diff --git a/.gitignore b/.gitignore index 301e238bb..24a76ca1b 100644 --- a/.gitignore +++ b/.gitignore @@ -4,4 +4,3 @@ build/ *.pyc __pycache__ .DS_Store -/locales/ diff --git a/locales/.gitignore b/locales/.gitignore new file mode 100644 index 000000000..cd1f2c943 --- /dev/null +++ b/locales/.gitignore @@ -0,0 +1 @@ +*.mo diff --git a/locales/ar/LC_MESSAGES/messages.po b/locales/ar/LC_MESSAGES/messages.po new file mode 100644 index 000000000..8f2670112 --- /dev/null +++ b/locales/ar/LC_MESSAGES/messages.po @@ -0,0 +1,26796 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# Monzer Ghannam , 2022. +# Youcef Guenaoua , 2024. +# Mohamed Brahimi , 2025. +# HAMDI KHALID , 2025. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: 2025-12-15 04:00+0000\n" +"Last-Translator: HAMDI KHALID \n" +"Language-Team: Arabic \n" +"Language: ar\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=6; plural=n==0 ? 0 : n==1 ? 1 : n==2 ? 2 : n%100>=3 " +"&& n%100<=10 ? 3 : n%100>=11 ? 4 : 5;\n" +"X-Generator: Weblate 5.15-dev\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "ساهم في هذا الدليل" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "قراءة الدليل وإبداء الرأي" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "" + +#: ../source/contribute.rst:14 +msgid "Translating the guide" +msgstr "" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "" + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "" + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "" + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "غير مكتمل" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "" + +#: ../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 +msgid "What is a source distribution?" +msgstr "" + +#: ../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 +msgid "What about eggs?" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python setup.py install``" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python -m pip install --editable .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:104 +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr "" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +msgid "Complete" +msgstr "" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +msgid "Versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +msgid "Calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +msgid "Other schemes" +msgstr "" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 ../source/flow.rst:143 +msgid "" +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../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 :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +msgid "Installed Project" +msgstr "" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +msgid "Project Root Directory" +msgstr "" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "" + +#: ../source/glossary.rst:257 +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:260 +msgid "Pyproject Metadata" +msgstr "" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +msgid "Pyproject Metadata Key" +msgstr "" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "" + +#: ../source/glossary.rst:344 +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:348 +msgid "Root License Directory" +msgstr "" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +msgid "Wheel Project" +msgstr "" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "" +"https://files.pythonhosted.org/packages/eb/" +"45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" +"sampleproject-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "" +"https://files.pythonhosted.org/packages/56/0a/" +"178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" +"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +msgid "" +"https://files.pythonhosted.org/packages/" +"63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" +"sampleproject_nomura-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +msgid "Creating the package" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +msgid "``pyproject.toml``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +msgid "Installing the package with ``pipx``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +msgid "Conclusion" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +msgid "1. Install twine" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +msgid "Dropping a Python version" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:108 +msgid "openSUSE" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:118 +msgid "Debian/Ubuntu and derivatives" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +msgid "Install packages in a virtual environment using pip and venv" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +msgid "Install packages using pip" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +msgid "Install extras" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +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/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python -m build``" +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:126 +msgid "``python -m build --no-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:127 +msgid "``python -m pip install --no-build-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../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 "" +"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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +msgid "Installation" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:233 +msgid "``appveyor-sample/build.cmd``" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:5 +msgid "Tool recommendations" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +msgid "Installing packages" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +msgid "Building distributions" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:313 +msgid "setuptools" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:317 +msgid "uv-build" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "GitHub" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +msgid "`Kivy `_" +msgstr "" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "Subdirectory name" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +msgid "``licenses``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*object*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Schema version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "examples" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "version\\_info" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*number*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**implementation**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**flags**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**headers**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +msgid "Package Building" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +msgid ":ref:`Version `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +msgid "``toml``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +msgid "``dependency_groups``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +msgid "Installers" +msgstr "" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +msgid "Reference implementation in Python" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +msgid "Names and normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +msgid "Name normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +msgid "Project Status Markers" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +msgid "Installer semantics: none." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +msgid "Installer semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +msgid "``deprecated``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +msgid "``pylock.toml`` Specification" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +msgid "``lock-version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +msgid "**Required?**: yes" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +msgid "``environments``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +msgid "``dependency-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +msgid "``[[packages]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +msgid "``packages.version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +msgid "The version of the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +msgid "``[[packages.dependencies]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +msgid "The time the file was uploaded." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +msgid "``packages.index``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +msgid "``import-names``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +msgid "Legacy specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +msgid "Examples:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +msgid "Example:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +msgid "PyPA schemas" +msgstr "" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +msgid "Python Description Formats" +msgstr "" + +#: ../source/specifications/section-reproducible-environments.rst:3 +msgid "Reproducible Environments" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +msgid "Normalized Names" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +msgid "HTML Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +msgid "Project List" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +msgid "Project Detail" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +msgid "JSON Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +msgid "Content-Types" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +msgid "Version + Format Selection" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +msgid "Definitions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +msgid "Version scheme" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +msgid "Pre-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +msgid "Version epochs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +msgid "Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +msgid "Integer Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +msgid "Version exclusion" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +msgid "Well-known Project URLs in Metadata" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +msgid "Label normalization" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +msgid "Normalized" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"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/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "" + +#: ../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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "" + +#: ../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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" diff --git a/locales/ars/LC_MESSAGES/messages.po b/locales/ars/LC_MESSAGES/messages.po new file mode 100644 index 000000000..d1ce516c3 --- /dev/null +++ b/locales/ars/LC_MESSAGES/messages.po @@ -0,0 +1,26789 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# Monzer Ghannam , 2022. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: Automatically generated\n" +"Language-Team: none\n" +"Language: ars\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "" + +#: ../source/contribute.rst:14 +msgid "Translating the guide" +msgstr "" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "" + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "" + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "" + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "" + +#: ../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 +msgid "What is a source distribution?" +msgstr "" + +#: ../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 +msgid "What about eggs?" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python setup.py install``" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python -m pip install --editable .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:104 +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr "" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +msgid "Complete" +msgstr "" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +msgid "Versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +msgid "Calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +msgid "Other schemes" +msgstr "" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 ../source/flow.rst:143 +msgid "" +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../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 :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +msgid "Installed Project" +msgstr "" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +msgid "Project Root Directory" +msgstr "" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "" + +#: ../source/glossary.rst:257 +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:260 +msgid "Pyproject Metadata" +msgstr "" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +msgid "Pyproject Metadata Key" +msgstr "" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "" + +#: ../source/glossary.rst:344 +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:348 +msgid "Root License Directory" +msgstr "" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +msgid "Wheel Project" +msgstr "" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "" +"https://files.pythonhosted.org/packages/eb/" +"45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" +"sampleproject-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "" +"https://files.pythonhosted.org/packages/56/0a/" +"178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" +"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +msgid "" +"https://files.pythonhosted.org/packages/" +"63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" +"sampleproject_nomura-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +msgid "Creating the package" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +msgid "``pyproject.toml``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +msgid "Installing the package with ``pipx``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +msgid "Conclusion" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +msgid "1. Install twine" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +msgid "Dropping a Python version" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:108 +msgid "openSUSE" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:118 +msgid "Debian/Ubuntu and derivatives" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +msgid "Install packages in a virtual environment using pip and venv" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +msgid "Install packages using pip" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +msgid "Install extras" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +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/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python -m build``" +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:126 +msgid "``python -m build --no-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:127 +msgid "``python -m pip install --no-build-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../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 "" +"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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +msgid "Installation" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:233 +msgid "``appveyor-sample/build.cmd``" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:5 +msgid "Tool recommendations" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +msgid "Installing packages" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +msgid "Building distributions" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:313 +msgid "setuptools" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:317 +msgid "uv-build" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +msgid "`Kivy `_" +msgstr "" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "Subdirectory name" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +msgid "``licenses``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*object*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Schema version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "examples" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "version\\_info" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*number*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**implementation**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**flags**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**headers**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +msgid "Package Building" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +msgid ":ref:`Version `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +msgid "``toml``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +msgid "``dependency_groups``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +msgid "Installers" +msgstr "" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +msgid "Reference implementation in Python" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +msgid "Names and normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +msgid "Name normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +msgid "Project Status Markers" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +msgid "Installer semantics: none." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +msgid "Installer semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +msgid "``deprecated``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +msgid "``pylock.toml`` Specification" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +msgid "``lock-version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +msgid "**Required?**: yes" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +msgid "``environments``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +msgid "``dependency-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +msgid "``[[packages]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +msgid "``packages.version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +msgid "The version of the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +msgid "``[[packages.dependencies]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +msgid "The time the file was uploaded." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +msgid "``packages.index``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +msgid "``import-names``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +msgid "Legacy specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +msgid "Examples:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +msgid "Example:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +msgid "PyPA schemas" +msgstr "" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +msgid "Python Description Formats" +msgstr "" + +#: ../source/specifications/section-reproducible-environments.rst:3 +msgid "Reproducible Environments" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +msgid "Normalized Names" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +msgid "HTML Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +msgid "Project List" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +msgid "Project Detail" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +msgid "JSON Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +msgid "Content-Types" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +msgid "Version + Format Selection" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +msgid "Definitions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +msgid "Version scheme" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +msgid "Pre-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +msgid "Version epochs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +msgid "Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +msgid "Integer Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +msgid "Version exclusion" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +msgid "Well-known Project URLs in Metadata" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +msgid "Label normalization" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +msgid "Normalized" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"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/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "" + +#: ../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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "" + +#: ../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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" diff --git a/locales/cs/LC_MESSAGES/messages.po b/locales/cs/LC_MESSAGES/messages.po new file mode 100644 index 000000000..d6faf4cae --- /dev/null +++ b/locales/cs/LC_MESSAGES/messages.po @@ -0,0 +1,26800 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# Luky12568 , 2025. +# Karolína Wallenfelsová , 2025. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: 2025-10-16 23:52+0000\n" +"Last-Translator: Karolína Wallenfelsová \n" +"Language-Team: Czech \n" +"Language: cs\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=((n==1) ? 0 : (n>=2 && n<=4) ? 1 : 2);\n" +"X-Generator: Weblate 5.14-dev\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "Přispějte této příručce" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "|PyPUG| vítá přispěvatele! Je hodně cest jak přispět, například:" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "Čtení příručky a zpětná vazba" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "Kontrolování nových příspěvků" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "Psaní nového obsahu" + +#: ../source/contribute.rst:14 +#, fuzzy +#| msgid "Translate the guide" +msgid "Translating the guide" +msgstr "Přeložte tuto příručku" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" +"Většina práce na |PyPUG| zaujímá místo na `repozitáři tohoto projektu na " +"GitHub`__. Pro započnutí, podívejte se na seznam `otevřených potíží`__ a " +"`žádostí o sloučení`__. Pokud plánujete na napsání nebo upravení příručky, " +"přečtěte si prosím :ref:`stylovou příručku `." + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" +"Přispěním na |PyPUG|, jste očekávání se řídit `pravidla chování`__ PSF." + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "" + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "" + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "" + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "Nedokončené" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "" + +#: ../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 +msgid "What is a source distribution?" +msgstr "" + +#: ../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 +msgid "What about eggs?" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python setup.py install``" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python -m pip install --editable .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:104 +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr "" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +msgid "Complete" +msgstr "" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +msgid "Versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +msgid "Calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +msgid "Other schemes" +msgstr "" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 ../source/flow.rst:143 +msgid "" +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../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 :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +msgid "Installed Project" +msgstr "" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +msgid "Project Root Directory" +msgstr "" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "" + +#: ../source/glossary.rst:257 +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:260 +msgid "Pyproject Metadata" +msgstr "" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +msgid "Pyproject Metadata Key" +msgstr "" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "" + +#: ../source/glossary.rst:344 +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:348 +msgid "Root License Directory" +msgstr "" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +msgid "Wheel Project" +msgstr "" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "" +"https://files.pythonhosted.org/packages/eb/" +"45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" +"sampleproject-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "" +"https://files.pythonhosted.org/packages/56/0a/" +"178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" +"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +msgid "" +"https://files.pythonhosted.org/packages/" +"63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" +"sampleproject_nomura-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +msgid "Creating the package" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +msgid "``pyproject.toml``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +msgid "Installing the package with ``pipx``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +msgid "Conclusion" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +msgid "1. Install twine" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +msgid "Dropping a Python version" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:108 +msgid "openSUSE" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:118 +msgid "Debian/Ubuntu and derivatives" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +msgid "Install packages in a virtual environment using pip and venv" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +msgid "Install packages using pip" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +msgid "Install extras" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +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/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python -m build``" +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:126 +msgid "``python -m build --no-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:127 +msgid "``python -m pip install --no-build-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../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 "" +"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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +msgid "Installation" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:233 +msgid "``appveyor-sample/build.cmd``" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:5 +msgid "Tool recommendations" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +msgid "Installing packages" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +msgid "Building distributions" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:313 +msgid "setuptools" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:317 +msgid "uv-build" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +msgid "`Kivy `_" +msgstr "" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "Subdirectory name" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +msgid "``licenses``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*object*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Schema version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "examples" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "version\\_info" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*number*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**implementation**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**flags**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**headers**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +msgid "Package Building" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +msgid ":ref:`Version `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +msgid "``toml``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +msgid "``dependency_groups``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +msgid "Installers" +msgstr "" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +msgid "Reference implementation in Python" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +msgid "Names and normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +msgid "Name normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +msgid "Project Status Markers" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +msgid "Installer semantics: none." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +msgid "Installer semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +msgid "``deprecated``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +msgid "``pylock.toml`` Specification" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +msgid "``lock-version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +msgid "**Required?**: yes" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +msgid "``environments``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +msgid "``dependency-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +msgid "``[[packages]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +msgid "``packages.version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +msgid "The version of the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +msgid "``[[packages.dependencies]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +msgid "The time the file was uploaded." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +msgid "``packages.index``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +msgid "``import-names``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +msgid "Legacy specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +msgid "Examples:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +msgid "Example:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +msgid "PyPA schemas" +msgstr "" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +msgid "Python Description Formats" +msgstr "" + +#: ../source/specifications/section-reproducible-environments.rst:3 +msgid "Reproducible Environments" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +msgid "Normalized Names" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +msgid "HTML Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +msgid "Project List" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +msgid "Project Detail" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +msgid "JSON Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +msgid "Content-Types" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +msgid "Version + Format Selection" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +msgid "Definitions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +msgid "Version scheme" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +msgid "Pre-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +msgid "Version epochs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +msgid "Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +msgid "Integer Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +msgid "Version exclusion" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +msgid "Well-known Project URLs in Metadata" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +msgid "Label normalization" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +msgid "Normalized" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"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/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "" + +#: ../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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "" + +#: ../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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" diff --git a/locales/da/LC_MESSAGES/messages.po b/locales/da/LC_MESSAGES/messages.po new file mode 100644 index 000000000..c55f56e69 --- /dev/null +++ b/locales/da/LC_MESSAGES/messages.po @@ -0,0 +1,26794 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# Philip Mallegol-Hansen , 2025. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: 2025-10-09 04:07+0000\n" +"Last-Translator: Philip Mallegol-Hansen \n" +"Language-Team: Danish \n" +"Language: da\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=2; plural=n != 1;\n" +"X-Generator: Weblate 5.14-dev\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "Bidrag til denne guide" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "" +"Bidrag til denne |PyPUG| er velkomne! Der er mange måder at hjælpe til, " +"blandt andet:" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "Læs guiden og giv feedback" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "Review af nye bidrag" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "Revidering af eksisterende indhold" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "" + +#: ../source/contribute.rst:14 +msgid "Translating the guide" +msgstr "" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "" + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "" + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "" + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "" + +#: ../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 +msgid "What is a source distribution?" +msgstr "" + +#: ../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 +msgid "What about eggs?" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python setup.py install``" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python -m pip install --editable .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:104 +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr "" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +msgid "Complete" +msgstr "" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +msgid "Versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +msgid "Calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +msgid "Other schemes" +msgstr "" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 ../source/flow.rst:143 +msgid "" +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../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 :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +msgid "Installed Project" +msgstr "" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +msgid "Project Root Directory" +msgstr "" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "" + +#: ../source/glossary.rst:257 +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:260 +msgid "Pyproject Metadata" +msgstr "" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +msgid "Pyproject Metadata Key" +msgstr "" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "" + +#: ../source/glossary.rst:344 +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:348 +msgid "Root License Directory" +msgstr "" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +msgid "Wheel Project" +msgstr "" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "" +"https://files.pythonhosted.org/packages/eb/" +"45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" +"sampleproject-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "" +"https://files.pythonhosted.org/packages/56/0a/" +"178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" +"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +msgid "" +"https://files.pythonhosted.org/packages/" +"63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" +"sampleproject_nomura-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +msgid "Creating the package" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +msgid "``pyproject.toml``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +msgid "Installing the package with ``pipx``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +msgid "Conclusion" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +msgid "1. Install twine" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +msgid "Dropping a Python version" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:108 +msgid "openSUSE" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:118 +msgid "Debian/Ubuntu and derivatives" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +msgid "Install packages in a virtual environment using pip and venv" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +msgid "Install packages using pip" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +msgid "Install extras" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +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/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python -m build``" +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:126 +msgid "``python -m build --no-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:127 +msgid "``python -m pip install --no-build-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../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 "" +"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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +msgid "Installation" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:233 +msgid "``appveyor-sample/build.cmd``" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:5 +msgid "Tool recommendations" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +msgid "Installing packages" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +msgid "Building distributions" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:313 +msgid "setuptools" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:317 +msgid "uv-build" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +msgid "`Kivy `_" +msgstr "" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "Subdirectory name" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +msgid "``licenses``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*object*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Schema version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "examples" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "version\\_info" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*number*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**implementation**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**flags**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**headers**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +msgid "Package Building" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +msgid ":ref:`Version `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +msgid "``toml``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +msgid "``dependency_groups``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +msgid "Installers" +msgstr "" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +msgid "Reference implementation in Python" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +msgid "Names and normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +msgid "Name normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +msgid "Project Status Markers" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +msgid "Installer semantics: none." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +msgid "Installer semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +msgid "``deprecated``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +msgid "``pylock.toml`` Specification" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +msgid "``lock-version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +msgid "**Required?**: yes" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +msgid "``environments``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +msgid "``dependency-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +msgid "``[[packages]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +msgid "``packages.version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +msgid "The version of the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +msgid "``[[packages.dependencies]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +msgid "The time the file was uploaded." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +msgid "``packages.index``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +msgid "``import-names``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +msgid "Legacy specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +msgid "Examples:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +msgid "Example:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +msgid "PyPA schemas" +msgstr "" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +msgid "Python Description Formats" +msgstr "" + +#: ../source/specifications/section-reproducible-environments.rst:3 +msgid "Reproducible Environments" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +msgid "Normalized Names" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +msgid "HTML Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +msgid "Project List" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +msgid "Project Detail" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +msgid "JSON Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +msgid "Content-Types" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +msgid "Version + Format Selection" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +msgid "Definitions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +msgid "Version scheme" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +msgid "Pre-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +msgid "Version epochs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +msgid "Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +msgid "Integer Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +msgid "Version exclusion" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +msgid "Well-known Project URLs in Metadata" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +msgid "Label normalization" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +msgid "Normalized" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"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/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "" + +#: ../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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "" + +#: ../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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" diff --git a/locales/de/LC_MESSAGES/messages.po b/locales/de/LC_MESSAGES/messages.po new file mode 100644 index 000000000..0690838d0 --- /dev/null +++ b/locales/de/LC_MESSAGES/messages.po @@ -0,0 +1,27138 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# jkoan , 2022. +# Marlon , 2022. +# Pixel-Master , 2022, 2024. +# Justin Nogossek , 2022. +# Jean-Luc Tibaux , 2023, 2025. +# TheescapedShadow , 2024. +# Hartmut Goebel , 2024. +# Emr , 2024. +# Carsten Gerlach , 2025. +# chrysle , 2025. +# Norah-14 , 2025. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: 2025-10-28 15:43+0000\n" +"Last-Translator: Norah-14 \n" +"Language-Team: German \n" +"Language: de\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=2; plural=n != 1;\n" +"X-Generator: Weblate 5.14.1-dev\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "Zu diesem Handbuch beitragen" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "" +"Der |PyPUG| begrüßt Mitwirkende! Es gibt viele Möglichkeiten, zu helfen, " +"einschließlich:" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "Den Leitfaden zu lesen und Feedback geben" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "Bewerte neue Beiträge" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "Überarbeitung bestehender Inhalte" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "Neue Inhalte schreiben" + +#: ../source/contribute.rst:14 +#, fuzzy +#| msgid "Translate the guide" +msgid "Translating the guide" +msgstr "Übersetzen Sie den Leitfaden" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" +"Die meiste Arbeit am |PyPUG| findet im `GitHub-Repository des Projekts`__ " +"statt. Sehen Sie sich zunächst die Liste der `Issues`__ und `Pull " +"Requests`__ an. Wenn Sie vorhaben, den Leitfaden zu schreiben oder zu " +"bearbeiten, lesen Sie bitte den :ref:`Styleguide `." + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" +"Durch den Beitrag zum |PyPUG| wird erwartet, dass Sie dem `Code of " +"Conduct`__ der PSF folgen." + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "Dokumentationstypen" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" +"Dieses Projekt besteht aus vier verschiedenen Dokumentationstypen mit " +"spezifischen Zwecken. Wenn Sie neue Ergänzungen zum Projekt vorschlagen, " +"wählen Sie bitte den entsprechenden Dokumentationstyp aus." + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "Tutorials" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" +"Der Schwerpunkt von Tutorials liegt darauf, dem Leser durch das Erreichen " +"eines Ziels neue Konzepte beizubringen. Es handelt sich um Schritt-für-" +"Schritt-Anleitungen. Sie enthalten keine überflüssigen Warnungen oder " +"Informationen. `example tutorial-style document`_." + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "Leitfäden" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" +"Leitfäden sind auf das Erreichen einer spezifischen Aufgabe konzentriert und " +"können ein gewisses Vorwissen annehmen. Sie sind ähnlich wie Tutorials, " +"haben aber einen engen und klaren Fokus. Leitfäden können zusätzliche " +"weiterführende Informationen bereitstellen, sofern diese benötigt werden. " +"Sie können auch mehrere Ansätze erläutern, um das gleiche Problem zu " +"lösen. :doc:`example guide-style document `." + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "Diskussionen" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" +"Diskussionen konzentrieren sich auf Verständnis und Information. Sie " +"erkunden ein bestimmtes Thema ohne ein spezifisches Ziel vor Augen zu " +"haben.:doc:`example discussion-style document `." + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "Die Spezifikationen" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" +"Die Spezifikationen sind Referenz Dokumentation, dass der Schwerpunkt lag " +"auf der umfassenden Dokumentation einer vereinbarten Schnittstelle für die " +"Interoperabilität zwischen Verpackungstools. :doc:`example specification-" +"style document `." + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "Die Übersetzungen" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" +"Wir verwenden `Weblate`_ um die Übersetzungen dieses Projekt zu verwalten. " +"Bitte besuchen Sie das Projekt `packaging.python.org`_ auf Weblate " +"beizutragen." + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" +"Wenn Sie feststellen, dass Sie einen Fehler in den Übersetzungen bemerken; " +"bitte öffnen Sie ein Issue auf `GitHub`_." + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" +"Alle Übersetzungen dieses Leitfadens müssen der `reStructuredText-Syntax " +"`_ folgen." + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "Eine Sprache hinzufügen" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" +"Wenn Sie Ihre Sprache nicht sehen auf `packaging.python.org`_ können, " +"klicken Sie auf den Button :guilabel:`Start new translation` ganz unten in " +"der Sprachenliste und fügen Sie Ihre Sprache hinzu." + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "Der reStructuredText-Syntax folgen" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" +"Wenn Sie nicht mit der Syntax von reStructuredText (RST) vertraut sind, " +"bitte lesen Sie `diese Anleitung `_ bevor Sie auf Weblate " +"übersetzen." + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "**Übersetzen Sie den Text in der Referenz nicht direkt**" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "" +"Wenn Sie Text in einem Verweis übersetzen, übersetzen Sie ihn bitte nicht " +"direkt." + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "Falsch: Folgenden Text direkt übersetzen:" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" +"Richtig: Folgenden Text übersetzen und den ursprünglichen Verweis hinzufügen:" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "Den Leitfaden lokal erstellen" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" +"Obwohl zum Mitwirken nicht unbedingt notwendig, könnte es sinnvoll sein, den " +"Leitfaden lokal zu bauen, um Ihre Änderungen zu testen. Dazu brauchen Sie:" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" +":doc:`Nox `. Sie können nox mit ``pip`` installieren oder " +"aktualisieren:" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" +"Python 3.11. Unsere Bau-Skripte sind normalerweise lediglich gegen Python " +"3.11 getestet. Konsultieren Sie die :doc:`Hitchhiker's Guide to Python " +"Installations-Anleitung ` um Python 3.11 " +"auf Ihrem Betriebssystem zu installieren." + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" +"Um den Leitfaden zu bauen, führen Sie den folgenden Shell-Befehl im " +"Wurzelverzeichnis des Projektes aus:" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" +"Nach Beendigung des Prozesses finden sie die HTML-Seiten im Verzeichnis ``./" +"build/html``. Sie können die Datei ``index.html`` öffnen, um den Leitfaden " +"im Webbrowser zu betrachten, aber es wird empfohlen sie mit einem HTTP-" +"Server auszuliefern." + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" +"Der Bau-Prozess mit anschließender Auslieferung via HTTP wird über folgenden " +"Befehl angestoßen:" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "Der Leitfaden ist dann über http://localhost:8000 aufrufbar." + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "Wo der Leitfaden deployt wird" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" +"Der Leitfaden wird via ReadTheDocs deployt und die Konfiguration liegt unter " +"https://readthedocs.org/projects/python-packaging-user-guide/. Er wird über " +"eine eigene Domain samt Frontend durch Fast.ly ausgeliefert." + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "Stil-Leitfaden" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" +"Der Stil-Leitfaden enthält Empfehlungen, wie die |PyPUG| verfasst werden " +"soll. Bevor Sie mit dem Schreiben anfangen, lesen Sie ihn bitte. Indem sie " +"im folgen, tragen Ihre Beiträge zu einem zusammenhängenden Ganzen bei und " +"können unkomplizierter angenommen werden." + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "Zweck der Anleitung" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" +"Die |PyPUG| soll als zuverlässige Anleitung für das Paketieren, " +"Veröffentlichen und Installieren von Python-Projekten mittels aktueller " +"Werkzeuge dienen." + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "Geltungsbereich" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" +"Der Leitfaden ist dazu da, Fragen zu beantworten und Probleme mit akkuraten " +"und fokussierten Empfehlungen zu lösen." + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" +"Er soll nicht umfassend sein oder die Dokumentation der individuellen " +"Projekte ersetzen. Beispielsweise hat pip Dutzende von Befehlen, Optionen " +"und Einstellungen. Die Dokumentation von pip beschreibt dies alles im " +"Detail, während dieser Leitfaden nur die Teile der Funktionalität von pip " +"erläutert, die für das Lösen der spezifischen Aufgaben notwendig sind." + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "Zielgruppe" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "" +"Die Zielgruppe des Leitfadens ist jeder, der Python über Pakete benutzt." + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "Vergessen Sie nicht, dass die Python-Community groß und einladend ist." + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" +"Behalten Sie im Hinterkopf, dass nicht alle, die Python benutzen, sich als " +"Programmierer verstehen. Die Zielgruppe enthält Astronomen, Maler oder " +"Studenten genauso wie professionelle Software-Entwickler." + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "Sprache und Ton" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" +"Versuchen Sie diesen Leitfaden mit einer Sprache zu schreiben, die nahbar " +"und bescheiden klingt, auch wenn Sie über alles Bescheid wissen." + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" +"Stellen Sie sich vor, Sie arbeiten an einem Python-Projekt mit jemandem, den " +"Sie als klug und talentiert kennen. Sie mögen es, mit ihm zu arbeiten, und " +"andersherum gleichermaßen. Diese Person fragt Sie etwas und Sie kennen die " +"Antwort. Wie antworten Sie? *Das* ist wie Sie den Leitfaden schreiben " +"sollten." + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" +"Hier ein kurzer Tipp zur Überprüfung: versuchen Sie, es laut zu lesen, um " +"ein Gefühl für Sprache und Tonfall ihres Geschriebenen zu erhalten. Klingt " +"es wie etwas, das Sie sagen würden, oder als würden Sie es vorspielen oder " +"eine Rede halten? Benutzen Sie gerne Verkürzungen und sorgen Sie sich nicht " +"um die Einhaltung von pingeligen Grammatik-Regeln. Hiermit erhalten Sie die " +"Erlaubnis, einen Satz mit einer Präposition zu beenden, wenn das so von " +"Ihnen gewünscht ist." + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" +"Der Tonfall sollte an die Ernsthaftigkeit und Komplexität des Themas " +"angepasst werden. Wenn Sie ein einführendes Tutorial schreiben, ist es OK, " +"einen Witz zu machen, aber wenn Sie eine wichtige Sicherheits-Empfehlung " +"behandeln, sollten Sie das vielleicht lieber ganz lassen." + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "Konventionen und Mechanik" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "**Dem Leser schreiben**" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" +"Wenn Du Empfehlungen oder Schritte zu ergreifen schilderst, wende dich bitte " +"an den Leser als *Du* oder verwende die Passivform." + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "Falsch: Zum Installieren macht der Benutzer…" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "Richtig: Du kannst es installieren, indem.." + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "Richtig: Zum Installieren, muss …" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "**Annahmen zur Ausgangssituation**" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" +"Vermeide unbegründete Annahmen zu machen. Das Lesen im Web bedeutet, dass " +"jede Seite der Anleitung die erste Seite der Anleitung sein kann, die der " +"Leser je sieht. Wenn Du Annahme zur Ausgangssituation machst, dann " +"beschreibe diese bitte." + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "**Umfangreiches Querverweisen**" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" +"Das erste Mal, wenn Du ein Werkzeug oder eine Praxis erwähnst, referenziere " +"bitte den zugehörigen Dokumentations-Abschnitt, oder alternativ ein anderes " +"relevante Dokument. Bitte erspare dem Leser die Suche nach Kontext." + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "**Respektiere Namenskonventionen**" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" +"Bitte verwende die bevorzugte Kapitalisierung bei der Benennung von " +"Werkzeugen, Websites, Menschen und anderen Nomen." + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "Falsch: Pip verwendet…" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "Richtig: pip verwendet.." + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "Falsch: ...auf github gehostet." + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "Richtig: ...auf GitHub gehostet." + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "**Nutze ein Geschlecht-neutralen Stil**" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" +"Oft werden Leser direkt angesprochen. Ansonsten verwenden sind " +"geschlechtsneutrale Pronomen zu verwenden, oder Pronomen vollständig zu " +"vermeiden." + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "Falsch: Ein Betreuer lädt die Datei hoch. Dann…" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "Richtig: Ein Betreuer lädt die Datei hoch. Dann…" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "Richtig: Ein Betreuer lädt die Datei hoch. Danach macht der Betreuer…" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "**Überschriften**" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "Falsch: Dinge, die Du über Python wissen solltest" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "Richtig: Dinge, die du über Python wissen solltest" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "*Nummern**" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" +"Im Hauptteil, schreiben sind Zahlen von eins bis neun als Wörter zu " +"schreiben. Für andere Zahlen oder Zahlen in Tabellen sind Ziffern zu " +"verwenden." + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "Bereitstellung von Python-Anwendungen" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "Seiten Status" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "Unvollständig" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "Letzte Überprüfung" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "24.08.2021" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "Überblick" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "Unterstützung mehrerer Hardwareplattformen" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "OS Pakete und Installationsprogramme" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" +"`Pynsist `__ ist ein Werkzeug, das Python-" +"Programme zusammen mit dem Python-Interpreter in ein einziges " +"Installationsprogramm auf der Basis von NSIS bündelt. In den meisten Fällen " +"erfordert das Verpacken nur, dass der Benutzer eine Version des Python-" +"Interpreters wählt und die Abhängigkeiten des Programms erklärt. Das Tool " +"lädt den angegebenen Python-Interpreter für Windows herunter und verpackt es " +"mit allen Abhängigkeiten in einem einzigen ausführbaren " +"Installationsprogramms." + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" +"Das installierte Programm kann von einer Verknüpfung gestartet werden, die " +"das Installationsprogramm zum Startmenü hinzufügt. Es verwendet einen Python " +"Interpreter, der in seinem Anwendungsverzeichnis installiert ist, unabhängig " +"von einer anderen Python-Installation auf dem Computer." + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" +"Ein großer Vorteil von Pynsist ist, dass die Windows Pakete unter Linux " +"gebaut werden können. Es gibt mehrere Beispiele für verschiedene Arten von " +"Programmen (Konsole, GUI) in der :any:`Dokumentation `. Das " +"Tool wird unter der MIT-Lizenz veröffentlicht." + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "Anwendungsbündel" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +#, fuzzy +msgid "Distribution package vs. import package" +msgstr "Distributionspaket" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +#, fuzzy +msgid "What's a distribution package?" +msgstr "Distributionspaket" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" +"Ein Distributionspaket ist ein Stück Software, das installiert werden kann. " +"Meistens ist das ein Synonym für \"Projekt\". Wenn Du ``pip pkg`` " +"installierst oder wenn Du ``dependencies = [\"pkg\"] ` schreibst in deinem " +"```pyproject.toml```, ``pkg``` ist der Name eines Distributionspakets. Wenn " +"PyPI_, die bekannteste zentralisierte Quelle für die Installation von Python " +"Bibliotheken und Tools zum Suchen genutzt, wird eine Liste von " +"Distributionspaketen als Ergebnisse zurückgegeben. Alternativ kann der " +"Begriff \"Distributionspaket\" verwendet werden, um eine bestimmte Datei zu " +"verweisen, die eine bestimmte Version eines Projekts enthält." + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "Was ist ein importierbares Paket?" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" +"Ein importierbares Paket ist ein Python-Modul. Wenn Sie ``import pkg`` oder " +"``from pkg import func``in Ihrem Code schreiben, ist ``pkg``der Name des " +"importierbaren Paketes. Genauer, importierbare Pakete sind spezielle Python-" +"Module, die Submodule enthalten können. Beispielsweise enthält das Paket " +"``numpy`` Module wie ``numpy.linalg`` und ``numpy.fft``. Für gewöhnlich ist " +"ein importierbares Paket ein Verzeichnis auf dem Dateisystem, das Module als " +"``.py``-Dateien und Submodule als Unterverzeichnisse enthält." + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" +"Sie können ein importierbares Paket nutzen, sobald sie das " +"Distributionspaket installiert haben, das es bereitstellt." + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" +"Was sind die Verbindungen zwischen Distributionspaketen und importierbaren " +"Paketen?" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" +"Meistens bietet ein Distributionspaket ein einziges Importpaket (oder " +"Nichtpaketmodul), mit einem passenden Namen. Zum Beispiel ```pip install " +"numpy`` ermöglicht ``Import numpy````." + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" +"Auf einem bestimmten Paketindex (wie PyPI) müssen Distributionspaketnamen " +"eindeutig sein. Andererseits haben Importpakete keine solche Anforderung. " +"Importpakete mit demselben Namen können durch mehrere Distributionspakete " +"bereitgestellt werden. Auch hier sind Forks ein häufiger Grund dafür." + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" +"Umgekehrt kann ein Verteilungspaket mehrere Importpakete liefern, obwohl " +"dies weniger häufig ist. Ein Beispiel ist das attrs_ Distributionspaket, das " +"sowohl ein `attrs`' Importpaket mit einer neueren API als auch ein `attr` " +"Importpaket mit einer älteren, aber unterstützten API bietet." + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "Wie unterscheiden sich Distributionspaketnamen und Importpaketnamen?" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" +"Importpakete sollten gültige Python-Kennzeichen haben, wie ihr Name " +"(die :ref:`genauen Regeln ` sind in der Python-" +"Dokumentation zu finden) [#non-identifier-mod-name]_. Insbesondere verwenden " +"sie Unterstriche ``_`` als Worttrenner und sind schreibungsabhängig." + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" +"Obwohl es technisch möglich ist, Pakete/Module zu importieren, die keine " +"gültige Python-Kennung als ihren Namen haben, mit :doc:`importlib " +"`, ist dies sehr selten und nicht zu empfehlen." + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "Entwurf" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "2025-?" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" +"Während PyPI und die Python Verpackungswerkzeuge wie :ref:`pip` die primären " +"Mittel zur Verteilung von Python Paketen sind, werden sie häufig auch als " +"Teil anderer Verpackungsökosysteme zur Verfügung gestellt. Diese " +"Umverpackungsbemühungen werden kollektiv als *downstream*-Verpackung " +"bezeichnet (Ihre eigenen Anstrengungen werden als *upstream*-Verpackung " +"bezeichnet), und beinhalten solche Projekte wie Linux-Distributionen, Conda, " +"Homebrew und MacPorts. Sie zielen im Allgemeinen auf eine verbesserte " +"Unterstützung für Anwendungsfälle, die nicht allein über Python-" +"Verpackungstools, wie native Integration mit einem bestimmten " +"Betriebssystem, oder eine sichere Kompatibilität mit bestimmten Versionen " +"von nicht-Python-Software handhabbar sind." + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" +"Diese Diskussion versucht, zu erklären, wie downstream Verpackungen in der " +"Regel durchgeführt werden, und welche zusätzlichen Herausforderungen " +"downstream Verpacker typischerweise gegenüberstehen. Es zielt darauf ab, " +"einige optionale Richtlinien zur Verfügung zu stellen, die Projektbetreuer " +"wählen können, um zu folgen, welche Hilfe die downstream Verpackung " +"*bedeutend* einfacher machen (ohne wesentliche Wartungsprobleme auf dem " +"upstream Projekt implizieren). Beachten Sie, dass dies kein All-oder " +"Nichtsdestoweniger-Vorschlag ist – alles, was vorgelagerte Betreuer tun " +"können, ist nützlich, auch wenn es nur ein kleiner Teil ist. Downstream-" +"Betreuer sind auch bereit, Patches vorzubereiten, um diese Probleme zu " +"lösen. Die Zusammenführung dieser Patches kann sehr hilfreich sein, da sie " +"die Notwendigkeit von unterschiedlichen Downstreams entfernt, dieselben " +"Patches zu tragen und wieder einzupflegen, und das Risiko, inkonsistente " +"Lösungen auf das gleiche Problem anzuwenden." + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" +"Die Schaffung einer guten Beziehung zwischen Software-Betreuer und " +"nachgeschalteten Paket-Nutzern kann gegenseitige Vorteile bringen. " +"Downstreams sind oft bereit, ihre Erfahrung, Zeit und Hardware zu teilen, um " +"Ihr Paket zu verbessern. Sie sind manchmal in einer besseren Position, um zu " +"sehen, wie Ihr Paket in der Praxis verwendet wird, und um Informationen über " +"seine Beziehungen zu anderen Paketen, die sonst erhebliche Anstrengungen " +"erfordern würde zu erhalten. Verpacker können oft Bugs finden, bevor Ihre " +"Benutzer sie in der Produktion treffen, bieten Bug-Berichte von guter " +"Qualität, und liefern Patches, wann immer sie können. So sind sie " +"regelmässig aktiv, um sicherzustellen, dass die von ihnen neu verteilten " +"Pakete für alle Kompatibilitätsprobleme aktualisiert werden, die entstehen, " +"wenn eine neue Python Version veröffentlicht wird." + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" +"Bitte beachten Sie, dass downstream Builds nicht nur eine binäre " +"Umverteilung umfassen, sondern auch Source Builds auf Anwendersystemen (z.B. " +"in Quell-ersten Distributionen wie Gentoo Linux)." + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "Bereitstellung vollständiger Quelldistributionen" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "Warum?" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" +"Die überwiegende Mehrheit der nachgeschalteten Paket-Nutzer bevorzugt Pakete " +"aus der Quelle zu bauen, anstatt die vorgefertigten binären Pakete zu " +"verwenden. In einigen Fällen ist die Verwendung von Quellen tatsächlich " +"erforderlich, damit das Paket in die Verteilung aufgenommen wird. Dies gilt " +"auch für reine Python-Pakete, die universelle wheels bieten. Die Gründe für " +"die Verwendung von Quellverteilungen können umfassen:" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "In der Lage zu sein, den Quellcode aller Pakete zu überprüfen." + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" +"In der Lage zu sein, die Testsuite zu betreiben und Dokumentation zu " +"erstellen." + +#: ../source/discussions/downstream-packaging.rst:66 +#, fuzzy +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" +"In der Lage zu sein, Patches leicht anzuwenden, einschliesslich Backporting " +"Commits aus dem Projekt-Repository und senden Patches zurück zum Projekt." + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" +"Auf einer bestimmten Plattform aufbauen zu können, die nicht von upstream " +"Builds abgedeckt ist." + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" +"In der Lage zu sein, für bestimmte Versionen von Systembibliotheken zu bauen." + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "Ein konsequenter Build-Prozess in allen Python Paketen." + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" +"Während es in der Regel möglich ist, Pakete aus einem Git-Repository zu " +"erstellen, gibt es einige wichtige Gründe, stattdessen eine statische " +"Archivdatei bereitzustellen:" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" +"Eine einzelne Datei wird oft effizienter, zuverlässiger und besser " +"unterstützt als z.B. mit einem Git-Klon. Dies kann Benutzern mit schlechter " +"Internet-Konnektivität helfen." + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" +"Downstreams verwenden oft Hashes, um die Authentizität von Quelldateien auf " +"nachfolgenden Builds zu überprüfen, die erfordern, dass sie im Laufe der " +"Zeit bitweise identisch bleiben. Aautomatisch generiert Git-Archive " +"garantieren dies zum Beispiel nicht, da sich die komprimierten Daten ändern " +"können, wenn gzip auf dem Server aktualisiert wird." + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" +"Archivdateien können gespiegelt werden, wodurch sowohl die up- als auch " +"downstream Bandbreiten-Nutzung verringert verwendet werden. Die eigentlichen " +"Builds können anschliessend in Firewall- oder Offline-Umgebungen ausgeführt " +"werden, die nur auf Quelldateien zugreifen können, die vom lokalen Spiegel " +"bereitgestellt oder früher umverteilt werden." + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" +"Die Veröffentlichung von Archivdateien kann sicherstellen, dass bei der " +"Erstellung des Quellarchivs alle Abhängigkeiten von " +"Versionsverwaltungssystem-Metadaten behoben werden. Automatisch generiert " +"Git-Archive überlassen zum Beispiel alle Informationen des Commit-Tags, was " +"zu falschen Versionsdetails in den resultierenden Builds führen könnte." + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "Verwenden Sie die Internetverbindung nicht während des Build-Prozesses" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" +"Downstream Builds werden häufig in sandboxed Umgebungen durchgeführt, die " +"nicht auf das Internet zugreifen können. Die Paketquellen werden in diese " +"Umgebung entpackt, und alle notwendigen Abhängigkeiten werden installiert." + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" +"Auch wenn dies nicht der Fall ist und Downloads sorgfältig authentifizieren " +"wurden, wird die Nutzung des Internets aus mehreren Gründen nicht empfohlen:" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" +"Die Internetverbindung kann instabil sein (z.B. durch schlechten Empfang) " +"oder unter vorübergehenden Problemen leiden, die den Prozess versagen oder " +"hängen lassen könnten." + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" +"Die Remote-Ressourcen können vorübergehend oder sogar dauerhaft nicht " +"verfügbar werden, wodurch der Aufbau nicht mehr möglich ist. Dies ist " +"besonders problematisch, wenn jemand eine alte Paketversion erstellen muss." + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" +"Die Remote-Ressourcen können sich ändern, wodurch der Build nicht " +"reproduzierbar ist." + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" +"Der Zugriff auf Remoteserver stellt ein Datenschutzproblem und ein " +"potenzielles Sicherheitsproblem dar, da es Informationen über das System zur " +"Erstellung des Pakets gibt." + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" +"Der Benutzer kann einen Dienst mit einem begrenzten Datenplan verwenden, in " +"dem unkontrollierter Internetzugang zusätzliche Gebühren oder andere " +"Unannehmlichkeiten zur Folge haben kann." + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "Den Paketbau mit System-Abhängigkeiten unterstützen" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" +"Manche Python-Projekte haben nicht-Python-Abhängigkeiten, etwa Bibliotheken " +"in C oder C++. Der Versuch, die System-Versionen dieser Abhängigkeiten bei " +"der Paketierung zu nutzen, kann in einigen Problemen für die Endnutzer " +"resultieren:" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" + +#: ../source/discussions/package-formats.rst:5 +#, fuzzy +#| msgid "Package Index" +msgid "Package Formats" +msgstr "Paketindex" + +#: ../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 "Distributionspaket" + +#: ../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 +msgid "What about eggs?" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python setup.py install``" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 +#, fuzzy +#| msgid "Documentation types" +msgid "Recommendation" +msgstr "Dokumentationstypen" + +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python -m pip install .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python -m pip install --editable .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:104 +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:146 +#, fuzzy +msgid "``install_headers``" +msgstr "Betreuer" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr "" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +#, fuzzy +#| msgid "Incomplete" +msgid "Complete" +msgstr "Unvollständig" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +msgid "Versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +msgid "Calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +msgid "Other schemes" +msgstr "" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 ../source/flow.rst:143 +msgid "" +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../source/glossary.rst:3 +msgid "Glossary" +msgstr "" + +#: ../source/glossary.rst:8 +msgid "Binary Distribution" +msgstr "Binärdistribution" + +#: ../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 :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../source/glossary.rst:44 +msgid "Built Distribution" +msgstr "Gebaute Distribution" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +#, fuzzy +msgid "Distribution Archive" +msgstr "Distributionspaket" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "Distributionspaket" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "Ei" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "Erweiterungsmodul" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "Paket importieren" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +#, fuzzy +msgid "Installed Project" +msgstr "Betreuer" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "Lizensausdruck" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "Modul" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "Paketindex" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "Pro Projekt Index" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +msgid "Project Root Directory" +msgstr "" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "Pures Modul" + +#: ../source/glossary.rst:257 +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:260 +msgid "Pyproject Metadata" +msgstr "" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +msgid "Pyproject Metadata Key" +msgstr "" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "" + +#: ../source/glossary.rst:344 +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:348 +msgid "Root License Directory" +msgstr "" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "Quellenarchiv" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "Spezifikation der Version" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "" + +#: ../source/glossary.rst:411 +#, fuzzy +msgid "Wheel" +msgstr "Wheel" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +#, fuzzy +#| msgid "Per Project Index" +msgid "Wheel Project" +msgstr "Pro Projekt Index" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "" +"https://files.pythonhosted.org/packages/eb/" +"45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" +"sampleproject-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "" +"https://files.pythonhosted.org/packages/56/0a/" +"178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" +"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +msgid "" +"https://files.pythonhosted.org/packages/" +"63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" +"sampleproject_nomura-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +#, fuzzy +msgid "Creating the package" +msgstr "Betreuer" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +msgid "``pyproject.toml``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +#, fuzzy +msgid "Installing the package with ``pipx``" +msgstr "Betreuer" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +msgid "Conclusion" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +#, fuzzy +msgid "1. Install twine" +msgstr "Betreuer" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +msgid "Dropping a Python version" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 +#, fuzzy +#| msgid "Package Index" +msgid "Package upload" +msgstr "Paketindex" + +#: ../source/guides/hosting-your-own-index.rst:64 +msgid "PyPI fall-through [2]_" +msgstr "" + +#: ../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 "" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:105 +#, fuzzy +#| msgid "Maintainer" +msgid "unmaintained" +msgstr "Betreuer" + +#: ../source/guides/installing-scientific-packages.rst:5 +msgid "Installing scientific packages" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:8 +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." +msgstr "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:108 +msgid "openSUSE" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:118 +msgid "Debian/Ubuntu and derivatives" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +msgid "Install packages in a virtual environment using pip and venv" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +msgid "Install packages using pip" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +msgid "Install extras" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +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/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python -m build``" +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +#, fuzzy +msgid ":ref:`distributing-packages`" +msgstr "Distributionspaket" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:126 +msgid "``python -m build --no-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:127 +msgid "``python -m pip install --no-build-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +#, fuzzy +#| msgid "Extension Module" +msgid "Extension module lifecycle" +msgstr "Erweiterungsmodul" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../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 "" +"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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +msgid "Installation" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:233 +msgid "``appveyor-sample/build.cmd``" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:5 +msgid "Tool recommendations" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +msgid "Installing packages" +msgstr "Installieren von Paketen" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +#, fuzzy +msgid "Building distributions" +msgstr "Distributionspaket" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:313 +msgid "setuptools" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:317 +msgid "uv-build" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "Paketierung" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +msgid "`Kivy `_" +msgstr "" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "Details" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "Subdirectory name" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +msgid "``licenses``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*object*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Schema version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "examples" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "version\\_info" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*number*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Documentation types" +msgid "**implementation**" +msgstr "Dokumentationstypen" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**flags**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Extension Module" +msgid "extensions" +msgstr "Erweiterungsmodul" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**headers**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "Betreuer" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +#, fuzzy +#| msgid "Package Index" +msgid "Package Building" +msgstr "Paketindex" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +#, fuzzy +#| msgid "Documentation types" +msgid "Reference Implementation" +msgstr "Dokumentationstypen" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +#, fuzzy +#| msgid "Version Specifier" +msgid ":ref:`Version `" +msgstr "Spezifikation der Version" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +msgid "``toml``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +msgid "``dependency_groups``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +#, fuzzy +#| msgid "packaging" +msgid "package" +msgstr "Paketierung" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +#, fuzzy +#| msgid "Documentation types" +msgid "Implementation Notes" +msgstr "Dokumentationstypen" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +#, fuzzy +msgid "Installers" +msgstr "Betreuer" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +#, fuzzy +#| msgid "Documentation types" +msgid "Reference implementation in Python" +msgstr "Dokumentationstypen" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +msgid "Names and normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +msgid "Name normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +#, fuzzy +msgid "``manylinux``" +msgstr "Betreuer" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +#, fuzzy +msgid "``musllinux``" +msgstr "Betreuer" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +msgid "Project Status Markers" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +msgid "Installer semantics: none." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +#, fuzzy +msgid "Installer semantics:" +msgstr "Betreuer" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +msgid "``deprecated``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +#, fuzzy +#| msgid "Specifications" +msgid "``pylock.toml`` Specification" +msgstr "Die Spezifikationen" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +msgid "``lock-version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +msgid "**Required?**: yes" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +msgid "``environments``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +msgid "``dependency-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +#, fuzzy +#| msgid "packaging" +msgid "``[[packages]]``" +msgstr "Paketierung" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +msgid "``packages.version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +#, fuzzy +msgid "The version of the package." +msgstr "Betreuer" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +msgid "``[[packages.dependencies]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +#, fuzzy +#| msgid "Where the guide is deployed" +msgid "The time the file was uploaded." +msgstr "Wo der Leitfaden deployt wird" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +#, fuzzy +#| msgid "Package Index" +msgid "``packages.index``" +msgstr "Paketindex" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +msgid "``import-names``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +#, fuzzy +msgid "``maintainers``" +msgstr "Betreuer" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +#, fuzzy +#| msgid "Specifications" +msgid "Legacy specification" +msgstr "Die Spezifikationen" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +msgid "Examples:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +msgid "Example:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +msgid "PyPA schemas" +msgstr "" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +msgid "Python Description Formats" +msgstr "" + +#: ../source/specifications/section-reproducible-environments.rst:3 +msgid "Reproducible Environments" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +msgid "Normalized Names" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +#, fuzzy +#| msgid "Translations" +msgid "HTML Serialization" +msgstr "Die Übersetzungen" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +msgid "Project List" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +msgid "Project Detail" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +msgid "JSON Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +msgid "Content-Types" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +msgid "Version + Format Selection" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +msgid "Definitions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +msgid "Version scheme" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +msgid "Pre-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +msgid "Version epochs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +msgid "Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +msgid "Integer Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +msgid "Version exclusion" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +msgid "Well-known Project URLs in Metadata" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +msgid "Label normalization" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +msgid "Normalized" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"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/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "" + +#: ../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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "" + +#: ../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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" + +#, fuzzy +#~ msgid "Signing the distribution packages" +#~ msgstr "Distributionspaket" diff --git a/locales/eo/LC_MESSAGES/messages.po b/locales/eo/LC_MESSAGES/messages.po new file mode 100644 index 000000000..9b592b6dd --- /dev/null +++ b/locales/eo/LC_MESSAGES/messages.po @@ -0,0 +1,34451 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# phlostically , 2021, 2024, 2025. +# meowmeowmeowcat , 2021. +# Emilia Meza , 2025. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: 2025-06-29 12:03+0000\n" +"Last-Translator: phlostically \n" +"Language-Team: Esperanto \n" +"Language: eo\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=2; plural=n != 1;\n" +"X-Generator: Weblate 5.13-dev\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "Kontribui al ĉi tiu gvidilo" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "" +"La |PyPUG| bonvenigas kontribuantojn! Jen kelke el multaj manieroj helpi nin:" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "Legi la gvidilon kaj doni opiniojn pri ĝi" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "Revizii novajn kontribuojn" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "Poluri ekzistantan enhavon" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "Verki novan enhavon" + +#: ../source/contribute.rst:14 +msgid "Translating the guide" +msgstr "Traduki ĉi tiun gvidilon" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" +"La plejparto e la laboro pri |PyPUG| okazas ĉe `la GitHub-deponejo de la " +"projekto `__. Por eki, vidu la liston de " +"`nesolvitaj cimoj `__ kaj `tirpetoj `__. Se vi " +"planas verki aŭ redakti la gvidilon, bonvolu legi la :ref:`gvidilon pri " +"stilo `." + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" +"Kontribuante al |PyPUG|, vi devas observi la `Kondutkodon `__ de PSF." + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "Tipoj de dokumentaro" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" +"Ĉi tiu projekto konsistas el kvar malsamaj dokumentaj specoj por specifaj " +"celoj. La projekto celas sekvi `la procezon Diátaxis `_ " +"por verki kvalitan dokumentaron. Kiam vi proponas novajn aldonojn al la " +"projekto, bonvolu elekti la taŭgan dokumentan specon." + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "Lerniloj" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" +"Lernilo fokusiĝas pri instruado de la leganto pri novaj konceptoj per " +"efektivigado de iu celo. Lernilo estas opinihava, paŝon-post-paŝa dokumento. " +"Ĝi ne inkluzivas negravajn avertojn aŭ informojn. `ekzempla lernileca " +"dokumento `_." + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "Gvidiloj" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" +"Gvidiloj estas por plenumi specifan taskon kaj povas supozi iun nivelon de " +"scio. Tiuj similas al lerniloj sed havas mallarĝan kaj klaran fokuson kaj " +"povas disponigi multajn avertojn kaj kromajn informojn laŭbezone. Ili ankaŭ " +"povas diskuti plurajn metodojn por unu tasko. :doc:`ekzempla gvidila " +"dokumento `." + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "Diskutoj" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" +"Diskutoj estas por komprenado kaj informado. Tiuj esploras specifan temon " +"sen specifa celo. :doc:`ekzempla diskuta dokumento `." + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "Specifiloj" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" +"Specifoj estas referenca dokumentaro por plene priskribi interkonsentitan " +"interfacon por kongrueco inter iloj pri pakado. :doc:`ekzempla specifo-" +"dokumento `." + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "Tradukoj" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" +"Ni uzas `Weblate`_ por administri tradukadon de ĉi tiu projekto. Bonvolu " +"viziti la projekton `packaging.python.org`_ ĉe Weblate por kontribui." + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" +"Se vi spertas problemojn dum tradukado, bonvolu raporti cimon ĉe `GitHub`_." + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" +"Traduko de ĉi tiu projekto devas sekvi `la sintakson reStructuredText " +"`_." + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "Aldoni lingvon" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" +"Se via lingvo ne estas listigita en `packaging.python.org`_, alklaku la " +"butonon :guilabel:`Start new translation` ĉe la malsupro de la listo de " +"lingvoj, kaj aldonu la lingvon al kiu vi volas traduki." + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "Sekvi la sintakson reStructuredText" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" +"Se vi ne bone scias la sintakson reStructuredText (RST), bonvolu legi `ĉi " +"tiun gvidilon `_ antaŭ ol ektraduki ĉe Weblate." + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "**Ne traduku tekston en referenco rekte**" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "Kiam vi tradukas tekston en referenco, bonvolu ne traduki ĝin rekte." + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "Malĝuste: Traduki la jenon rekte:" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" +"Ĝuste: Traduki la jenan tekston al via propra lingvo kaj aldoni la " +"originalan referencon:" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "Konstrui la gvidilon loke" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" +"Kvankam tio ne necesas por kontribui, estas utile konstrui ĉi tiun gvidilon " +"loke por elprovi viajn ŝanĝojn. Por konstrui ĉi tiun gvidilon loke, vi " +"bezonos la jenon:" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr ":doc:`Nox `. Vi povas instali aŭ ĝisdatigi nox per ``pip``:" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" +"Python 3.11. Niaj konstruaj programetoj estas ordinare testata nur per " +"Python 3.11. Vidu :doc:`Hitchhiker's Guide to Python installation " +"instructions ` por instali Python 3.11 " +"sur via mastruma sistemo." + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" +"Por konstrui la gvidilon, rulu la jenan konzolan komandon ĉe la radika " +"dosierujo de la projekto:" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" +"Post fino de la procezo, vi povas trovi la HTML-eligaĵon en la dosierujo ``./" +"build/html``. Vi povas malfermi la dosieron ``index.html`` por rigardi la " +"gvidilon en TTT-legilo, sed estas rekomendate servi la gvidilon per HTTP-" +"servilo." + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" +"Vi povas konstrui la gvidilon kaj servi ĝin per HTTP-servilo uzante la jenan " +"komandon:" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "La gvidilo estos legebla ĉe http://localhost:8000." + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "Kie la gvidilo disponiĝas" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" +"La gvidilo disponiĝas per ReadTheDocs, kaj la agordoj troviĝas ĉe https://" +"readthedocs.org/projects/python-packaging-user-guide/. Ĝi estas servata ĉe " +"propra retadreso per Fast.ly." + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "Rekomendoj pri stilo" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" +"Ĉi tiu stila gvidilo havas rekomendojn pri kiel verki la |PyPUG|. Antaŭ ol " +"vi ekverkas, bonvolu revizii ĝin. Sekvante la stilgvidilon, viaj kontribuoj " +"pli koheros kaj iĝos pli akceptindaj en la projekton." + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "Celo" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" +"La |PyPUG| celas esti la aŭtoritata dokumento pri kiel enpaki, eldoni kaj " +"instali Python-projektojn per nunaj iloj." + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "Amplekso" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" +"La gvidilo celas respondi al demandoj kaj solvi problemojn per precizaj kaj " +"enfokusigitaj rekomendoj." + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" +"La gvidilo ne celas esti plenplena, nek anstataŭigi la dokumentaron de " +"individuaj projektoj. Ekzemple, pip havas dekduojn da komandoj, opciojn, kaj " +"agordoj. La dokumentaro de pip priskribas ĉiujn el tiuj detale, dum la " +"gvidilo nur priskribas tiajn partojn de pip, kiaj necesas por kompletigi la " +"specifajn taskojn priskribitajn en la gvidilo." + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "Legantaro" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "" +"La legantoj de ĉi tiu gvidilo estas iuj ajn, kiuj uzas Python kun pakoj." + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" +"Ne forgesu, ke la Python-komunumo estas granda kaj bonveniga. Legantoj ne " +"povas havi la saman aĝon, sekson, edukon, kulturon ktp kiel vi, sed ili " +"meritas lerni pakadon tiel, kiel vi." + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" +"Aparte notu, ke ne ĉiuj, kiuj uzas Python, rigardas sin kiel programistojn. " +"La legandaro de ĉi tiu gvidilo inkluzivas astronomojn, pentristojn kaj " +"lernantojn kune kun profesiaj programistoj." + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "Voĉo kaj tono" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" +"Dum verkado de tiu gvidilo, klopodu skribi kun voĉo amikeca kaj humila, eĉ " +"se vi scias ĉion." + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" +"Imagu, ke vi laboras pri Python-projekto kun iu inteligenta kaj sperta. Vi " +"ŝatas labori kun tiu, kaj tiu ŝatas labori kun vi. Tiu ulo demandis al vi, " +"kaj vi scias la respondon. Kiel vi respondus? Jen *tiel* vi verku ĉi tiun " +"gvidilon." + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" +"Jen rapida kontrolo: provu laŭtlegi por senti la voĉon kaj tonon de via " +"verkaĵo. Ĉu ĝi similas ion, kion vi dirus, aŭ similas aktoraĵon aŭ prelegon? " +"Se tio plaĉas al vi, uzu malformalan lingvaĵon kaj ignoru trostriktajn " +"gramatikajn regulojn." + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" +"Dum verkado de la gvidilo, adaptu vian tonon por la graveco kaj malfacileco " +"de la temo. Se vi verkas enkondukan lernilon, estas bone ŝerci, sed se vi " +"diskutas gravan rekomendon pri sekureco, vi eble volas eviti ŝercojn entute." + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "Konvencioj kaj meĥaniko" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "**Verku por la leganto**" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" +"Kiam vi donas rekomendojn aŭ farendaĵojn, alparolu la leganton kiel «vi», aŭ " +"uzu la imperativon." + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "Netaŭga: Por instali ĝin, la uzanto rulas…" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "Taŭga: Vi povas instali ĝin per rulado de…" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "Taŭga: Por instali ĝin, rulu…" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "**Klarigu supozojn**" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" +"Evitu nedeklaritajn supozojn. Je Interreta legado, iu ajn paĝo de la gvidilo " +"povas esti la unua paĝo vidata de leganto. Se vi supozas ion, do klarigu " +"tiujn supozojn." + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "**Interreferencu ofte**" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" +"La unuan fojon vi mencias ilon aŭ praktikon, ligu al la parto de la gvidilo " +"pri ĝi aŭ al signifa dokumento aliloka. Ne serĉigu la leganton." + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "**Respektu nomojn**" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" +"Kiam vi nomas ilojn, retejojn, homojn kaj aliajn proprajn nomojn, uzu iliajn " +"preferatajn usklojn." + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "Netaŭga: Pip uzas…" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "Taŭga: pip uzas…" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "Netaŭga: …gastigata ĉe github." + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "Taŭga: …gastigata ĉe GitHub." + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "**Uzu seksneŭtralan stilon**" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" +"Ofte vi rekte alparolu la leganton per *vi*, *vin* aŭ *via*. Alie, uzu " +"seksneŭtralajn pronomojn *ili*, *ŝ/li* aŭ entute evitu pronomojn." + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "Malĝuste: Mastrumanto alŝutas la dosieron. Poste li…" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "Ĝuste: Mastrumanto alŝutas la dosieron. Poste ŝ/li…" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "Ĝuste: Mastrumanto alŝutas la dosieron. Poste la mastrumanto…" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "**Titoloj de paragrafoj**" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" +"Verku titolojn uzante tiujn vortojn, kiujn la leganto serĉas. Bona maniero " +"fari tion estas kompletigi implicitan demandon. Ekzemple, leganto eble volas " +"scii: *Kiel mi instalu MiaBiblioteko?* Tiel, bona ebla titolo estas *Instali " +"MiaBiblioteko*." + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" +"En paragrafaj titoloj, uzu frazan usklon. Alivorte, skribu titolojn tiel, " +"kiel vi skribus ordinaran frazon." + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "Netaŭga: Sciindaĵoj Pri Python" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "Taŭga: Sciindaĵoj pri Python" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "**Nombroj**" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" +"En alineo, skribo la nombrojn unu ĝis naŭ kiel vortojn. Por aliaj nombroj aŭ " +"nombroj en tabeloj, uzu ciferojn." + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "Disponigi Python-programojn" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "Stato de la paĝo" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "Nekompleta" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "Laste reviziita" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "24 Aŭgusto 2021" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "Superrigardo" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "Subtenante plurajn aparatajn platformojn" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "Pakado kaj instaliloj por mastrumaj sistemoj" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "Windows" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "Pynsist" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" +"`Pynsist `__ estas ilo faskiganta Python-" +"programon kune kun la Python -interpretilo en unu instalilon uzantan NSIS. " +"Plej ofte, pakado nur postulas elekti version de la Python-interpretilo kaj " +"deklari la dependencojn de la programo. La ilo elŝutas la specifitan Python-" +"interpretilon por Windows kaj pakas ĝin kune kun ĉiuj dependaĵoj en unu " +"Windows-ruleblan instalilon." + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" +"La instalita programo estas lanĉebla per lanĉilo aldonita de la instalilo al " +"la startmenuo. Ĝi uzas Python-interpretilon instalitan ene de ĝia programa " +"dosierujo, sendependan de aliaj Python-instalaĵoj sur la komputilo." + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" +"Granda avantaĝo de Pynsist estas, ke la Windows-pakoj estas konstrueblaj sur " +"Linux. Ekzistas pluraj ekzemploj por diversaj specoj de programoj (konzolaj, " +"grafikfasadaj) en la :any:`dokumentaro `. La ilo estas sub la " +"licenco MIT." + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "Aplikprogramaj faskoj" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" +"`py2exe `__ estas etendaĵo de distutils, " +"kiu ebligas konstrui memstarajn Windows-programojn (32-bitajn aŭ 64-bitajn) " +"el Python-programoj. Versioj de Python inkluzivitaj en la oficiala evolua " +"ciklo estas subtenata (vidu `Staton de la branĉoj de Python `__). py2exe povas konstrui konzolajn programojn kaj " +"fenestrajn (grafikfasadajn) programojn. Konstruado de servoj por Windows kaj " +"servoj DLL/EXE COM eble funkcios, sed tio ne estas aktive subtenata. La " +"etendaĵo de distutils estas disponebla sub la Licenco MIT kaj la Mozilla " +"Public License 2.0." + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" +"`py2app `__ estas komando por Python " +"setuptools, kiu ebligas fari aŭtonoman programfaskon aŭ kromprogramon por " +"macOS el Python-programon. Notu, ke py2app DEVAS esti uzita sur macOS por " +"konstrui; ĝi ne povas krei Mac-programojn sur aliaj platformoj. py2app uzas " +"la licencon MIT." + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "Unikso (inkluzive de Linux kaj macOS)" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "pex" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" +"`pex `__ estas biblioteko por generi .pex-" +"dosieron (Python EXecutable), kiu estas rulebla Python-medio simile al " +"virtualenv. pex estas plivastigo de la ideoj en :pep:`441` kaj igas la " +"disponigon de Python-programojn tiel facila kiel cp. pex-dosiero povas eĉ " +"inkluzivi plurajn platformspecifajn Python-distribuojn; tial, unu pex-" +"dosiero povas esti portebla inter Linux kaj macOS. pex uzas la Apache-" +"Licencon 2.0." + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "Administrado de agordoj" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "Distribua pako kaj importa pako" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" +"La vorto «pako» signifas plurajn malsamajn konceptoj. Jen paĝo klariganta la " +"diferencojn inter la du malsamaj sed rilataj signifoj je Python-pakado, " +"«distribua pako» kaj «importa pako»." + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "Kio estas distribua pako?" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" +"Distribua pako estas instalebla peco da programaro. Plej ofte, tio estas " +"sinonima al «projekto». Kiam vi tajpas ``pip install pako``, aŭ kiam vi " +"skribas ``dependencies = [\"pako\"]`` en via ``pyproject.toml``, ``pako`` " +"estas la nomo de distribua pako. Kiam vi serĉas aŭ foliumas PyPI_, la plej " +"vaste konata fonto por instali Python-bibliotekojn kaj ilojn, vi vidas " +"liston da distribuaj pakoj. Alternative, la termino «distribua pako» povas " +"signifi specifan dosieron enhavantan specifan version de projekto." + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" +"Notu, ke en la mondo de Linux, «distribua pako» aŭ simple «pako» estas io " +"provizata de la sistema pakadministrilo de la `Linux-distribuo `_, " +"kio estas alia signifo." + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "Kio estas importa pako?" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" +"Importa pako estas Python-modulo. Tiel, kiam vi skribas ``import pako`` aŭ " +"``from pako import funk`` en via Python-kodo, ``pako`` estas la nomo de " +"importa pako. Pli precize, importa pako estas speciala Python-modulo, kiu " +"povas enhavi submodulojn. Ekzemple, la pako ``numpy`` enhavas modulojn kiel " +"``numpy.linalg`` kaj ``numpy.fft``. Ordinare, importa pako estas dosierujo " +"en la dosiersistemo, enhavanta modulojn kiel ``.py``-dosierojn kaj subpakojn " +"kiel subdosierujojn." + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" +"Vi povas uzi importan pakon tuj, kiam vi instalis distribuan pakon " +"provizanta ĝin." + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "Kiel ligiĝas distribuaj pakoj kaj importaj pakoj?" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" +"Plej ofte, distribua pako provizas nur unu importan pakon (aŭ ne-pakan " +"modulon), kun la sama nomo. Ekzemple, ``pip install numpy`` ebligas vin " +"skribi ``import numpy``." + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" +"Tamen, tio estas nur konvencia. PyPI kaj aliaj pakindeksoj *ne devigas ajnan " +"rilaton* inter la nomo de distribua pako kaj la importaj pakoj provizataj de " +"ĝi. (Tial, vi ne simple instalu la PyPI-pakon ``pako``, se vi vidas ``import " +"pako``; tio eble instalos neintencitan aŭ eĉ malican pakon.)" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" +"Distribua pako povas provizi importan pakon de alia nomo. Ekzemple, " +"konsideru la popularan bibliotekon Pillow_ por pritraktado de bildoj. La " +"nomo de ĝia distribua pako estas ``Pillow``, sed ĝi provizas la importan " +"pakon ``PIL``. Tio estas pro historiaj kialoj: Pillow komenciĝis kiel forko " +"de la biblioteko PIL kaj retenis la importan nomon ``PIL``, por ke " +"ekzistantaj uzantoj de PIL povas ekuzi Pillow senŝanĝe. Pli ĝenerale, " +"forkado de ekzistanta biblioteko estas ofta kialo por malsamaj nomoj inter " +"la distribua pako kaj la importa pako." + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" +"En iu pakindekso (kiel PyPI), la nomoj de distribuaj pakoj devas esti " +"unikaj. Tamen, neniu simila devo ekzistas por la nomoj de importaj pakoj. " +"Pluraj distribuaj pakoj povas provizi importajn pakojn de la sama nomo. " +"Forkado estas ofta kialo pri tio." + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" +"Male, distribua pako povas provizi plurajn importajn pakojn, kvankam tio " +"maloftas. Ekzemple, la distribua pako attrs_ provizas kaj importan pakon " +"``attrs`` de pli nova API kaj importan pakon ``attr`` de pli malnova sed " +"subtenata API." + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "Kiel komparas nomo de distribua pako kaj nomo de importa pako?" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" +"La nomo de importa pako devas esti validan identigilon de Python " +"(la :ref:`precizaj reguloj ` troviĝas en la dokumentaro " +"de Python) [#non-identifier-mod-name]_. Speciale, ĝi uzas substrekojn ``_`` " +"kiel vortapartigilojn kaj estas usklecdistinga." + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" +"Aliflanke, nomo de distribua pako povas enhavi streketon ``-`` aŭ substrekon " +"``_`` kaj ankaŭ povas enhavi punkton ``.``, kiu estas kelkfoje uzata por " +"paki subpakon de :ref:`nomspaca pako `. Por " +"plej multaj celoj, ĝi estas usklecoblinda kaj al la diferenco inter ``-`` " +"kaj ``_``. Ekzemple, ``pip install Bonega_Pako`` estas sama kiel ``pip " +"install bonega-pako`` (la precizaj reguloj troviĝas en la :ref:`specifo pri " +"normigo de nomoj `)." + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" +"Kvantam teĥnike eblas importi pakon/modulon, kies nomo ne estas valida " +"Python-identigilo, per :doc:`importlib `, tio " +"estas maloftega kaj malrekomendegata." + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "Subteni pakadon far malsupruloj" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "Malneto" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "2025-?" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" +"Kvankam PyPI kaj la Python-pakiloj kiel :ref:`pip` estas la ĉefrimedoj por " +"distribui Python-pakojn, Python-pakoj ankaŭ ofte estas parto de aliaj " +"pakadaj ekosistemoj. Tiaj repakadaj klopodoj kolektive nomiĝas *malsuprula* " +"pakado (viaj propraj klopodoj nomiĝas *suprula* pakado), kaj inkluzivas " +"interalie Linux-distribuojn, Conda, Homebrew kaj MacPorts. Ili ĝenerale " +"celas pli bone subteni tiajn uzkazojn, kiajn Python-pakiloj sole ne povas " +"subteni, kiel ekzemple indiĝenan integriĝon kun iu mastruma sistemo, aŭ " +"certan kongruecon kun iu versio de ne-Python-a programo." + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" +"Ĉi tiu diskuto provas klarigi, kiel malsuprula pakado kutime funkcias kaj " +"kiajn problemojn alfrontas malsupraj pakantoj. Ĝi celas disponigi kelkajn " +"laŭvolajn gvidnormojn por mastrumantoj de projektoj por *pliege* faciligi " +"malsuprulan pakadon (sen grava malfaciligo de la suprula projekto). Notu, ke " +"tio ne estas ĉioma-aŭ-nenioma – utilas io ajn, kion suprula mastrumanto " +"povas fari, eĉ se ĝi estas nur malgranda parto. Malsuprulaj mastrumantoj " +"ankaŭ volas prepari flikojn por solvi tiajn problemojn. Eĉ kelkaj el tiaj " +"flikoj estas tre utilaj, ĉar diversaj malsupruloj ne plu bezonas alporti kaj " +"rebazigi la samajn flikojn aŭ solvi la saman problemon multfoje." + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" +"Bonaj rilatoj inter programomastrumantoj kaj malsupraj pakantoj povas helpi " +"unu la aliajn. Malsupruloj ofte volonte donacas siajn sperton, tempon kaj " +"aparatojn por plibonigi vian pakon. Ili fojfoje pli bone scias, kiel via " +"pako uziĝas praktike kaj pri la rilatoj kun aliaj pakoj; ofte ne facilas " +"akiri tiajn informojn alimaniere. Pakantoj ofte povas trovi cimon antaŭ ol " +"la uzantoj trafus ĝin praktike; pakantoj bone raportas cimojn kaj disdonas " +"flikaĵojn tiam ajn kiam eblas. Ekzemple, ili aktive certigas, ke la " +"redistribuataj pakoj estas ĝisdatigitaj kontraŭ problemoj pri kongrueco, " +"kiam nova versio de Python eldoniĝas." + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" +"Bonvolu noti, ke malsuprulaj konstruj inkluzivas ne nur duuman " +"redistribuadon sed ankaŭ konstruojn el fonto sur sistemo de uzanto (en fonto-" +"centra distribuo kiel Gentoo Linux, ekzemple)." + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "Provizi plenajn fontajn distribuojn" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "Kial?" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" +"Preskaŭ ĉiuj malsuprulaj pakantoj preferas konstrui pakojn el fonto, ne uzi " +"la duumajn pakojn provizitajn de supruloj. Kelkfoje, uzado de la fonto estas " +"deviga por inkluzivi la pakon en la distribuon. Tio ankaŭ estas vera pri " +"pako konsistanta nur el Python provizanta universalan wheel. Jen iuj kialoj " +"por uzi fontan distribuon:" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "La kapablo inspekti la fontkodon de ĉiuj pakoj." + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "La kapablo ruli la testaron kaj konstrui la dokumentaron." + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" +"La kapablo facile fliki, inkluzive de retroporti modifojn el la projekta " +"deponejo kaj submeti flikaĵojn al la projekto." + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "La kapablo konstrui sur specifa platformo ne provizita de supruloj." + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "La kapablo bindi al specifaj versioj de sistemaj bibliotekoj." + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "Havi koheran konstruprocedon por ĉiaj Python-pakoj." + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" +"Kvankam ofte oni povas konstrui pakon el Git-deponejo, ekzistas kelkaj " +"gravaj kialoj por anstataŭe disponigi statikan arĥivon:" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" +"Elŝutado de unu dosiero estas ofte pli rapida, pli dependema kaj pli bone " +"subtenata ol ekz. uzi ``git clone``. Tio povas helpi tiajn uzantojn, kies " +"Interreta konekto malbonas." + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" +"Malsupruloj ofte uzas haketaĵojn por konfirmi la aŭtentikecon de " +"fontdosieroj por sekvaj konstruoj. Tio postulas, ke ili restu bite identaj. " +"Ekzemple, aŭtomate generita Git-arĥivo ne garantias tion, ĉar la densigitaj " +"datenoj povas ŝanĝiĝi, se la servilo ĝisdatigas ``gzip``." + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" +"Oni povas speguli arĥivo-dosierojn, malpliigante Interretan uzadon por ĉiuj. " +"La konstruado mem povas okazi en ŝirmita aŭ senkonekta medio, kiu povas nur " +"atingi fontodosierojn provizitajn de la loka spegulo aŭ redistribuitajn pli " +"frue." + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" +"Eksplicite eldoni arĥivo-dosierojn povas certigi, ke ajna dependeco sur " +"versikontrolsistemaj metadatenoj solviĝas dum kreado de la fonta arĥivo. " +"Ekzemple, aŭtomate generita Git-arĥivo ekskluziviĝas informojn pri la " +"enmetaj etikedoj, eble kaŭzante malĝustajn informojn pri versiaj detaloj en " +"la rezultaj konstruoj." + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "Kiel?" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" +"Ideale, **fontodistribua arĥivo ĉe PyPI inkluzivu ĉiujn dosierojn de la Git-" +"deponejo de la pako** necesajn por konstrui la pako mem, ruli la testaron, " +"konstrui kaj instali la dokumentaron, kaj ĉiajn aliajn dosierojn utilajn por " +"uzantoj, kiel ekzemple ŝelkompletigaĵojn, redaktilajn helpdosierojn ktp." + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" +"Kelkaj projektoj havas problemojn pri Python-pakadministrilo uzanta fontan " +"distribuon el PyPI. Ili ne deziras pligrandigi pakojn kun dosieroj ne " +"uzataj, aŭ ili deziras ne eldoni fontan distribuon, ĉar konstrui projekton " +"el fonta distribuo povas esti problemplene aŭ neeble. Tiakaze, bona " +"kompromiso povas esti eldoni apartan fontarĥivon por malsupruloj aliloke, " +"ekzemple per alkroĉado al GitHub-eldono. Alternative, grandaj dosieroj, kiel " +"ekzemple testdatenoj, povas esti dividitaj en apartajn arĥivojn." + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" +"Aliflanke, kelkaj projektoj (kiel NumPy_ ekzemple) decidas inkluzivi testojn " +"en siaj instalitaj pakoj. Tio havas la ekstran avantaĝon ebligantan uzantojn " +"ruli testojn post instalo, ekzemple por kontroli cimojn post ĝisdatigo de " +"dependaĵo. Alia metodo estas disdividi testojn aŭ testajn datenojn en " +"apartan Python-pakon. Tiun metodon uzas la projekto cryptography_, kies " +"grandaj tekstovektoroj troviĝas en la pako cryptography-vectors_." + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" +"Bona ideo estas uzi la fontan distribuon en la eldona laborfluo. Ekzemple, " +"la ilo :ref:`build` faras precize tion: ĝi unue konstruas fontan distribuon, " +"kaj poste uzas ĝin por konstrui wheel. Tio certigas, ke la fonta distribuo " +"fakte funkcias, kaj ke ĝi ne preterlasas dosierojn inkluzivitajn en la " +"oficiala wheel." + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" +"Ideale, ankaŭ uzu la fontan distribuon por ruli testojn, konstrui " +"dokumentaron, ktp, aŭ aldonu specifajn testojn por certigi, ke ĉiuj necesaj " +"dosieroj inkluziviĝis. Kompreneble, tio postulas pli da peno; tial, estas " +"bone ne fari tion – malsuprulaj pakantoj tuj raportos ian ajn mankantan " +"dosieron." + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "Ne uzi Interreton dum konstruado" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" +"Malsuprulo ofte konstruas en izolita medio sen konekto al Interreto, " +"malpakante la resursojn de la pako en tiun medion kaj instalante ĉiujn " +"necesajn dependaĵojn." + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" +"Eĉ se ne, kaj supozante, ke oni taŭge aŭtentikigus elŝutojn, uzi Interreton " +"estas malrekomendate pro la jenaj kialoj:" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" +"La Interreta konekto povas esti malstabila (ekz. pro malbona sendrata reto) " +"aŭ havi dumpteman problemon, kaŭzante malsukceson aŭ paraliziĝon de la " +"procezo." + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" +"La foraj resursoj povas portempe aŭ eĉ daŭre neatingebligi, malebligante la " +"konstruadon. Tio estas aparte problema, kiam oni devas konstrui malnovan " +"version de pako." + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "La foraj resursoj povas ŝanĝiĝi, nereproduktebligante la konstruon." + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" +"Kontakto al fora servilo kaŭzas problemojn pri privateco kaj eble sekureco, " +"ĉar tio tralasas informojn pri la sistemo konstruanta la pakon." + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" +"La uzanto eble uzas servon kun limigita datenplano tiel, ke senbrida " +"konektado al Interreto povas kaŭzi kromajn pagendaĵojn aŭ aliajn ĝenojn." + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" +"Ideale, propra konstrua programeto ne eĉ provu atingi Interreton sen " +"eksplicita peto. Se ia resurso mankas kaj estas elŝutenda, la programeto " +"petu por permeso unue. Se tio ne eblas, la dua plej bona opcio estas provizi " +"baskulon por malŝalti ĉian atingon al Interreto, ekzemple kontrolante, ĉu iu " +"media variablo «NO_NETWORK» estas nemalplena." + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" +"Ĉar malsupruloj ofte ankaŭ rulas testojn kaj konstruas dokumentaron, oni " +"faru la ĉi-supron ankaŭ por tiaj procedoj." + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" +"Ankaŭ bonvolu memori, ke se oni elŝutas forajn resursojn, oni absolute devas " +"*kontroli la aŭtentikecon* (ofte per haketaĵo), gardante kontraŭ " +"fianstataŭigo far fiulo." + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "Ebligi konstruadon uzante sistemajn dependecojn" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" +"Kelkaj Python-projektoj dependas de ne-Python-aj bibliotekoj en ekz. C aŭ C+" +"+. Uzado de sistemaj versioj de tiaj dependaĵoj en suprula pakado kaŭzas " +"multajn problemojn por uzantoj:" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" +"Konstrui el fonta distribuo postulas font-kongruan version de la dependaĵo, " +"kune kun ĝiaj ĉapoj kaj aliaj helpdosieroj, kiujn kelkaj sistemoj pakas " +"aparte de la biblioteko mem." + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" +"Eĉo por spertulo, instali kongruan version de dependaĵo povas esti " +"malfacilege. Ekzemple, la postulata versio povus manki en la uzata Linux-" +"distribuo, aŭ alia pako povus postuli nekongruan version." + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" +"La pakada sistemone registras la ligon inter la Python-pako kaj la sistema " +"dependaĵo. Sistema ĝisdatigo povas ĝisdatigi la bibliotekon al nova versio, " +"rompante binaran kongruecon kun la Python-pako kaj postulante malaŭtomatan " +"riparon." + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" +"Tamen, neniu el tiuj problemoj validas por malsuprula pakado, kaj " +"malsupruloj havas bonajn kialojn por preferi dinamikan bindadon al sistemaj " +"dependaĵoj. Specife:" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" +"Ofte, fidinde komunigi dinamikajn dependaĵojn inter komponantoj estas granda " +"parto de la *celo* de malsupruloa pakada ekosistemo. Helpante tion, oni " +"faciligas por uzantoj de tiaj sistemoj uzi suprulajn projektojn en sia " +"preferata formo." + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" +"Statika bindado kaj kopiado kaŝas la uzon de eksteraj dependaĵoj, " +"malfaciligante inspektadon de la fonto." + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" +"Dinamika bindado ebligas rapide kaj sisteme anstataŭigi la uzitajn " +"bibliotekojn tra tuta malsuprula pakada ekosistemo, kio gravas pri sekureca " +"problemo aŭ severa cimo." + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" +"Laste, sed grave, statika bindado kaj kopiado de dependaĵoj kreas " +"duplikatojn kaj povas uzi troon da diskospaco kaj memoro." + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "Subteni testadon far malsupruloj" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "Konfirmi, ke la malsuprula pakado ne kreis cimojn." + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "Testi sur pliaj platformoj ol la suprula testaro." + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" +"Trovi subtilan cimon nur troveblan per specifaj aparatoj, versioj de " +"sistemaj pakoj ktp." + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" +"Testi la eldonitan pakon por versioj de dependaĵoj pli novaj (aŭ malnovaj) " +"ol tiuj de la suprulaj testoj." + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" +"Testi la pakon en medio tre simila al la medioj de uzantoj. Tio povas trovi " +"cimojn okazantojn pro komplikaj interagoj inter diversaj instalitaj pakoj, " +"inkluzive de tiuj pakoj, kiuj ne estas dependaĵoj de via pako sed tamen " +"povas kaŭzi problemojn." + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" +"Testi la eldonitan pakon por pli novaj versioj de Python (inkluzive de " +"punktaj eldonoj) aŭ maloftaj Python-realigoj kiel PyPy." + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" +"Inkluzivu la testo-dosierojn kaj testilojn en la fontan distribuon, aŭ " +"faciligu aparte elŝuti ilin." + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" +"Ne skribu al la pakaj dosierujoj dum testado. Malsupruloj ofte testas sur la " +"instalita pako; modifoj dum testado kaj provizoraj testdosieroj povas " +"inkluziviĝi en la instalita pako!" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" +"Igu la testojn ruleblaj sen speciala aranĝo, aŭ faru la necesan aranĝon kiel " +"parton de la testilo. Neniam supozu, ke oni povas konekti al sistemaj servoj " +"kiel ekzemple datenbankoj – oni povus eĉ fiaskigi gravan servon!" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" +"Se via pako havas laŭvolajn dependecojn, igu iliajn testojn laŭvolaj ankaŭ. " +"Aŭ transsaltu ilin, se la rilataj pakoj mankas, aŭ marku ilin por faciligi " +"malelekti ilin." + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" +"Pli ĝenerale, marku testojn kun specialaj postuloj. Tiuj povas inkluzivi " +"ekz. signifan uzon de diskospaco aŭ memoro, longan ruladan daŭron, " +"neparaleligeblecon." + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" +"Ne supozu, ke oni rulos la testaron kun ``-Werror``. Malsupruloj ofte " +"bezonas malŝalti ĝin pro malĝustaj pozitivoj, ekz. pri pli novaj versioj de " +"dependecoj. Asertu avertojn per ``pytest.warns()``, ne ``pytest.raises()``!" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" +"Provu fidindigi kaj malhazardigi la testaron. Evitu malsukceman teston. " +"Evitu dependi de detaloj pri iu platformo, aŭ ekzaktajn rezultojn de " +"gliskoma operacio, aŭ la daŭro de operacioj ktp. Hazarda testado povas " +"utili, sed ankaŭ havu statikajn testojn por kompleteco." + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" +"Se oni bezonas multon da tempo por ruli la testaron, subtenu paralelan " +"testadon. Malsupruloj ofte mastrumas multajn pakojn, kaj testi ĉiujn " +"postulas multegon da tempo. Uzi pytest-xdist_ povas malhelpi ŝtopiĝon." + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" +"Ideale, subtenu ruli testaron per ``pytest``. pytest_ havas multajn " +"komandliniajn argumentojn utilegajn al malsupruloj, ekzemple la kapablojn " +"facile malŝalti testojn, reruli malsukcesemajn testojn (per pytest-" +"rerunfailures_), aŭtomate ĉesigi testojn post iom da tempo (per pytest-" +"timeout_) aŭ ruli testojn paralele (per pytest-xdist_). Notu, ke oni povas " +"*ruli* per ``pytest`` testaron ne *verkitan* per ``pytest``: ``pytest`` " +"povas trovi kaj ruli preskaŭ ĉiajn testojn kongruajn kun la testo-trova " +"meĥanismo de ``unittest`` en la norma biblioteko." + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "Celi stabilajn eldonojn" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "frue meti novan version en la stabilan kanalon," + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "fliki la aktualan eldonitan version," + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "aŭ eĉ malĝisdatigi la stabilan kanalon al pli malnova eldono." + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" +"Ĉiu el tiuj opcioj havas riskojn kaj farendaĵojn. Pakanto devas pesi ilin " +"por determini tion, kio oni faru." + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" +"Jen kelkaĵoj, kiujn supruloj povas fari, por ebligi stabilajn eldonkanalojn " +"(tiaĵoj ofte utilas ankaŭ por la uzantoj de la pako):" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" +"Adaptu la oftecon de eldonado al la rapido de kodŝanĝoj. Pako malofte " +"eldonata povas enhavi po multaj ŝanĝoj por ĉiu eldono kaj tial pliigas la " +"riskon de regresoj." + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" +"Evitu miksi cimriparojn kaj novajn funkciojn laŭeble. Aparte, se ekzistas " +"konataj cimriparoj jam enmetitaj, konsideru novan eldonon antaŭ ol aldoni " +"novajn funkciojn." + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" +"Konsideru antaŭeldonojn post gravaj ŝanĝoj, por disponigi pli da ŝancoj pri " +"testado fare de tiuj uzantoj kaj malsupruloj, kiuj volontas." + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" +"Se la projekto estas rapidege evoluigata, konsideru, ĉu disfendi unu aŭ " +"plurajn branĉojn, kiuj inkluzivas pli konservativan subaron de ^anĝoj kaj " +"eldoniĝas aparte. Ekzemple, Django_ nuntempe havas tri branĉojn apud la " +"ĉefbranĉo." + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" +"Eĉ se vi ne deziras mastrumi pliajn branĉojn daŭre, pripensu pliajn flikajn " +"eldonojn kun minimumaj ŝanĝoj al la antaŭa versio, aparte kiam malsekureco " +"troviĝas." + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" +"Disdividu ŝanĝon en enfokusigitajn modifojn riparantajn po unu problemo, por " +"faciligi elekti modifojn por pli fruaj eldonoj, se tio necesas." + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" +"**Diskutoj** celas provizi plenajn informojn pri specifa temo. Se vi nur " +"volas eklabori, legu :doc:`/guides/index`." + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "install_requires kontraste kun requirements.txt" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "install_requires" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" +"``install_requires`` estas ŝlosilvorto de :ref:`setuptools` " +"en :file:`setup.py` kiu specifas la *minimumon* necesan por rulado de " +"projekto. Kiam la projekto estas instalata de :ref:`pip`, ĝi estas la " +"specifo uzatan por instali la dependaĵojn." + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" +"Ekzemple, se la projekto postulas A kaj B, via ``install_requires`` estos " +"jena:" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "Cetere, bone estas specifi ajnan konatan malsupran aŭ supran limojn." + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" +"Ekzemple, eble vi scias, ke via projekto postulas almenaŭ v1 de «A»k aj v2 " +"de «B», jene:" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" +"Oni eble ankaŭ scias, ke projekto «A» enkondukis ŝanĝon en sia versio 2 " +"rompantan la kongruecon de onia projekton kun versio 2 aŭ posta de «A», kaj " +"tial volas malpermesi version 2:" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" +"Ne estas bona praktiko uzi ``install_requires`` por alpingli dependaĵojn al " +"specifaj versioj aŭ specifi subdependaĵojn (dependaĵojn de dependaĵo). Tio " +"estas tro strikta kaj malhelpas ĝisdatigon de dependaĵoj." + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" +"Fine, estas grave kompreni, ke ``install_requires`` estas listo de " +"«Abstraktaj» postuloj, t.e. nuraj nomoj kaj versiaj restriktoj, kiuj ne " +"determinas la lokon, de kiu la dependecoj estos plenumitaj (t.e. de kiu " +"indekso aŭ fonto). La kieo (t.e. kiel «Konkretigi» ilin) estas determinota " +"rultempe per la opcioj de :ref:`pip`. [1]_" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "Dosiero requirements.txt" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" +":ref:`Postulo-Dosiero `, plej simple, estas listo de " +"argumentoj al :ref:`pip:pip install` en dosiero." + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" +"Dum ``install_requires`` difinas dependecojn de unu projekto, :ref:`Postulo-" +"Dosiero ` ofte difinas la postulojn pri plena Python-" +"medio." + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" +"Dum postuloj de ``install_requires`` estas minimumaj, postulo-dosiero ofte " +"enhavas plenan liston de alpinglitaj versioj por :ref:`ripeteblaj instaloj " +"` de plena medio." + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" +"Dum postuloj de ``install_requires`` estas «Abstraktaj» (ne asociitaj al iu " +"indekso), postulo-dosiero ofte enhavas pip-flagojn kiel ``--index-url`` aŭ " +"``--find-links`` por «Konkretigi» la postulojn (asocii ilin al iuj indeksoj " +"aŭ dosierujoj da pakoj). [1]_" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" +"Dum metadatenoj de ``install_requires`` estas aŭtomate analizitaj far pip " +"dum instalado, postulo-dosieroj ne estas, kaj nur estas uzataj, kiam oni " +"specife instalas per ``python -m pip install -r``." + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" +"Por pli pri «abstraktaj» kaj «konkretaj» postuloj, legu https://caremad.io/" +"posts/2013/07/setup-vs-requirement/." + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "Pakaj formoj" + +#: ../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 "" +"Jen paĝo pri la dosierformoj uzataj por distribui Python-pakojn kaj la " +"diferencojn inter ili." + +#: ../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 "" +"Ekzistas dosieroj en du formoj en pakindicoj kiel PyPI_: **fontaj " +"distribuoj** (anglalingve mallonge **sdist**) kaj **duumaj distribuoj**, " +"ofte konata kiel **wheel**. Ekzemple, la `paĝo ĉe PyPI por pip 23.3.1 `_ provizas du dosierojn, ``pip-23.3.1.tar.gz`` kaj ``pip-23.3.1-py3-" +"none-any.whl``. La unua estas fonta distribuo; la dua estas wheel. Kiel " +"klarigite ĉi-sube, tiuj du servas malsamajn celojn. Kiam vi eldonas pakon ĉe " +"PyPI (aŭ aliloke), vi ĉiam elŝutu fontan distribuon kaj unu aŭ pluraj wheel-" +"o(j)n." + +#: ../source/discussions/package-formats.rst:21 +msgid "What is a source distribution?" +msgstr "Kio estas fonta distribuo?" + +#: ../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 "" +"Koncepte, fonta distribuo estas arĥivo de la fontkodo en kruda formo. " +"Konkrete, fonta distribuo estas ``.tar.gz``-arĥivo enhavanta la fontkodon " +"kun plia speciala dosiero nomita ``PKG-INFO``, kiu enhavas la projektajn " +"metadatenojn. La ĉeesto de tiu dosiero helpas plirapidigi pakilojn, ĉar ne " +"necesas rekomputi la metadatenojn. La dosiero ``PKG-INFO`` sekvas la formon " +"specifitan en :ref:`core-metadata` kaj ne estas malaŭtomate verkinda [#core-" +"metadata-format]_." + +#: ../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 "" +"Tial, vi povas inspekti la enhavon de fonta distribuo maldensigante ĝin per " +"normaj enarĥivigiloj kiel ``tar -xvf`` ĉe Unikso (kiel Linux kaj macOS) " +"aŭ :ref:`la komandlinia interfaco de la Python-modulo tarfile " +"` ĉe ajna platformo." + +#: ../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 "" +"Fonta distribuo servas plurajn celojn en la pakada ekosistemo. " +"Kiam :ref:`pip`, la norma Python-pakinstalilo, ne povas trovi instaleblan " +"wheel, ĝi elŝutos fontan distribuon, konstruos wheel de ĝi, kaj instalos la " +"wheel. Krome, fonta distribuo ofte estas uzata kiel la paka fonto far " +"subpakantoj (kiel ekzemple Linux-distribuoj, Conda, Homebrew kaj MacPorts " +"sur macOS, …) , kiuj, pro diversaj kialoj, eble preferas fontan distribuon " +"ol interalie la Git-deponejon." + +#: ../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 "" +"Fonta distribuo estas rekonata per ĝia dosiernomo de la " +"formo :samp:`{paknomo}-{versio}.tar.gz`, ekz. ``pip-23.3.1.tar.gz``." + +#: ../source/discussions/package-formats.rst:50 +msgid "" +"If you want technical details on the sdist format, read the :ref:`sdist " +"specification `." +msgstr "" +"Se vi deziras teĥnikajn detalojn pri la fontdistribua dosierformo, " +"legu :ref:`la specifon pri fontaj distribuoj `." + +#: ../source/discussions/package-formats.rst:55 +msgid "What is a wheel?" +msgstr "Kio estas wheel?" + +#: ../source/discussions/package-formats.rst:57 +msgid "" +"Conceptually, a wheel contains exactly the files that need to be copied when " +"installing the package." +msgstr "" +"Koncepte, wheel enhavas precize tiujn dosierojn, kiuj devas esti kopiitaj " +"dum instalado de la pako." + +#: ../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 "" +"Ekzistas granda diferenco inter fontaj distribuoj kaj wheel-oj por pakoj " +"kun :term:`etendaj moduloj `, verkitaj en tradukendaj " +"lingvoj kiel C, C++ kaj Rust, kiuj devas esti tradukitaj al " +"platformodependaj maŝinkodoj. Je tia pako, wheel ne enhavas fontkodon (kiel " +"C-fontdosieron), sed enhavas tradukitan, ruleblan kodon (kiel la ``.so``-" +"dosierojn ĉe Linux aŭ DLL ĉe Windows)." + +#: ../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 "" +"Krome, dum ekzistas po unu fonta distribuo por ĉiu versio de projekto, povas " +"ekzisti multaj wheel-oj. Denove, tio plej temas pri etendaĵa modulo. La " +"tradukita kodo de etendaĵa modulo estas ligita al mastruma sistemo kaj " +"procesora arĥitekturo kaj ofte ankaŭ la versio de la Python-interpretilo (se " +"oni ne uzas la :ref:`stabilan ABI de Python `)." + +#: ../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 "" +"Por pure-Python-a pako, la diferenco inter fonta distribuo kaj wheel estas " +"malpli markita. Estas ordinare unu rado, por ĉiuj platformoj kaj Python-" +"versioj. Python estas interpretata lingvo ne bezonanta antaŭan tradukadon; " +"tial wheel enhavas nur ``.py``-dosierojn, same kiel fonta distribuo." + +#: ../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 "" +"Se vi scivolas pri bajtkodaj ``.pyc``-dosieroj, ili ne inkluziviĝas en " +"wheel, ĉar ili estas facile generebla, kaj inkluzivi ilin nenecese estigus " +"po unu wheel por ĉiu Python-versio por multaj pakoj, anstataŭ ununura pako. " +"Anstataŭe, instalilo kiel :ref:`pip` generas ilin dum instalado de la pako." + +#: ../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 "" +"Tamen, ekzistas gravaj diferencoj inter fontaj distribuo kaj wheel, eĉ por " +"pure Python-a projekto. Wheel intence enhavas nur tiom, kiom estas " +"instalota, kaj neniom pli. Specife, wheel ne inkluzivu testojn kaj " +"dokumentaron, dum fonta distribuo ja ofte inkluzivas ilin. Ankaŭ, la " +"dosierformo wheel estas pli komplika ol fonta distribuo. Ekzemple, ĝi " +"inkluzivas speciala dosieron nomitan ``RECORD`` listigantan ĉiujn dosierojn " +"en wheel kune kun haketaĵoj de la enhavoj por kontroli la integrecon de la " +"elŝutaĵo." + +#: ../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 "" +"Vi eble scivolas, ĉu wheel estas vere necesa por «simpla kaj baza» pure " +"Python-a projekto. Pro la fleksebleco de fonta distribuo, instalilo kiel pip " +"ne povas rekte instali fontan distribuon – ĝi devas unue konstrui wheel " +"per :term:`konstrua malfasado ` specifita de la fonta " +"distribuo (la konstrua malfasado povas ĉiel transformi konstruante la wheel, " +"kiel ekzemple traduki C-etendaĵojn). Tial, eĉ por pure Python-a projekto, vi " +"ĉiam alŝutu kaj fontan distribuon kaj wheel al PyPI aŭ alia pakindekso. Tio " +"multe plirapidigas instaladon por uzantoj, ĉar wheel estas rekte instalebla. " +"Inkluzivante nur instalendajn dosierojn, wheel ankaŭ estas malpli granda por " +"elŝuti." + +#: ../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 "" +"Teĥnike, wheel estas ZIP-arĥivo (malkiel fonta distribuo, kiu estas TAR-" +"arĥivo). Oni povas inspekti la enhavojn malpakante ĝin kiel ordinaran ZIP-" +"arĥivon, ekz., per ``unzip`` sur Uniksaj platformoj kiel Linux kaj macOS, " +"``Expand-Archive`` en Powershell sur Windows aŭ :ref:`la komandlinia fasado " +"de la modulo zipfile de Python `. Tio povas esti " +"utilega por kontroli, ĉu rado inkluzivas ĉiujn dosierojn bezonatajn." + +#: ../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 "" +"Ene de wheel troviĝas la dosieroj de la pako kaj ekstra dosierujo " +"nomita :samp:`{paknomo}-{versio}.dist-info`. Tiu dosierujo enhavas diversajn " +"dosierojn, inkluzive de dosiero ``METADATA``, kiu ekvivalentas ``PKG-INFO`` " +"en fonta dstribuo, kaj ``RECORD``. Tio utilas por certigi, ke neniu dosiero " +"mankas en wheel." + +#: ../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 "" +"La dosiernomo de wheel (ignorante kelkajn maloftajn trajtojn) aspektas " +"jene: :samp:`{nomo_de_pako}-{versio}-{python_etikedo}-{abi_etikedo}-" +"{platforma_etikedo}.whl`. Tiu nomada konvencio identigas tiujn platformojn " +"kaj Python-versiojn, kun kiuj la wheel kongruas. Ekzemple, la nomo " +"``pip-23.3.1-py3-none-any.whl`` signifas la jenon:" + +#: ../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 "" +"(``py3``) Ĉi tiu wheel estas instalebla sur ajna realigo de Python 3, ĉu " +"CPython, la plej ĝenerale uzata realigo de Python, aŭ alternativa realigo " +"kiel PyPy_;" + +#: ../source/discussions/package-formats.rst:124 +msgid "(``none``) It does not depend on the Python version;" +msgstr "(``none``) Ĝi ne dependas de la versio de Python;" + +#: ../source/discussions/package-formats.rst:125 +msgid "(``any``) It does not depend on the platform." +msgstr "(``any``) Ĝi ne dependas de la platformo." + +#: ../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 "" +"La patroneo ``py3-none-any`` estas ofta por puraj Python-projektoj. Pakoj " +"kun etendaĵaj moduloj ofte eldonas plurajn wheel-ojn de pli komplikaj " +"etikedoj." + +#: ../source/discussions/package-formats.rst:130 +msgid "" +"All technical details on the wheel format can be found in the :ref:`wheel " +"specification `." +msgstr "" +"Ĉiaj teĥnikaj detaloj pri la dosierformo wheel troviĝas en la :ref:`specifo " +"pri wheel `." + +#: ../source/discussions/package-formats.rst:138 +msgid "What about eggs?" +msgstr "Kio pri egg?" + +#: ../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 "" +"«Egg» estas malnova pakformo anstataŭigita per la formo wheel. Ĝi ne plu " +"estu uzata. Ekde la Aŭgusto de 2023, PyPI `malakceptas alŝuton de egg `_." + +#: ../source/discussions/package-formats.rst:144 +msgid "Here's a breakdown of the important differences between wheel and egg." +msgstr "Jen la gravaj diferencoj inter wheel kaj egg." + +#: ../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 "" +"La formo egg estis enkondukita de :ref:`setuptools` en 2004, dum la formo " +"wheel estis enkondukita de :pep:`427` en 2012." + +#: ../source/discussions/package-formats.rst:149 +msgid "" +"Wheel has an :doc:`official standard specification `. Egg did not." +msgstr "" +"Wheel havas :doc:`oficialan norman specifon `. Specifo ne ekzistis pri Egg." + +#: ../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 "" +"Wheel estas :term:`distribua ` formo, alivorte pakada " +"formo. [#wheel-importable]_ Egg estis kaj distribua formo kaj rultempa " +"instala formo (se ĝi restis zip-densigita) kaj estis intence importebla." + +#: ../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 "" +"Wheel-arĥivo ne inkluzivas ``.pyc``-dosierojn. Tial, se la distribuo nur " +"enhavas Python-dosierojn (kaj ne tradukitajn etendaĵojn), kaj kongruas kun " +"Python 2 kaj 3, ĝi povas esti «universala» simile al :term:`fonta distribuo " +"`." + +#: ../source/discussions/package-formats.rst:161 +msgid "" +"Wheel uses standard :ref:`.dist-info directories `. Egg used ``.egg-info``." +msgstr "" +"Wheel uzas la norman :ref:`dosierujon .dist-info `. Egg uzis ``.egg-info``." + +#: ../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 "" +"Wheel havas :ref:`pli riĉan dosiernoman konvencion `. " +"Unu wheel-arĥivo povas indiki sian kongruecon kun pluraj versioj de la " +"lingvo Python, de realigoj de Python, de ABI-oj kaj de sistemaj arĥitekturoj." + +#: ../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 "" +"Wheel estas versihava. Ĉiu wheel-dosiero enhavas la versiojn de la wheel-" +"specifo kaj la realigon pakinte ĝin." + +#: ../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 "" +"Wheel estas interne organizita laŭ `dosierlokaj tipoj de sysconfig `_, " +"plifaciligante konverti ali aliaj formoj." + +#: ../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 "" +"Ĉi tiu formo estas retmesaĝo-baza. Kvankam ĝi estus neverŝajne elektita " +"hodiaŭ, ĝi restas kiel la kanona formo pro retrokongrueco. Por la uzanto, " +"tio estas plejparte nevidebla, ĉar la metadatenoj estas specifitaj de la " +"uzanto en maniero komprenita de la konstrua malfasado, ofte ``[project]`` en " +"``pyproject.toml`,` kaj tradukitaj de la konstrua malfasado al ``PKG-INFO``." + +#: ../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 "" +"Kelkfoje, wheel povas esti uzata kiel importabla rultempa formo, " +"kvankam :ref:`aktuale tio ne estas oficiale subtenata `." + +#: ../source/discussions/pip-vs-easy-install.rst:6 +msgid "pip vs easy_install" +msgstr "pip kontraste kun easy_install" + +#: ../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 `, nun `evitinda `_, estis " +"eldonita en 2004 kiel parto de :ref:`setuptools`. Tiam, ĝi estis utila por " +"instali :term:`pakojn ` el :term:`PyPI ` uzante postulo-specifilojn kaj aŭtomate instali dependaĵojn." + +#: ../source/discussions/pip-vs-easy-install.rst:14 +#, fuzzy +#| 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." +msgid "" +":ref:`pip` came later in 2008, as an 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:`pip` venis poste en 2008, kiel alternativo al :ref:`easy_install " +"`, kvankam ĝi plejparte baziĝis sur la komponantoj " +"del :ref:`setuptools`. Tiutempe, ĝi notinde *ne* instalis pakon " +"kiel :term:`Egg ` aŭ de :term:`Egg ` (sed simple kiel «platan» " +"pakon de :term:`fonta distribuo `), kaj " +"enkondukis :ref:`Postulo-Dosierojn `, ebligante " +"uzanton facile reprodukti mediojn." + +#: ../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 "Jen la gravaj diferencoj inter pip kaj la evitinda easy_install:" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "**pip**" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "**easy_install**" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "Instali el :term:`Wheel `" + +#: ../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 "Jes" + +#: ../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 "Ne" + +#: ../source/discussions/pip-vs-easy-install.rst:30 +msgid "Uninstall Packages" +msgstr "Malinstali Pakojn" + +#: ../source/discussions/pip-vs-easy-install.rst:30 +msgid "Yes (``python -m pip uninstall``)" +msgstr "Jes (``python -m pip uninstall``)" + +#: ../source/discussions/pip-vs-easy-install.rst:32 +msgid "Dependency Overrides" +msgstr "Anstataŭigo de Dependeco" + +#: ../source/discussions/pip-vs-easy-install.rst:32 +msgid "Yes (:ref:`Requirements Files `)" +msgstr "Jes (:ref:`Postulo-Dosieroj `)" + +#: ../source/discussions/pip-vs-easy-install.rst:35 +msgid "List Installed Packages" +msgstr "Listigi instalitajn pakojn" + +#: ../source/discussions/pip-vs-easy-install.rst:35 +msgid "Yes (``python -m pip list`` and ``python -m pip freeze``)" +msgstr "Jes (``python -m pip list`` kaj ``python -m pip freeze``)" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "Subteno de :pep:`438`" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Installation format" +msgstr "Instala dosierformo" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "'Flat' packages with :file:`egg-info` metadata." +msgstr "Plata pako kun metadatenoj en :file:`egg-info`." + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "Enkapsuligita Egg-formo" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "modifado de sys.path" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "Instalas de :term:`Egg `" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "`subteno de pylauncher `_" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "Jes [1]_" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr ":ref:`Plurversiaj Instaloj `" + +#: ../source/discussions/pip-vs-easy-install.rst:57 +msgid "Exclude scripts during install" +msgstr "Ekskluzivi programetojn dum instalado" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "per project index" +msgstr "unu-projekta indekso" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Only in virtualenv" +msgstr "Nur en virtualenv" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "Jes, per setup.cfg" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +#, fuzzy +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" +"https://setuptools.readthedocs.io/en/latest/easy_install.html#natural-script-" +"launcher" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "Ĉu ``setup.py`` estas evitinda?" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "Ne, :term:`setup.py` kaj :ref:`setuptools` ne estas evitindaj." + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" +"Setuptools estas bone uzebla kiel :term:`konstrua malfasado ` " +"por paki Python-projektojn. Kaj :file:`setup.py` estas valida agorda dosiero " +"por :ref:`setuptools`, kiu estas verkita en Python anstataŭ *TOML* ekzemple " +"(ion similan faras aliaj iloj kiel *nox* per sia agorda " +"dosiero :file:`noxfile.py` kaj *pytest* per sia :file:`conftest.py`)." + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" +"Tamen, ``python setup.py`` kaj la uzado de :file:`setup.py` kiel komandlinia " +"ilo estas evitindaj." + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "Tio signifas, ke oni **NE UZU** la ĉi-subajn komandojn:" + +#: ../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 "Kiuj komandoj mi uzu anstataŭe?" + +#: ../source/discussions/setup-py-deprecated.rst:33 +#: ../source/guides/modernize-setup-py-project.rst:30 +msgid "Deprecated" +msgstr "Evitindaj" + +#: ../source/discussions/setup-py-deprecated.rst:33 +#: ../source/guides/modernize-setup-py-project.rst:30 +msgid "Recommendation" +msgstr "Rekomendo" + +#: ../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]_" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" +"Tio postulas la dependaĵon :ref:`build`. Estas rekomendate ĉiam konstrui kaj " +"eldoni kaj la fontan distribuon kaj la wheel de projekto; tion faras la " +"komando ``python -m build``. Laŭbezone oni povas uzi la flagojn ``--sdist`` " +"kaj ``--wheel`` por generi nur unu aŭ la alia." + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" +"Por instali setuptools-bazan projekton, oni ofte rulis la komandon " +"``install`` de :file:`setup.py``, kiel ekzemple ``python setup.py install``. " +"Nuntempe, la rekomendata metodo estas uzi :ref:`pip` rekte per la jena " +"komando: ``python - m pip install .`` en kiu la punkto ``.`` estas " +"dosiersistema loko, la aktuala dosierujo. Fakte, *pip* akceptas la lokan " +"dosiersisteman lokon de la projekta fontarba dosierujo kiel argumenton al " +"sia subkomando ``install``. Tiel, jen alia valida komando: ``python - m pip " +"install loko/de/projekto``." + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" +"Por instalo en *evoluada* (aŭ *modifebla*) reĝimo, anstataŭ ``python " +"setup.py develop`` oni uzu la flagon ``--editable`` de la subkomando " +"*install* de pip: ``python -m pip install --editable .``." + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" +"Unu rekomendata kaj simpla metodo por konstrui :term:`fontan distribuon " +"` kaj :term:`wheel ` estas uzi la " +"ilon :ref:`build` kun komando kiel ``python -m build``, kiu generas ambaŭ " +"distribuajn formojn. Laŭbezone oni povas uzi la flagojn ``--sdist`` kaj ``--" +"wheel`` por nur generi unu aŭ la alian. Notu, ke la ilo ``build`` devas esti " +"aparte instalita." + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" +"La komando ``python setup.py install`` evitindiĝis en setuptools versio " +"*58.3.0*." + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "Kio pri aliaj komandoj?" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "Kiuj estas anstataŭaĵoj por la aliaj komandoj ``python setup.py``?" + +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "``python setup.py test``" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "Ni rekomendas uzi testilon kiel pytest_." + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" +"``python setup.py check``, ``python setup.py register``, kaj ``python " +"setup.py upload``" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "Fidinda anstataŭaĵo estas :ref:`twine`:" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "``python -m twine check --strict dist/*``" + +#: ../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/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "``python -m twine upload dist/*``" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" +"Ne necesa nek subtenata ĉe :term:`PyPI `. Tamen " +"ĝi eble necesas ĉe aliaj :term:`pakindeksoj ` " +"(ekzemple :ref:`devpi`)." + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "``python setup.py --version``" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "Ebla solvo (interalie) estas anstataŭe uzi setuptools-scm_:" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "``python -m setuptools_scm``" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "Aliaj komandoj" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "Ĉi tiu gvidilo ne sugestas anstataŭaĵojn por la ĉi-subaj komandoj:" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "``alias``" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "``bdist``" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "``bdist_dumb``" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "``bdist_egg``" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "``bdist_rpm``" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "``build``" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "``build_clib``" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "``build_ext``" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "``build_py``" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "``build_scripts``" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "``clean``" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "``dist_info``" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "``easy_install``" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "``editable_wheel``" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "``egg_info``" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "``install_data``" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "``install_egg_info``" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "``install_headers``" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "``install_lib``" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "``install_scripts``" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "``rotate``" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "``saveopts``" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "``setopt``" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "``upload_docs``" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "Kio pri propraj komandoj?" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" +"Same, propra :file:`setup.py`-komando estas evitinda. Ni rekomendas migri " +"tiajn proprajn komandojn al tasko-rulilo aŭ io simila. Jen kelkaj tiaj iloj: " +"chuy, make, nox aŭ tox, pydoit, pyinvoke, taskipy, kaj thx." + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "Kio pri propraj konstruaj paŝoj?" + +#: ../source/discussions/setup-py-deprecated.rst:168 +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 "" +"Ne evitindaj estas propraj konstrupaŝoj, kiuj ekzemple aŭ anstataŭigas " +"ekzistantaj paŝojn kiel ``build_py``, ``build_ext`` kaj ``bdist_wheel``, aŭ " +"aldonas novajn konstrupaŝojn. Tiuj estos aŭtomate alvokitaj." + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "Ĉu forviŝi ``setup.py``?" + +#: ../source/discussions/setup-py-deprecated.rst:177 +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 "" +"Kvankam la uzado de :file:`setup.py` kiel ruleblaĵo estas evitinda, ĝia " +"uzado kiel agorda dosiero por setuptools estas absolute bona. Probable neniu " +"modifo necesas pri :file:`setup.py`." + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "Ĉu ``pyproject.toml`` estas deviga?" + +#: ../source/discussions/setup-py-deprecated.rst:185 +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 "" +"Kvankam ĝi ankoraŭ ne absolute necesas, estas **REKOMENDEGATA** havi " +"dosieron :file:`pyproject.toml` ĉe la radiko de fontarbo de projekto, kies " +"enhavo estas jena:" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" +"La gvidilo :ref:`modernize-setup-py-project` havas pliajn detalojn pri tio." + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" +"La norma implicita konduto de :term:`konstrua fasado `, se " +"dosiero :file:`pyproject.toml` kaj ĝia tabelo ``[build-system]`` mankas, " +"estas supozi, ke :term:`la konstrua malfasado ` estas " +"setuptools." + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "Kial? Kio tio signifas?" + +#: ../source/discussions/setup-py-deprecated.rst:206 +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 "" +"Se mallonge diri, la rolo de setuptools reduktiĝis al nura konstrua " +"malfasado." + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "Kie mi povas legi plu pri tio?" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" +"`Kial vi ne rulu setup.py rekte (anglalingva) `__ far Paul Ganssle" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr ":doc:`setuptools:deprecated/commands`" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "Unufontigi la Projektan Version" + +#: ../source/discussions/single-source-version.rst:7 +msgid "Complete" +msgstr "Kompleta" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "7 Oktobro 2024" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" +"Ofte :term:`distribua Python-pako ` provizas " +"unu :term:`importan pakon `, kaj oni deziras, ke la rultempa " +"atributo ``__version__`` de la importa pako estu sama " +"kiel :func:`importlib.metadata.version` por la distribua pako " +"(laŭ :ref:`runtime-version-access`)." + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" +"Ofte oni deziras derivi la versian informon el versikontrolsistema *etikedo* " +"(kiel ``v1.2.3``) anstataŭ malaŭtomata ĝisdatigo en la fontkodo." + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" +"Kelkaj projektoj povas elekti simple ignori la obligon de datenoj, kaj " +"dependi de aŭtomata testado por certigi, ke la valoroj ne diverĝas." + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" +"Alternative, la konstrua sistemo de projekto povas ebligi difinadon de unu " +"fonto de vero pri la versia numero." + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "Ĝenerale, jen la opcioj:" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" +"Se la kodo estas en versikontrola sistemo (VKS), kiel ekzemple Git, do la " +"versio povas esti eltirita el la VKS." + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" +"La versio povas esti malaŭtomate enmetita en la " +"dosieron :file:`pyproject.toml` – kaj la konstrua sistemo povas kopii ĝin al " +"aliaj postulataj lokoj." + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" +"La versio povas esti rekte metita en la fontkodon – aŭ en specialcelan " +"dosieron kiel :file:`_version.txt` (kiu devas esti parto de la fonta " +"distribua pako de la projekto) aŭ kiel atributo en modulo " +"kiel :file:`__init__.py`. Do la konstrua sistemo povas eltiri ĝin el la " +"rultempa loko ĉe konstrua tempo." + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" +"Vidu la dokumentaron por via konstrua sistemo por la rekomendata metodo." + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" +"Kiam oni intencas, ke distribua pako kaj ĝia asociita importa pako havu la " +"saman version, ni rekomendas, ke la projekto havu aŭtomatan testkazon " +"certigantan, ke ``nomo_de_importa_pako.__version__`` kaj " +"``importlib.metadata.version(\"nomo-de-distribua-pako\")`` estu samaj (notu: " +"por multaj projektoj, ``nomo_de_importa_pako`` kaj ``nomo-de-distribua-" +"pako`` estos samaj)." + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "Pritraktado de Versioj far Konstruaj Sistemoj" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" +"Jen hiperligoj al dokumentaroj de konstrusistemoj por pritraktado de versiaj " +"signoĉenoj." + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "`Flit `_" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "`Hatchling `_" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" +"`PDM `_" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" +"`Setuptools `_" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "`setuptools_scm `_" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "src-aranĝo kontraste al plata aranĝo" + +#: ../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 "" +"La «plata aranĝo» signifas organizi la projektajn dosierojn en dosierujo aŭ " +"deponejo tiel, ke la diversaj agordaoj dosieroj kaj :term:`importaj pakoj " +"` estas ĉiuj en la supranivela dosierujo." + +#: ../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 "" +"La «src-aranĝo» diferencas de la plata aranĝo movanta la kodon importeblan " +"(t.e. ``import mia_pako``, ankaŭ konatan kiel :term:`importajn pakojn " +"`) en subdosierujon. Tiu subdosierujo estas ofte nomita " +"``src/``; tial la nomo «src-aranĝo»." + +#: ../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 "" +"Jen resumo de la gravaj kondutaj diferencoj inter src-aranĝo kaj plata " +"aranĝo:" + +#: ../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 "" +"La src-aranĝo postulas instaladon de la projekto por ruli ĝian kodon, dum la " +"plata aranĝo ne postulas tion." + +#: ../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 "" +"Tio signifas, ke la src-aranĝo necesigas ekstran paŝon en la evoluada " +"laborfluo de projekto (ofte :doc:`modifebla instalo ` uziĝas por evoluigado, kaj ordinara instalo uziĝas por " +"testado)." + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" +"La src-aranĝo malhelpas neintencitan uzadon de la evoluigata kopio de la " +"kodo." + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +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." +msgstr "" +"Tio gravas, ĉar la Python-interpretilo inkluzivas la aktualan dosierujon " +"kiel la unuan eron de la importa dosierlokaro. Tial, se en la aktuala " +"dosierujo ekzistas importa pako, kies nomo estas sama kiel instalita importa " +"pako, do la varianto en la aktuala dosierujo estos uzata. Tio povas kaŭzi " +"subtilajn misaĵojn de la pakado, rezultigante dosierojn mankantajn en la " +"distribuo." + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" +"La src-aranĝo avertas tion, tenante la importajn pakojn en dosierujo aparta " +"de la radika dosierujo de la projekto, certigante, ke la instalita kopio " +"uziĝos." + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" +"La src-aranĝo devigas, ke :doc:`redaktebla instalo < setuptools:userguide/" +"development_mode>` nur kapablas importi tiujn dosierojn, kiuj estas intence " +"importeblaj." + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" +"Tio estas speciale utila, kiam la modifebla instalo estas realigita per " +"`dosierloko-agorda dosiero `_ aldonanta la dosierujon al la importa dosierlokaro." + +#: ../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 "" +"La plata aranĝo aldonus aliajn projektaojn dosierojn (ekzemple " +"``README.md``, ``tox.ini``) kaj pakadajn/ilajn agordajn dosierojn (ekzemple " +"``setup.py``, ``noxfile.py``) al la importa dosierlokaro. Tio kaŭzus, ke " +"kelkaj importoj funkcius en modifebla instalo sed ne en ordinara instalo." + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "Ruli komandlinian fasadon el fonto per src-aranĝo" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" +"Pro la unue menciita kvalito de la src-aranĝo, oni ne povas ruli " +"komandlinian fasadon rekte de la :term:`fontarbo `, sed " +"devas instali la pakon en :doc:`Evoluada Reĝimo ` por testado. Se tio malutilias, oni povas antaŭmeti la " +"pakan dosierujon al :py:data:`sys.path` de Python, kiam oni rulas la " +"dosieron :file:`__main__.py`:" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +msgid "Versioning" +msgstr "Versiado" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "Jen diskuto pri ĉiuj flankoj de la versiado de Python-pakoj." + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "Validaj versiaj numeroj" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" +"Diversaj Python-projektoj uzas malsamajn versiajn skemojn pro siaj malsamaj " +"bezonoj. Tamen, por kongrui kun :ref:`pip` kaj aliaj iloj, ĉia projekto " +"devas observi flekseblan formon por versiaj identigiloj, pri kio la " +"aŭtoritata referenco estas la :ref:`specifo pri versio-specifiloj `. Jen kelkaj ekzemploj de versiaj numeroj [#version-examples]_:" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "Simpla versio (fina eldono): ``1.2.0``" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "Evoluanta eldono: ``1.2.0.dev1``" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "Alfa-eldono: ``1.2.0a1``" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "Beta-eldono: ``1.2.0b1``" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "Eldonkandidato: ``1.2.0rc1``" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "Posteldono: ``1.2.0.post1``" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" +"Posteldono de alfa-eldono (ebla, sed malrekomendata): ``1.2.0a1.post1``" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "Simpla versio kun nur du komponantoj: ``23.12``" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "Simpla versio kun nur unu komponanto: ``42``" + +#: ../source/discussions/versioning.rst:30 +#, fuzzy +#| msgid "A version with an epoch: ``1!1.0``" +msgid "A version with an epoch (discouraged): ``1!1.0``" +msgstr "Versio kun epoko: ``1!1.0``" + +#: ../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 "" +"Projektoj povas uzi ciklon de antaŭeldonoj por testado far uzantoj antaŭ " +"fina eldono. Laŭorde, jen la ŝtupoj: alfa-eldonoj, beta-eldonoj, " +"eldonkandidatoj, fina eldono. Pip kaj aliaj modernaj Python-pakistaliloj " +"apriore ignoras antaŭeldonojn decidadante la instalotan version de " +"dependaĵo, escepte de eksplicita postulo (ekzemple per ``pip install " +"pako==1.1a3`` or ``pip install --pre pako``)." + +#: ../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 "" +"Evoluada eldono celas subteni eldonadon dum frua parto de evoluada ciklo — " +"ekzemple, ĉiutaga konstruo aŭ konstruo el la plej nova fonto en Linux-" +"distribuo." + +#: ../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 "" +"Posteldono estas por korekti negravajn erarojn en fina eldono, kiuj ne " +"efikas sur la distribuita programo, kiel ekzemple korektado de eraro en la " +"eldonaj notoj. Oni ne uzu posteldonon por ripari cimon; por tio oni uzu " +"novan finan eldonon (ekz., alkremante la trian komponanton por semantika " +"versio)." + +#: ../source/discussions/versioning.rst:49 +#, fuzzy +#| 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." +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" +"Fine, epoko, kiuj estas malofte uzata, helpas ripari la ordon dum ŝanĝado de " +"la versia skemo. Ekzemple, se projekto uzas kalendaran versiadon, kun " +"versioj kiel 23.12, kaj ŝanĝas al semantika versiado, kun versioj kiel 1.0, " +"la komparo inter 1.0 kaj 23.12 estus malĝusta. Por korekti tion, la novaj " +"versiaj numeroj havu eksplicitan epokon, kiel «1!1.0», por esti pli novaj ol " +"la malnovaj versiaj numeroj." + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "Semantika versiado kaj kalendara versiado" + +#: ../source/discussions/versioning.rst:62 +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 "" +"Versia skemo estas formala maniero interpreti la segmentojn de versia numero " +"kaj decidi la sekvan versian numeron por nova eldono de pako. Ekzistas du " +"versiaj skemoj ofte uzataj por Python-pakoj: semantika versiado kaj " +"kalendara versiado." + +#: ../source/discussions/versioning.rst:69 +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 "" +"La projekta mastrumanto decidas la uzotan versian numeron. Tio signifas, ke " +"versia alkremento reflektas la opinion de la mastrumanto. Tiu opinio povas " +"devii de la percepto de la uzantoj pri la promesoj de la formaligita versia " +"skemo." + +#: ../source/discussions/versioning.rst:75 +#, fuzzy +#| 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." +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" +"Ekzistas konataj esceptoj por elektado de la sekva versia numero. La " +"mastrumanto povas konscie rompi la supozon, ke la lasta versio-segmento nur " +"enhavas retrokongruajn ŝanĝojn. Unu kazo estas por ripari sekurecan " +"vundeblaĵon. Eldono pro sekureco ofte nur modifas la lastan versio-" +"segmenton, sed havas neretrokongruajn ŝanĝojn." + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "Semantika versiado" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" +"La ideo de *semantika versiado* (aŭ SemVer) estas uzi tripartajn versiajn " +"numerojn, *maĵora.minora.flika*, je kiu la projekta aŭtoro alkrementas:" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "*maĵora* kiam nekongruaj API-ŝanĝoj okazas," + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "*minora* kiam funkcioj aldoniĝas retrokongrue, kaj" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "*flika*, kiam okazas retrokongruaj cimriparoj." + +#: ../source/discussions/versioning.rst:94 +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 "" +"Plimulto de Python-projektoj uzas skemon similan al semantika versiado. " +"Tamen, multaj projektoj, speciale la grandegaj, ne strikte observas " +"semantikan versiadon, ĉar multaj ŝanĝoj havas teĥnike rompantajn ŝanĝojn sed " +"efikas sur nur malgrandan frakcion da uzantoj. Tiaj projektoj ofte " +"alkrementas la maĵoran numeron tiam, kiam la nekongrueco estas multa aŭ por " +"signali ŝanĝon pri la projekto, ne por ĉia malgranda nekongrueco [#semver-" +"strictness]_. Inverse, alkremento de la maĵora versia numero kelkfoje " +"signalas signifajn sed retrokongruajn novajn funkciojn." + +#: ../source/discussions/versioning.rst:104 +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 "" +"Por tiuj projektoj, kiuj uzas striktan semantikan versiadon, tiu maniero " +"ebligas uzi :ref:`versio-specifilon de kongrua eldono `, per la operatoro ``~=``. Ekzemple, ``nomo ~= X.Y`` " +"proksimume ekvivalentas ``nomo >= X.Y, == X.*``, t.e., ĝi postulas minimume " +"la eldonon X.Y, kaj permesas ajnan pli novan eldonon kun pli granda Y kaj " +"sama X. Simile, ``nomo ~= X.Y.Z`` proksimume ekvivalentas ``nomo >= X.Y.Z, " +"== X.Y.*``, t.e., ĝi postulas minimume X.Y.Z kaj permesas pli novan eldonon " +"de samaj X kaj Y sed pli granda Z." + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" +"Python-projektoj uzantaj semantikan versiadon observu la regulojn 1–8 de la " +"`specifo Semantika Versiado 2.0.0 `_." + +#: ../source/discussions/versioning.rst:116 +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 "" +"The populara dokumentargenerilo :doc:`Sphinx ` estas ekzemplo " +"de projekto uzanta striktan semantikan versiadon (vidu la :doc:`regulojn pri " +"versiado de Sphinx `). La fama " +"scienckomputa pako :doc:`NumPy ` eksplicite uzas «malstriktan» " +"semantikan versiadon, je kiu eldono alkrementa la minoran version povas " +"enhavi neretrokongruajn API-ŝanĝojn (vidu la :doc:`regulojn pri versiado de " +"NumPy `)." + +#: ../source/discussions/versioning.rst:125 +msgid "Calendar versioning" +msgstr "Kalendara versiado" + +#: ../source/discussions/versioning.rst:127 +#, fuzzy +#| 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." +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 "" +"Semantika versiado ne taŭgas por ĉiaj projektoj, ekzemple por tiaj " +"projektoj, kiaj eldona plano estas regule tempobaza kun avertoj pri forigota " +"funkcio dum kelkaj eldonoj antaŭ la forigado." + +#: ../source/discussions/versioning.rst:131 +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 "" +"La ĉefavantaĝo de datobaza versiado aŭ `kalendara versiado `_ " +"(CalVer) estas, ke estas facile kompreni kiel malnova la baza funkciaro de " +"iu eldono estas nur per la versia numero." + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" +"Kalendara versia numero ordinare estas de la formo *jaro.monato* (ekzemple, " +"23.12 por Decembro 2023)." + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" +":doc:`Pip `, la norma Python-pakinstalilo, uzas kalendaran " +"versiadon." + +#: ../source/discussions/versioning.rst:143 +msgid "Other schemes" +msgstr "Aliaj skemoj" + +#: ../source/discussions/versioning.rst:145 +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 "" +"Seria versiado estas la plej simpla versia skemo konsistanta el unu enjreo " +"alkrementata po unu fojo por ĉiu eldono. Kvankam seria versiado estas tre " +"facile administrebla por la aŭtoro, ĝi estas malfacila por la uzanto, ĉar " +"seria versia numero enhavas neniom aŭ apenaŭon da informo pri retrokongrueco " +"de la API." + +#: ../source/discussions/versioning.rst:151 +#, fuzzy +#| 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." +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 "" +"Eblas kombinaĵoj de ĉi-supraj skemoj. Ekzemple, projekto povas kombini dato-" +"bazitajn versiojn kun seriajn versiojn, kreante skemon *jaro.serio*, kiu " +"klarigas la proksimuman aĝon de la eldono, sed ne postulas eldonan planon en " +"la jaro." + +#: ../source/discussions/versioning.rst:158 +#: ../source/specifications/version-specifiers.rst:114 +msgid "Local version identifiers" +msgstr "Loka versi-identigilo" + +#: ../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 "" +"Publika versio-identigilo celas subteni distribuadon per :term:`PyPI `. Python-pakiloj ankaŭ subtenas :ref:`lokan versio-" +"identigilon `, kiu identigas lokan evoluadan " +"konstruon ne por publika eldonado, aŭ modifitan varianton de eldono far " +"redistribuanto." + +#: ../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 "" +"Loka versio-identigilo konsistas el publika versio-identigilo sekvita de «+» " +"kaj loka versia etikedo. Ekzemple, pako kun Fedora-specifaj flikoj havus la " +"version «1.2.1+fedora.4». Alia ekzemplo estas versio komputita de setuptools-" +"scm_, kiu estas kromprogramo por setuptools leganta la version el Git-" +"datenoj. En Git-deponejo kun kelko da ŝanĝoj post la plej nova eldono, " +"setuptools-scm generas version kiel «0.5.dev1+gd00980f» aŭ, se la deponejo " +"havas nespuratajn ŝanĝojn, kiel «0.5.dev1+gd00980f.d20231217»." + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "Akiri versiajn informojn dum rultempo" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" +"Versiaj informoj por ĉiuj :term:`distribuaj pakoj ` " +"loke haveblaj en la aktuala medio estas akireblaj per la " +"funkcio :func:`importlib.metadata.version` en la norma biblioteko::" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" +"Multaj projektoj ankaŭ provizas version al la supranivela :term:`importa " +"pako ` per paknivela atributo ``__version__``::" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" +"Tiu teĥniko estas speciale utila por komandlinia programo, kies versio-peto " +"(kiel ekzemple ``pip -V``) devas ruliĝi rapide." + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" +"Eldonanto de pako, kiu volas certigi, ke la versioj de la distribua pako kaj " +"importa pako estu samaj, legu la diskuton :ref:`single-source-version` por " +"eblaj metodoj por fari tion." + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" +"Ĉar importaj pako kaj moduloj ne *devas* sciigi pri rultempa versia informo " +"tiel (vidu la neaprobitan proponon :pep:`PEP 396 <396>`), oni serĉu la " +"atributon ``__version__`` nur por tiuj interfacoj, por kiuj oni scias ke la " +"atributo ekzistas (kiel ekzemple projekto serĉanta sian propran version aŭ " +"la version de unu el siaj rektaj dependaĵoj). Alie, la serĉanta kodo " +"pritraktu la kazon, kiam la atributo mankas [#fallback-to-dist-version]_." + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" +"Kelkaj projektoj devas publikigi versiajn informojn de eksteraj API-oj, kiuj " +"ne estas la versio de la modulo mem. Tia projekto difinu sian projekto-" +"specifan manieron akiri la informon runtempe. Ekzemple, la modulo :mod:`ssl` " +"de la norma biblioteko provizas plurajn manierojn por atingi la version de " +"la biblioteko OpenSSL::" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" +"Pliaj ekzemploj de strangaj versiaj numeroj troviĝas en `artikolo `_ de Seth Larson." + +#: ../source/discussions/versioning.rst:229 +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 "" +"Por pli personaj vidpunktoj pri ĉi tiu temo, vidu la jenajn artikolojn: `far " +"Hynek Schlawak `_, `far Donald Stufft `_, `far Bernát Gábor `_, `far Brett " +"Cannon `_. Por humuro, legu pri ZeroVer_." + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" +"Plena listo rilatanta la supranivelajn importeblajn nomojn al la distribuo-" +"pakoj provizantaj tiujn importeblajn pakojn kaj modulojn estas akirebla per " +"la funkcio :func:`importlib.metadata.packages_distributions` de la norma " +"biblioteko. Tio signifas, ke kodo provanta raporti version por ĉiu " +"importebla nomo havas rimedon raporti ion, eĉ se atributo ``__version__`` " +"mankas. Nur moduloj de la norma biblioteko kaj moduloj disponigitaj per " +"maniero alia ol instalado de Python-pako ne havos versiajn informojn tiukaze." + +#: ../source/flow.rst:3 +msgid "The Packaging Flow" +msgstr "La Pakada Laborfluo" + +#: ../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 "" +"Jen dokumento resumanta la fluon pri eldonado/distribuado " +"de :term:`distribua pako `, ofte al la `Python-" +"Pakindekso `_. Ĝi estis verkita por eldonantoj " +"de pakoj, kiuj estas supozite la aŭtoroj de la pakoj." + +#: ../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 "" +"Kvankam la :doc:`lernilo ` priskribas la " +"procedon por prepari simplan pakon por eldonado, ĝi ne plene klarigas la " +"postulatajn paŝojn kaj dosierojn kaj la kialojn." + +#: ../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 "" +"Eldonado de pako postulas fluon el la fontkodo de la aŭtoro ĝis la Python-" +"medio de la uzanto. Jen la paŝoj de tiu fluo:" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" +"Havu fontarbon enhavantan la pakon. Tiu devenas tipe de versikontrola " +"sistemo (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 "" +"Preparu agordan dosieron priskribantan la pakajn metadatenojn (nomon, " +"version ktp) kaj la manieron konstrui la artefaktojn. Plej ofte tiu estas la " +"dosiero :dosiero:`pyproject.toml` malaŭtomate mastrumata en la fontarbo." + +#: ../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 "" +"Kreu konstruitajn artefaktojn seldontan al la pako-disdonada servo (kutime " +"PyPI); tiuj ordinare estas :term:`fonta distribuo (sdist) ` kaj unu aŭ pli da :term:`konstrutaj distribuoj " +"(wheel) `. Tiujn konstruas konstruilo uzante la agordan " +"dosieron de la antaŭa paŝo. Ofte estas nur unu ĝenerala wheel por pure " +"Python-a pako." + +#: ../source/flow.rst:35 +msgid "Upload the build artifacts to the package distribution service." +msgstr "Alŝutu la konstruitajn artefaktojn al la pak-distribua servo." + +#: ../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 "" +"Nun, la pako ĉeestas ĉe la pako-distribua servo. Por uzi la pakon, uzantoj " +"faru la jenon:" + +#: ../source/flow.rst:40 +msgid "" +"Download one of the package's build artifacts from the package distribution " +"service." +msgstr "" +"Elŝutu unu el la konstruitaj artefaktoj de la pako el la pak-distribua servo." + +#: ../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 "" +"Instalu ĝin en ĝis Python-medio, ordinare en la dosierujo ``site-packages``. " +"Tio povas postuli konstruadon aŭ tradukadon, kiu devas esti priskribita de " +"la pakaj metadatenoj." + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" +"La lastajn du paĵojn faras la ilo :ref:`pip`, kiam uzanto rulas ``pip " +"install``." + +#: ../source/flow.rst:50 +msgid "The steps above are described in more detail below." +msgstr "La ĉi-supraj paŝoj estas priskribitaj plidetale ĉi-sube." + +#: ../source/flow.rst:53 +msgid "The source tree" +msgstr "La fontarbo" + +#: ../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 "" +"La fontarbo enhavas la fontkodon de la pako, ofte el versikontrola sistemo. " +"La specifa versio de la kodo uzita por konstrui la artefaktojn ordinare " +"estas asociita al etikedo de la versio en la versikontrola sistemo." + +#: ../source/flow.rst:60 +msgid "The configuration file" +msgstr "La agorda dosiero" + +#: ../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 "" +"La agorda dosiero dependas de la ilo uzita por krei la konstruitajn " +"artefaktojn. La norma praktiko estas uzi dosieron :file:`pyproject.toml` en " +"la `dosierformo 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 "" +"Minimume, la dosiero :file:`pyproject.toml` bezonas tabelon ``[build-" +"system]`` specifante la konstruilon. Ekzistas multaj konstruiloj, interalie " +"inkluzive " +"de :ref:`flit`, :ref:`hatch`, :ref:`pdm`, :ref:`poetry`, :ref:`setuptools`, " +"`trampolim`_ kaj `whey`_. La dokumentaro de iu ilo klarigos la enhavon de la " +"tabelo ``[build-system]``." + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "Ekzemple, jen tabelo pri uzado de :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 "" +"Kun tia tabelo en la dosiero :file:`pyproject.toml`, :term:`konstrua fasado " +"` kiel :ref:`build` povas ruli la elektitan :term:`konstruan " +"malfasadon ` por krei la konstruitajn artefaktojn. La " +"konstrua malfasado povas ankaŭ provizi sian propran fasadon. Instalilo " +"kiel :ref:`pip` ankaŭ funkcias kiel fasado, kiam ĝi rulas la konstruan " +"malfasadon por instali el fonta distribuo." + +#: ../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 "" +"Tiu konstruilo, kiun vi elektas, determinas la postulatajn pliajn informojn " +"en la dosiero :file:`pyproject.toml`. Ekzemple, oni povas uzi la jenon:" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" +"tabelo ``[project]`` enhavanta la projektajn :doc:`Kernajn Metadatenojn ` (nomon, version, aŭtoron ktp)," + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "tabelo ``[tool]`` enhavantaj agordajn opciojn por specifaj iloj." + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" +"Vidu la :ref:`gvidilon pri pyproject.toml ` por " +"plenaj detaloj pri agordado de ``pyproject.toml``." + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "Konstruaj artefaktoj" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "La fonta distribuo (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 "" +"Fonta distribuo enhavas sufiĉon por instali de fonto la pakon en la Python-" +"medio de la uzanto. Tial, ĝi bezonas la pakan fonton, kaj ankaŭ povas " +"inkluzivi testojn kaj dokumentaron. Tio utilas por tiaj uzantoj, kiaj volas " +"programi kun viaj fontoj, aŭ kies sistemoj postulas lokan tradukadon " +"(ekzemple por C-etendaĵo)." + +#: ../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 "" +"La pako :ref:`build` scias kiel alvoki vian konstruilon por krei unu el la " +"jeno:" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" +"Aŭ via konstruilo povas provizi sian propran interfacon por krei fontan " +"distribuon." + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "La konstruita distribuo (wheel)" + +#: ../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 "" +"Konstruita distribuo enhavas nur tiujn dosierojn, kiuj necesas en la Python-" +"medio de uzanto. Instalado ne postulas tradukadon, kaj la wheel povas simple " +"esti malpakita al la dosierujo ``site-packages``. Tio plirapidigas kaj " +"plifaciligas instaladon." + +#: ../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 "" +"Pure Python-a pako tipe nur bezonas unu «generalan» wheel. Pako kun " +"tradukita duuma etendaĵo bezonas po unu wheel por ĉiu subtenata kombinaĵo de " +"Python-interpretilo, mastruma sistemo kaj ĉefprocesora arĥitekturo. Se taŭga " +"wheel ne haveblas, :ref:`pip` kaj aliaj iloj instalos la fontan distribuon." + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" +"Aŭ via konstruilo povas provizi sian propran interfacon por krei 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 "" +"La implicita konduto de :ref:`build` estas fari kaj fontan distribuon kaj " +"wheel el la fonto en la aktuala dosierujo; la ĉi-supraj ekzemploj estas " +"intence specifaj." + +#: ../source/flow.rst:159 +msgid "Upload to the package distribution service" +msgstr "Alŝuti al la paka distribua servo" + +#: ../source/flow.rst:161 +msgid "" +"The :ref:`twine` tool can upload build artifacts to PyPI for distribution, " +"using a command like:" +msgstr "" +"La ilo :ref:`twine` povas alŝuti konstruitajn artefaktojn al PyPI por " +"distribuo, uzante komandon kiel la jenon:" + +#: ../source/flow.rst:168 +msgid "Or, your build tool may provide its own interface for uploading." +msgstr "Aŭ, via konstruilo eble provizas sian propran interfacon por alŝutado." + +#: ../source/flow.rst:171 +msgid "Download and install" +msgstr "Elŝuti kaj instali" + +#: ../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 "" +"Nun, post eldonado de la pako, uzantoj povas elŝuti kaj instali la pakon en " +"siajn Python-mediojn. Oni faras tion per :ref:`pip`, uzante la jenan " +"komandon:" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" +"Uzantoj povas ankaŭ uzi aliajn ilojn kiel :ref:`pipenv`, :ref:`poetry`, " +"aŭ :ref:`pdm`." + +#: ../source/glossary.rst:3 +msgid "Glossary" +msgstr "Terminaro" + +#: ../source/glossary.rst:8 +msgid "Binary Distribution" +msgstr "Duuma Distribuo" + +#: ../source/glossary.rst:11 +msgid "" +"A specific kind of :term:`Built Distribution` that contains compiled " +"extensions." +msgstr "" +"Specifa speco de :term:`Konstruita Distribuo ` enhavanta " +"tradukitajn etendaĵojn." + +#: ../source/glossary.rst:14 +msgid "Build Backend" +msgstr "Konstrua Malfasado" + +#: ../source/glossary.rst:17 +#, fuzzy +#| msgid "" +#| "A library that takes a source tree and builds a :term:`source " +#| "distribution ` or :term:`built " +#| "distribution ` from it. The build is delegated to the " +#| "backend by a :term:`frontend `. All backends offer a " +#| "standardized interface." +msgid "" +"A library that takes a :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" +"Biblioteko prenanta fontarbon kaj konstruanta :term:`fontan distribuon " +"` or :term:`konstritan distribuon `. La :term:`fasado ` delegas la konstruadon al " +"la malfasado. Ĉia malfasado provizas normigitan interfacon." + +#: ../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 "" +"Ekzemploj de konstruaj malfasadoj estas :ref:`flit-core de flit " +"`, :ref:`hatchling de hatch `, :ref:`maturin`, :ref:`meson-" +"python`, :ref:`scikit-build-core`, kaj :ref:`setuptools`." + +#: ../source/glossary.rst:32 +msgid "Build Frontend" +msgstr "Konstrua Fasado" + +#: ../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 "" +"Ilo, rulebla de uzanto, kiu el arbitra fontarbo aŭ :term:`fonta distribuo " +"` konstruas fontan distribuon " +"aŭ :term:`wheel `. La faktan konstruadon faras la :term:`konstrua " +"malfasado ` de la fontarbo." + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "Ekzemploj de konstruaj fasadoj estas :ref:`pip` kaj :ref:`build`." + +#: ../source/glossary.rst:44 +msgid "Built Distribution" +msgstr "Konstruita Distribuo" + +#: ../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 :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 "" +":term:`Distribua ` formo enhavanta dosierojn kaj " +"metadatenojn, kiujn oni povas simple movi al la ĝustaj lokoj en la cela " +"sistemo por instalado. :term:`Wheel` estas unu ekzemplo, dum :term:`Fonta " +"Distribuo ` ne estas ekzemplo, ĉar ĝi " +"postulas tradukadon antaŭ instalado. Tio ne signifas, ke Python-dosiero " +"devas esti antaŭtradukita (:term:`Wheel` intence ne inkluzivas tradukitajn " +"Python-dosierojn). Vidu :ref:`package-formats` por pliaj informoj." + +#: ../source/glossary.rst:56 +msgid "Built Metadata" +msgstr "Konstruitaj Metadatenoj" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" +"La konkreta formo de :term:`Kerna Metadateno ` en " +"instalita :term:`Projekto ` (la dosiero ``METADATA``) " +"aŭ :term:`Distribua Arĥivo ` (``PKG-INFO`` " +"en :term:`fonta distribuo `, " +"``METADATA`` en :term:`Wheel`)." + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "Kernaj Metadatenoj" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" +"La :ref:`specifo ` kaj la aro de :term:`Kernaj Metadatenaj " +"Kampoj ` difinitaj de ĝi, pri la ĉefaj statikaj " +"atributoj de :term:`Distribua Pako ` " +"aŭ :term:`Instalita Projekto `." + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "Kerna Metadatena Kampo" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" +"Unu ŝlosilo-valoro-paro (aŭ sinsekvo de tiaĵoj de la sama nomo, por plurfoje " +"uzebla kampo) difinita en la specifo :term:`Kernaj Metadatenoj `kaj konservita en la :term:`Konstruitaj Metadatenoj `. Notinde, diferencas de :term:`Pyproject-Metadatena Ŝlosilo " +"`." + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "Distribua Arĥivo" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" +"La fizika distribua artefakto (ekz. dosiero sur disko) por :term:`Distribua " +"Pako `." + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "Distribua Pako" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" +"Versiohava arĥiva dosiero enhavanta Python-ajn :term:`pakojn `, :term:`modulojn `, kaj aliajn resursajn dosierojn por " +"distribui :term:`Eldonon `. La uzanto elŝutas kaj instalas la " +"arĥivan dosieron el Interreto." + +#: ../source/glossary.rst:97 +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 "" +"Distribua pako estas ofte simple nomata «pako» aŭ «distribuo», sed ĉi tiu " +"gvidilo uzas la plenan terminon tiam, kiam klareco necesas por eviti " +"konfuzon kun :term:`Importa Pako ` (kiu estas ankaŭ ofte " +"nomata «pako») aŭ alia speco de distribuo (ekz. Linux-distribuo aŭ distribuo " +"de la programlingvo Python), kiuj ofte estas simple nomataj «distribuo». " +"Vidu :ref:`distribution-package-vs-import-package` por detaloj pri la " +"diferencoj." + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "Egg" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" +"Formo de :term:`Konstruita Distribuo ` enkondukita " +"de :ref:`setuptools`, nun anstataŭita de :term:`Wheel`. Por detaloj, " +"vidu :ref:`egg-format`." + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "Etenda Modulo" + +#: ../source/glossary.rst:114 +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:`Modulo ` verkita en la malaltnivela lingvo de la Python-" +"realigo: C/C++ por Python, Java por Jython. Ofte en unu dinamike ŝargebla " +"antaŭtradukita dosiero, ekz. komunobjekta (``.so``) dosiero por Python-" +"etendaĵo sur Unikso, dinamike ŝargebla biblioteko (DLL, kun la dosiersufikso " +"``.pyd``) por Python-etendaĵo sur Windows, aŭ Java-klasdosiero por Jython-" +"etendaĵo." + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "Importa Pako" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" +"Python-modulo, kiu povas enhavi aliajn modulojn aŭ, rikure, aliajn pakojn." + +#: ../source/glossary.rst:127 +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 "" +"Oni ofte simple nomas importan pakon «pako», sed ĉi tiu gvidisto uzos la pli " +"longan terminon, kiam oni devas distingi ĝin de :term:`Distribua Pako " +"`, kiu ankaŭ ofte nomiĝas «pako». " +"Vidu :ref:`distribution-package-vs-import-package` por resumo de la " +"diferencoj." + +#: ../source/glossary.rst:133 +msgid "Installed Project" +msgstr "Instalita Projekto" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" +":term:`Projekto ` instalita por uzo kun Python-interpretilo " +"aŭ :term:`Virtuala Medio `, laŭ la " +"normo :ref:`recording-installed-packages`." + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "Konata Bona Aro (KGS)" + +#: ../source/glossary.rst:143 +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 "" +"Aro de distribuoj ĉe specifitaj versioj kongruaj inter si. Tipe oni rulas " +"testaron, antaŭ ol deklari iun aron konata bona aro. La terminon ofte uzas " +"kadroj kaj ilaroj konsistantaj el multaj distribuoj." + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "Licenco-Klasigilo" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" +"Klasigilo PyPI Trove (:ref:`laŭ ` la " +"specifo :term:`Kernaj Metadatenoj `) komenciĝanta per " +"``License ::``." + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "Licenco-Esprimo" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "SPDX-Esprimo" + +#: ../source/glossary.rst:161 +#, fuzzy +#| msgid "" +#| "A string with valid SPDX license expression syntax, including one or more " +#| "SPDX :term:`License Identifier`\\(s), which describes a :term:`Project`'s " +#| "license(s) and how they inter-relate. Examples: ``GPL-3.0-or-later``, " +#| "``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" +"Signoĉeno de valida SPDX-licenco-esprima sintakso, inkluzivante unu aŭ pli " +"da :term:`Licenco-Identigilo(j) `, priskribanta(j) " +"licenco(j)n de la :term:`Projekto ` kaj iliajn interrilatojn. " +"Ekzemple: ``GPL-3.0-or-later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "Licenco-Identigilo" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "SPDX-Identigilo" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" +"Valida mallongforma licenco-identigilo de SPDX, originale specifita " +"en :pep:`639`. Tio inkluzivas ĉiujn validajn SPDX-identigilojn kaj la " +"proprajn signoĉenojn ``LicenseRef-[identigilo]`` konformajn al la normo " +"SPDX. Ekzemple: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-Mia-Propra-Licenco``" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "Modulo" + +#: ../source/glossary.rst:186 +msgid "" +"The basic unit of code reusability in Python, existing in one of two " +"types: :term:`Pure Module`, or :term:`Extension Module`." +msgstr "" +"La baza unuo de reuzebla kodo en Python, en unu el la du jenaj " +"tipoj: :term:`Pura Modulo ` aŭ :term:`Etendaĵa Modulo " +"`." + +#: ../source/glossary.rst:189 +msgid "Package Index" +msgstr "Pakindekso" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" +"Deponejo de distribuoj kun TTT-fasado por aŭtomatigi serĉadon kaj uzadon " +"de :term:`pakoj `." + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "Unu-Projekta Indekso" + +#: ../source/glossary.rst:198 +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 "" +"Privata aŭ alia nekanona :term:`Pakindekso ` indikita de " +"specifa :term:`Projekto ` kiel la indekso preferata aŭ postulata " +"por solvi dependecojn de tiu projekto." + +#: ../source/glossary.rst:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "Projekto" + +#: ../source/glossary.rst:205 +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 "" +"Biblioteko, kadro, programeto, kromprogramo, aplikprogramo, datenaro aŭ alia " +"resurso, aŭ iu kombinaĵo de tiuj, pakotaj en :term:`Distribuon `." + +#: ../source/glossary.rst:209 +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 "" +"Ĉar la plejparto de projektoj kreas :term:`Distribuojn ` per aŭ ``build-system`` de :pep:`518`, aŭ :ref:`distutils`, " +"aŭ :ref:`setuptools`, alia aktuala praktika difino de projekto estas iu " +"enhavanta dosieron :term:`pyproject.toml`, :term:`setup.py`, " +"aŭ :term:`setup.cfg` ĉe la radiko de la projekta fonta dosierujo." + +#: ../source/glossary.rst:215 +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-projekto devas havi unikan nomon, registritan ĉe :term:`PyPI `. Ĉiu projekto enhavas unu aŭ plurajn :term:`Eldonojn " +"`, kaj ĉiu eldono konsistas el unu aŭ pluraj :term:`distribuoj " +"`." + +#: ../source/glossary.rst:220 +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 "" +"Notu, ke ekzistas forta konvencio nomi projekton laŭ la nomo de la pako " +"importebla por ruli tiun projekton. Tamen, tio ne necesas. Eblas instali " +"distribuon de projekto «foo», kiu provizas pakon importeblan nur kiel «bar»." + +#: ../source/glossary.rst:226 +msgid "Project Root Directory" +msgstr "Projekta Radika Dosierujo" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" +"La dosiersistema dosierujo, en kiu troviĝas la term:`fontarbo ` de :term:`projekto `." + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "Projekta Fontarbo" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" +"La surdiska formo de :term:`Projekto ` uzata por evoluigado, " +"enhavanta la krudan fontkodon antaŭ pakado en :term:`Fontan Distribuon " +"` aŭ :term:`Konstruitan Distribuon " +"`." + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "Projektaj Fontaj Metadatenoj" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "Pura Modulo" + +#: ../source/glossary.rst:257 +msgid "" +"A :term:`Module` written in Python and contained in a single ``.py`` file " +"(and possibly associated ``.pyc`` and/or ``.pyo`` files)." +msgstr "" +":term:`Modulo ` verkita en Python kaj en unu dosiero ``.py`` (kaj " +"eble asociitaj dosieroj ``.pyc`` kaj/aŭ ``.pyo``)." + +#: ../source/glossary.rst:260 +msgid "Pyproject Metadata" +msgstr "Pyproject-Metadatenoj" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +msgid "Pyproject Metadata Key" +msgstr "Pyproject-Metadatena Ŝlosilo" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" +"Supranivela TOML-ŝlosilo en la tabelo ``[project]`` en ``pyproject.toml``; " +"parto de la :term:`Pyproject-Metadatenoj `. Notindas, ke " +"ĝi ne estas :term:`Kerna Metadatena Kampo `." + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "Pyproject-Metadatena Subŝlosilo" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" +"Duanivela TOML-ŝlosilo sub tabelo-valora :term:`Pyproject-Metadatena Ŝlosilo " +"`." + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "Python-Pakada Aŭtoritato (PyPA)" + +#: ../source/glossary.rst:287 +#, fuzzy +#| 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 `__." +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" +"PyPA estas laborgrupo mastrumanta multajn projektojn pri pakado de Python. " +"Ĝia retejo estas :doc:`pypa.io `. Ĝi gastigas projektojn ĉe " +"`GitHub `_ kaj `Bitbucket `_ kaj diskutas problemojn ĉe `la dissendolisto distutils-sig `_ kaj `la forumo " +"Discourse por Python `__." + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "Python-Pakindekso (PyPI)" + +#: ../source/glossary.rst:298 +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 `_ estas la ĉefa :term:`pakindekso ` " +"por la Python-komunumo. Ĉiu Python-programisto povas uzi ĝin por uzi kaj " +"distribui siajn distribuojn." + +#: ../source/glossary.rst:301 +msgid "pypi.org" +msgstr "pypi.org" + +#: ../source/glossary.rst:304 +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 `_ estas la retadreso de la :term:`Python-" +"Pakindekso (PyPI) `. Ĝi anstataŭis la malnovan " +"retadreson, ``pypi.python.org``, en 2017. Ĝi funkciiĝas per :ref:`warehouse`." + +#: ../source/glossary.rst:308 +msgid "pyproject.toml" +msgstr "pyproject.toml" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" +"La ilo-sendependa :term:`projekta ` specifa dosiero. Difinita " +"en :pep:`518`." + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "Eldono" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" +"Kopio de :term:`Projekto ` ĉe iu punkto en tempo, indikita de " +"versia identigilo." + +#: ../source/glossary.rst:319 +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 "" +"Eldonado de versio povas necesigi publikigon de pluraj :term:`Distribuoj " +"`. Ekzemple, se oni eldonus version 1.0 de iu " +"projekto, oni povus disponigi ĝin kiel kaj fontan distribuon kaj Windows-" +"instalilan dosierformon." + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "Postulo" + +#: ../source/glossary.rst:327 +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 "" +"Specifo de instalota :term:`pako `. :ref:`pip`, la " +"instalilo rekomendata de :term:`PyPA `, " +"permesas diversajn formojn de «postuloj». Por pliaj detaloj, " +"vidu :ref:`pip:pip install`." + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "Postulo-Specifilo" + +#: ../source/glossary.rst:336 +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 "" +"Tekstoformo uzata de :ref:`pip` por instali pakojn el :term:`pakindekso " +"`. Por EBNF-diagramo de la tekstoformo, vidu :ref:`dependency-" +"specifiers`. Ekzemple, ``foo>=1.3`` estas postulo-specifilo, en kiu ``foo`` " +"estas la nomo de la projekto kaj ``>=1.3`` estas la :term:`versio-specifilo " +"`" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "Postulo-Dosiero" + +#: ../source/glossary.rst:344 +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 "" +"Dosiero enhavanta liston de :term:`Postuloj ` instaleblaj " +"per :ref:`pip`. Por plian informoj, vidu la dokumentaron de :ref:`pip` " +"pri :ref:`Postulo-Dosieroj `." + +#: ../source/glossary.rst:348 +msgid "Root License Directory" +msgstr "Radika Licenco-Dosierujo" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "Licenco-Dosierujo" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" +"La dosierujo, en kiu licenco-dosieroj troviĝas, en :term:`Projekta Fontarbo " +"`, :term:`Distribua Arĥivo ` " +"aŭ :term:`Instalita Projekto `. Por :term:`Projekta " +"Fontarbo ` aŭ :term:`Fonta Distribuo `, ĝi estas la :term:`Projekta Radika Dosierujo " +"`. Por :term:`Konstruita Distribuo ` aŭ :term:`Instalita Projekto `, ĝi estas " +"la dosierujo :file:`.dist-info/licenses/` de la wheel-arĥivo aŭ projekta " +"dosierujo respektive. Ankaŭ, la radika dosierujo, al kiu estas relativaj la " +"dosierlokoj en la :term:`Kerna Metadatena Kampo ` " +"``License-File``." + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "setup.py" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "setup.cfg" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" +"La projektaj specifaj dosieroj por :ref:`distutils` kaj :ref:`setuptools`. " +"Vidu ankaŭ :term:`pyproject.toml`." + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "Fonta Arĥivo" + +#: ../source/glossary.rst:375 +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 "" +"Arĥivo enhavanta la krudan fontkodon de :term:`Eldono `, antaŭ la " +"kreado de :term:`Fonta Distribuo ` " +"aŭ :term:`Konstruita Distribuo `." + +#: ../source/glossary.rst:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "Fonta Distribuo (aŭ «sdist»)" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "Sistema Pako" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "Pako en formo indiĝena al la mastruma sistemo, ekz. rpm aŭ dpkg." + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "Versio-Specifilo" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "Virtuala Medio" + +#: ../source/glossary.rst:405 +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 "" +"Izolita Python-medio, en kiu oni povas instali pakojn por iu programo, " +"anstataŭ tutsistema instalado. Por pliaj informoj, vidu :ref:`Krei kaj uzi " +"Virtualan Medion `." + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "Wheel-Formo" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "Wheel" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" +"La norma dosierformo por :term:`Konstruita Distribuo `, " +"origine enkondukita de :pep:`427` kaj difinita de la normo :ref:`binary-" +"distribution-format`. Vidu :ref:`package-formats` por pliaj informoj. Ne " +"konfuzu ĝin kun ĝia referenca realigo, :term:`la Projekto Wheel `." + +#: ../source/glossary.rst:421 +msgid "Wheel Project" +msgstr "Wheel-Projekto" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" +"La referenca realigo far PyPA de la :term:`Wheel-Formo `; " +"vidu :ref:`wheel`." + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "Aro de Laboro" + +#: ../source/glossary.rst:429 +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 "" +"Kolekto de importeblaj :term:`distribuoj `. Tiuj estas " +"la distribuoj en la variablo `sys.path`. Maksimume unu :term:`Distribuo " +"` por iu projekto povas ĉeesti en aro de laboro." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "Analizi la pakajn elŝutojn el PyPI" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" +"Ĉi tiu paragrafo priskribas kiel uzi la publikan statistikan datenaron pri " +"elŝutoj el PyPI por lerni pli pri elŝutoj de pako (aŭ pakoj) ĉe PyPI. " +"Ekzemple, oni povas uzi ĝin por malkovri la distribuojn de Python-versioj " +"uzitaj por elŝuti pakon." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "Fonaj informoj" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "PyPI ne montras statistikojn pri elŝutoj pro kelkaj kialoj: [#]_" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" +"**Ne kongrua kun Enhavo-Distribua Reto (CDN):** Statistikoj pri elŝutoj " +"ŝanĝadas. Inkluzivado de tiuj en projekto-paĝoj tre enkaŝmemorigitaj " +"postulus oftan eksvalidigon de la kaŝmemoro kaj igus la kaŝmemoron malpli " +"efika." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +msgid "" +"**Highly inaccurate:** A number of things prevent the download counts from " +"being accurate, some of which include:" +msgstr "" +"**Tre malpreciza:** Kelkaj problemoj malhelpas la precizecon de la kalkulado " +"de elŝutoj, interalie:" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "Elŝuta kaŝmemoro de ``pip`` (kiu malpliigas la kalkulon de eŝutoj)" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" +"Internaj aŭ neoficialaj speguloj (povas kaj pliigi kaj malpliigi elŝutajn " +"kalkulojn)" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "Pakoj ne gastigitaj de PyPI (por komparo)" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" +"Neoficialaj instaliloj aŭ provoj falsi la fojojn de elŝutado (kiuj pliigas " +"la nombron de elŝutoj)" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" +"Konataj historiaj problemoj pri datena kvalito (kiuj malpliigas la nombron " +"de elŝutoj)" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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 "" +"**Ne tre utila:** Ne veras, ke ju pli elŝutata projekto estas, des pli bona " +"ĝi estas!" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:37 +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 "" +"Resume, ĉar la valoro estas malalta pro diversaj kialoj, kaj la kostoj estas " +"altaj, tio ne estas efika uzo de limigitaj resursoj." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:42 +msgid "Public dataset" +msgstr "Publika datenaro" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" +"Alternative, `la projekto Linehaul `__ transigas elŝutajn protokolojn de PyPI al `Google BigQuery`_ " +"[#]_, konservitajn kiel publikan datenaron." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "Ekstarigi" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" +"Por uzi `Google BigQuery`_ por serĉi `la publikan statistikan datenaron pri " +"elŝutoj el PyPI `_, oni bezonas " +"havi konton ĉe Google kaj ŝalti la BigQuery API por projekto ĉe Google Cloud " +"Platform. Oni rajtas uzi maksimume po 1 terabajton da informpetoj en ĉiu " +"monato `uzante la senkostan tavolon de BigQuery sen kreditkarto `__" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "Navigu al la `reta fasado de BigQuery `_." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "Krei novan projekton." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" +"Ŝalti la `BigQuery API `__." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" +"Por pli detalaj instrukcioj pri kiel ekuzi BigQuery, legu `BigQuery " +"quickstart guide `__." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "Datena skemo" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" +"Linehaul skribas eron en tabelon ``bigquery-public-" +"data.pypi.file_downloads`` por ĉiu elŝuto. La tabelo enhavas informojn pri " +"la elŝutita dosiero kaj la maniero de elŝuto. Jen kelkaj utilaj kolumnoj en " +"la `tabela skemo `__:" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "Kolumno" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "Priskribo" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "Ekzemploj" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "timestamp" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "Dato kaj tempo" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "``2020-03-09 00:33:03 UTC``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "file.project" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "Nomo de projekto" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "``pipenv``, ``nose``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "file.version" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "Versio de pako" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "``0.1.6``, ``1.4.2``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "details.installer.name" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "Instalilo" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "pip, :ref:`bandersnatch`" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "details.python" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "Versio de Python" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "``2.7.12``, ``3.6.4``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "Utilaj informpetoj" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" +"Rulu informpetojn en la `reta fasado de BigQuery `_ " +"alklakante la butonon «Compose query»." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" +"Notu, ke la vicoj estas en dispartigita tabelo, kio limigas la koston de " +"informpetoj. Jen ekzemplaj informpetoj analizantaj lastatempajn elŝutojn " +"filtrante la kolumnon ``timestamp``." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "Kalkuli elŝutojn de pako" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" +"Jen informpeto kalkulanta la totalan nombron de elŝutoj de la projekto " +"«pytest»." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "num_downloads" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "26190085" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" +"Por kalkuli nur elŝutojn per pip, filtru la kolumnon " +"``details.installer.name``." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "24334215" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "Nombro de pakaj elŝutoj tra tempo" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" +"Por grupigi laŭ monatoj, uzu la funkcion ``TIMESTAMP_TRUNC``. Ankaŭ filtrado " +"per tiu kolumno reduktas la koston." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "1956741" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "2018-01-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "2344692" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "2017-12-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "1730398" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "2017-11-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "2047310" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "2017-10-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "1744443" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "2017-09-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "1916952" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "2017-08-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "Versioj de Python tra tempo" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" +"Eltiri la version de Python el la kolumno ``details.python``. Averto: tiu " +"informpeto pritraktas pli ol 500 gigabajtojn da datenoj." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "python" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "3.7" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "18051328726" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "3.6" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "9635067203" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "3.8" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "7781904681" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "2.7" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "6381252241" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "2026630299" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "3.5" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "1894153540" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "Akiri absolutajn hiperligojn al artefaktoj" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" +"Fojfoje utilas akiri absolutan hiperligon al elŝutebla artefakto ĉe PyPI per " +"la haketaĵo, ekz. se speciala projekto aŭ eldono estis forviŝita de PyPI. La " +"metadatena tabelo enhavas la kolumnon ``path``, kiu inkluzivas la haketaĵon " +"kaj la artefaktan dosiernomon." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" +"La generita retadreso ne estas stabila, sed aktuale ĝi kongruas kun la " +"retadreso ĉe kiu la PyPI-artefaktoj troviĝas." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "url" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +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/analyzing-pypi-package-downloads.rst:246 +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/analyzing-pypi-package-downloads.rst:248 +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/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "Avertoj" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" +"Aldone al la avertoj ĉi-supraj, Linehaul suferis de cimo, kiu kaŭzis tre " +"maltroan kalkuladon pri elŝutaj statistikoj antaŭ la 26a de Julio 2018. " +"Elŝutoj antaŭ tiu dato estas proporcie precizaj (ekz. la elcento de Python 2 " +"kontraste al Python 3), sed la reportataj totaloj estas pli-ol-dekoble " +"malgrandaj ol la realaj nombroj." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "Pliaj iloj" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" +"Krom la BigQuery-konzolo, ekzistas kelkaj ceteraj iloj utilaj por analizado " +"de elŝuta statistiko." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "``google-cloud-bigquery``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" +"Oni ankaŭ povas programe akiri la publikan statistikan datenaron pri elŝutoj " +"el PyPI per la API de BigQuery kaj la projekto `google-cloud-bigquery`_, la " +"oficiala klienta Python-biblioteko por BigQuery." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "``pypinfo``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" +"`pypinfo`_ estas komandlinia ilo por aliri al la datenaro, kapabla generi " +"plurajn utilajn informpetojn. Ekzemple, oni povas pridemandi la totalan " +"nombron de elŝutoj de pako per la komando ``pypinfo paknomo``." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "Instalu `pypinfo`_ per pip." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "Uzado:" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "``pandas-gbq``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" +"La projekto `pandas-gbq`_ permesas atingi informpetajn rezultojn per " +"`Pandas`_." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "Referencoj" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" +"`Retmesaĝo pri evitindigo de la Kalkuloj de Elŝutoj ĉe PyPI `__" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" +"`Retmesaĝo anoncanta datenaron pri PyPI ĉe BigQuery `__" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "Krei kaj malkovri kromprogramojn" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" +"Ofte dum verkado de programo aŭ biblioteko en Python, oni volas havi la " +"kapablon adapti aŭ aldoni pliajn funkciojn per **kromprogramo**. Ĉar Python-" +"pako estas aparte distribuata, la programo aŭ biblioteko eble volas aŭtomate " +"**malkovri** ĉiujn haveblajn kromprogramojn." + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "Ekzistas tri ĉefmanieroj igi kromaĵojn aŭtomate malkovreblaj:" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "`Uzi nomajn konvenciojn `_." + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "`Uzi nomspacajn pakojn `_." + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "`Uzi pakajn metadatenojn `_." + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "Uzi noman konvencion" + +#: ../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/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 "" +"Se vi instalis la kromaĵojn `Flask-SQLAlchemy`_ kaj `Flask-Talisman`_, do " +"``discovered_plugins`` estos:" + +#: ../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 "" +"Uzado de nomada konvencio por kromprogramoj permesas serĉi la :ref:`simplan " +"deponejan API-on ` de la Python-Pakindekso por ĉiuj " +"pakoj observantaj la nomandan konvencion." + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "Uzi nomspacajn pakojn" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" +"Oni povas uzi :doc:`nomspacan pakon ` por " +"starigi konvencion pri la lokoj de kromprogramoj kaj por trovi " +"kromprogramojn. Ekzemple, se oni igas la subpakon ``myapp.plugins`` nomspaca " +"pako, do alia :term:`distribuo ` povas disponigi " +"modulojn kaj pakojn al tiu nomspaco. Post instalo, oni povas " +"uzi :func:`pkgutil.iter_modules` por trovi ĉiujn modulojn kaj pakojn " +"instalitajn sub tiu nomspaco:" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" +"Specifado de ``myapp.plugins.__path__`` al :func:`~pkgutil.iter_modules` " +"kaŭzas serĉadon de moduloj rekte sub tiu nomspaco. Ekzemple, se oni instalus " +"distribuojn provizante la modulojn ``myapp.plugins.a`` kaj " +"``myapp.plugins.b``, do ``discovered_plugins`` estus la jeno:" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" +"Ĉi tiu ekzemplo uzas subpakon kiel la nomspacan pakon (``myapp.plugins``), " +"sed ankaŭ eblas uzi supranivelan pakon por tiu celo (ekzemple " +"``myapp_plugins``). Elektado de la uzota nomspaco laŭ onia gusto, sed ne " +"estas rekomendata igi la ĉefan supranivelan pakon (``myapp`` en la ekzemplo) " +"nomspaca pako pro kromprogramoj, ĉar unu aĉa kromprogramo rompus la plenan " +"nomspacon, malimportebligante vian projekton. Por la maniero «nomspaca " +"subpako», kromprograma pako devas ne inkluzivi la :file:`__init__.py` por la " +"supranivela paka dosierujo (``myapp`` en la ekzemplo) kaj inkluzivi la " +"nomspacpako-stilan :file:`__init__.py` en la nomspaca subpaka dosierujo " +"(``myapp/plugins``). Tio ankaŭ implicas, ke kromprogramo devas eksplicite " +"doni liston de pakoj kiel la argumenton ``packages`` de :func:`setup`, " +"anstataŭ uzi :func:`setuptools.find_packages`." + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" +"Nomspaca pako estas komplika funkcio, kaj estas pluraj malsamaj manieroj " +"krei iĝin. Estas rekomendegate legi la dokumentaron :doc:`packaging-" +"namespace-packages` kaj klare dokumenti la preferatan manieron por " +"kromprogramoj de via projekto." + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "Uzi pakajn metadatenojn" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" +"Pako povas enhavi metadatenojn pri kromprogramoj per :ref:`entry-points`. " +"Per tio, pako anoncas, ke ĝi enhavas ian kromprogramon. Alia pako subtenanta " +"tian kromprogramon povas uzi la metadatenojn por trovi tiun kromprogramon." + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" +"Ekzemple, se vi havas pakon nomitan ``myapp-plugin-a``, kies " +"``pyproject.toml`` enhavas la jenon:" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" +"Do oni povas serĉi kaj ŝargi ĉiujn registritajn enirpunktojn " +"per :func:`importlib.metadata.entry_points` (aŭ la `retroporto `_ " +"``importlib_metadata >= 3.6`` por Python 3.6 – 3.9):" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" +"En ĉi tiu ekzemplo, ``discovered_plugins`` estas kolekto de la " +"tipo :class:`importlib.metadata.EntryPoint`:" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" +"Nun via elektita modulo estas importebla per " +"``discovered_plugins['a'].load()``." + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" +"La specifo de ``entry_point`` en :file:`setup.py` estas fleksebla kaj opcio-" +"plena. Estas rekomendate tralegi la paragrafon pri :doc:`enirpunktoj " +"` ." + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" +"Ĉar ĉi tiu specifo estas parto de la :doc:`norma biblioteko `, multaj iloj krom setuptools subtenas difinadon de " +"enirpunktoj." + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "Krei kaj paki komandliniajn programojn" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +msgid "Creating the package" +msgstr "Krei la pakon" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" +"Unue, kreu fontarbon por la :term:`projekto `. Kiel ekzemplo, ni " +"verkos simplan ilon eligantan tekstan saluton dependantan de komandliniaj " +"argumentoj." + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "FIXME" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" +"Konsili pri la optimuma strukturo de Python-pako en alia gvidilo aŭ diskuto " +"kaj ligi al ĝi ĉi tie." + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" +"Ĉi tiu projekto sekvos la :ref:`src-aranĝon ` kaj " +"similas la jenan dosierarbon, kun supranivela dosierujo (kaj paknomo) nomita " +"``greetings``:" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" +"La reala kodo respondeca por la funkciado de la ilo troviĝos en la " +"dosiero :file:`greet.py`, nomita laŭ la ĉefmodulo:" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" +"La ĉi-supra funkcio ricevas plurajn ŝlosilvortajn argumentojn pri konstruado " +"de la saluto. Nun, konstruu la komandlinian fasadon kun la samaj argumentoj " +"en :file:`cli.py`:" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" +"La komandlinia fasado estas konstruita per typer_, kiu estas facile uzebla " +"komandlinia argumentanalizilo uzante tipo-konsiletoj de Python. Ĝi provizas " +"aŭtomatan kompletigon kaj bone aranĝitan komandlinian helpon senmodife. Alia " +"opcio estus :py:mod:`argparse`, kiu estas komandlinia argumentanalizilo " +"inkluzivita en la norma biblioteko de Python. Ĝi sufiĉas por la plejparto de " +"bezonoj, sed postulas multe da kodo, ofte en ``cli.py``, por bona funkciado. " +"Alterntaive, docopt_ kreas komandlinian fasadon nur per docstring; altnivela " +"uzanto uzu click_ (sur kiu ``typer`` estas bazita)." + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" +"Nun, aldonu malplenan dosieron :file:`__init__.py`, por marki la projekton " +"kiel ordinaran :term:`importan pakon `." + +#: ../source/guides/creating-command-line-tools.rst:88 +#, fuzzy +#| msgid "" +#| "The file :file:`__main__.py` marks the main entry point for the " +#| "application when running it via :mod:`runpy` (i.e. ``python -m " +#| "greetings``, which works immediately with flat layout, but requires " +#| "installation of the package with src layout), so initizalize the command-" +#| "line interface here:" +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" +"La dosiero :file:`__main__.py` estas la ĉefenirpunkto de la programo, kial " +"ĝi ruliĝas per :mod:`runpy` (t.e. ``python -m greetings``, kiu funkcias tuj " +"kun plata aranĝo sed postulas instaladon kun src-aranĝo). Tial, starigu la " +"komandlinian fasadon ĉi tie:" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" +"Por ebligi uzadon de la komandlinia fasado rekte de la :term:`fontarbo " +"`, ekzemple kiel ``python src/greetings``, oni povas " +"meti trukon en tiun dosieron; legu pri tio en :ref:`running-cli-from-source-" +"src-layout`." + +#: ../source/guides/creating-command-line-tools.rst:106 +msgid "``pyproject.toml``" +msgstr "``pyproject.toml``" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" +"La projektaj :term:`metadatenoj ` troviĝas " +"en :term:`pyproject.toml`. La :term:`metadatenaj ŝlosiloj pyproject " +"` kaj la tabelo ``[build-system]`` estu " +"laŭ :ref:`writing-pyproject-toml`, kun dependeco sur ``typer`` (ĉi tiu " +"lernilo uzas la version *0.12.3*)." + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" +"Por ke la projekto estu rekonebla kiel komandlinia ilo, krome " +"la :ref:`enirpunkto ` ``console_scripts`` " +"(vidu :ref:`console_scripts`) devas esti aldonita kiel :term:`subŝlosilo " +"`:" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" +"Nun, la fontarbo de la projekto pretas transformiĝi en " +"instaleblan :term:`distribuan pakon `." + +#: ../source/guides/creating-command-line-tools.rst:123 +msgid "Installing the package with ``pipx``" +msgstr "Instali la pakon per ``pipx``" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" +"Post instalo de ``pipx`` laŭ :ref:`installing-stand-alone-command-line-" +"tools`, instalu vian projekton:" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" +"Tio difinos la ruleblan programon kiel enirpunkton kaj disponigos la " +"komandon ``greet``. Ni elprovu:" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" +"Ĉar ĉi tiu ekzemplo uzas ``typer``, oni povas nun superrigardi la opciojn de " +"la programo per la flago ``--help`` aŭ agordi kompletigadon per la flago ``--" +"install-completion``." + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" +"Por simple ruli la programon sen malprovizora instalado, uzu ``pipx run``, " +"kiu kreos provizoran (sed enkaŝmemorigitan) virtualan medion por ĝi:" + +#: ../source/guides/creating-command-line-tools.rst:156 +#, fuzzy +#| msgid "" +#| "This syntax is a bit unpractical, however; as the name of the entry point " +#| "we defined above does not match the package name, we need to state " +#| "explicitly which executable script to run (even though there is only on " +#| "in existence)." +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" +"Tamen, tiu sintakso estas praktike netaŭga: ĉar la nomo de la enirpunkto " +"difinita ĉi-supre ne egalas la nomon de la pako, ni devas eksplici la " +"rulotan programon (malgraŭ la ekzisto de nur unu)." + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" +"Tamen ekzistas pli praktika solvo de tiu problemo: enirpunkto specifa al " +"``pipx run``. La sama estas difinebla jene en :file:`pyproject.toml`:" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" +"Dank’ al tiu enirpunkto (kiu *devas* kongrui kun la nomo de la pako), " +"``pipx`` trovos la ruleblan programon kiel la implicitaĵon kaj rulos ĝin. " +"Tio ebligas la jenan komandon:" + +#: ../source/guides/creating-command-line-tools.rst:176 +msgid "Conclusion" +msgstr "Konkludo" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "Paki kaj distribui projektojn" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "Eksvalidiĝinta" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "14 Decembro 2023" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" +"Ĉi tiu paragrafo diskutas pliajn detalojn pri agordado, pakado kaj " +"distribuado de Python-projektoj per ``setuptools`` ne menciitajn en la " +"enkonduka lernilo en :doc:`/tutorials/packaging-projects`. Ĝi supozas, ke vi " +"jam konas la enhavon de la paĝo :doc:`/tutorials/installing-packages`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" +"Ĉi tiu paragrafo *ne* celas rekomendi pri ĉiaj aspektoj de Python-" +"projektoj. Ekzemple, ĝi ne rekomendas ion ajn aŭ iun ajn ilon pri versio-" +"kontrolado, dokumentaro aŭ testado." + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" +"Por pli da referencaj informoj, vidu :std:doc:`Building and Distributing " +"Packages ` en la dokumentaro " +"de :ref:`setuptools`, sed notu, ke tieaj konsiloj povas esti eksvalidiĝinta. " +"Se ekzistas neakordo, preferu la konsilojn en la Manlibro por Python-Uzantoj " +"pri Pakado." + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "Postuloj por pakado kaj distribuado" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" +"Unue certigu, ke vi jam plenumis la :ref:`postulojn por instali pakojn " +"`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "Instali «twine» [1]_:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" +"Vi postulas tiun por alŝuti viajn projektajn :term:`distribuojn " +"` al :term:`PyPI ` " +"(vidu :ref:`ĉi-sube `)." + +#: ../source/guides/distributing-packages-using-setuptools.rst:52 +msgid "Configuring your project" +msgstr "Agordi vian projekton" + +#: ../source/guides/distributing-packages-using-setuptools.rst:56 +msgid "Initial files" +msgstr "Komencaj dosieroj" + +#: ../source/guides/distributing-packages-using-setuptools.rst:61 +msgid "" +"The most important file is :file:`setup.py` which exists at the root of your " +"project directory. For an example, see the `setup.py `_ " +"in the `PyPA sample project `_." +msgstr "" +"La plej grava dosiero estas :file:`setup.py` ĉe la radiko de via projekta " +"dosierujo. Por ekzemplo, vidu `setup.py `_ en " +"la `ekzempla projekto de PyPA `_." + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr ":file:`setup.py` havas du ĉeffunkciojn:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" +"Ĝi estas la komandlinian fasadon por rulado de diversaj komandoj pri pakado. " +"Por listo de haveblaj komandoj, rulu ``python3 setup.py --help-commands``." + +#: ../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` estas ini-dosiero enhavanta implicitajn valorojn de opcioj " +"por la komandoj de :file:`setup.py`. Por ekzemplo, vidu `setup.cfg `_ en la `ekzempla projekto de PyPA `_." + +#: ../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 "" +"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 "" +"Ĉiu projekto enhavo readme-dosieron pri la celoj de la projekto. La plej " +"ofta dosierformo estas `reStructuredText `_ kun dosiersufikso ``.rst``, sed tio ne estas deviga. Pluraj " +"variantoj de `Markdown `_ " +"estas ankaŭ subtenataj (vidu la " +"argumenton :ref:`long_description_content_type ` de " +"``setup()``)." + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" +"Por ekzemplo, vidu `README.md `_ en la `ekzempla projekto de PyPA `_." + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" +"Projekto uzanta :ref:`setuptools` 0.6.27+ havas normajn README-dosierojn " +"(:file:`README.rst`, :file:`README.txt`, aŭ :file:`README`) inkluzivitajn en " +"fonta distribuo implicite. La norma biblioteok :ref:`distutils` adoptas tiun " +"konduton ekde Python 3.7. Plie, :ref:`setuptools` 36.4.0+ " +"inkluzivas :file:`README.md`, se ĝi troviĝas. Se oni uzas setuptools, oni ne " +"bezonas inkluzivi la README-dosieron en :file:`MANIFEST.in`. Se ne, " +"inkluzivu ĝin eksplicite." + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "MANIFEST.in" + +#: ../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` necesas, kiam oni bezonas paki pliajn dosierojn ne " +"aŭtomate inkluzivotajn en fontan distribuon. Por detaloj pri verkado " +"de :file:`MANIFEST.in`, inkluzive de listo de aŭtomate inkluzivotaj " +"dosieroj, vidu :ref:`Uzi MANIFEST.in `." + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" +"Tamen, oni ne devas uzi :file:`MANIFEST.in`. Ekzemple, la `ekzempla projekto " +"de PyPA `_ ne plu " +"havas :file:`MANIFEST.in`, ĉar ĉiaj necesaj dosieroj inkluziviĝas " +"en :ref:`setuptools` ekde versio 43.0.0." + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr ":file:`MANIFEST.in` ne rilatas al duuma distribuo kiel wheel." + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "LICENSE.txt" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" +"Ĉiu pako havu licenco-dosieron pri la kondiĉoj de distribuado. En multaj " +"jurisdikcioj, pako sen eksplicita licenco ne estas uzebla nek distribuebla " +"far iu alia ol la kopirajto-posedanto. Se vi ne certas pri la licenco, vidu " +"`Choose a License `_ de GitHub, aŭ konsultu " +"advokaton." + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" +"Por ekzemplo, vidu `LICENSE.txt `_ en la `ekzempla projekto de PyPA `_." + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" +"Tamen tio ne necesas, la ofta praktiko estas inkluzivi Python-modulojn kaj " +"pakojn sub unu supranivela pako, kies nomo estas sama kiel (aŭ tre proksima " +"al) la :ref:`nomo ` de via projekto." + +#: ../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 "" +"Por ekzemplo, vidu la pakon `sample `_ en la `ekzempla projekto de PyPA `_." + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "argumentoj por setup()" + +#: ../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 "" +"Kiel menciite ĉi-supre, la ĉeftrajto de :file:`setup.py` estas, ke ĝi " +"enhavas mallokan funkcion ``setup()``. La ŝlosilvortaj argumentoj de tiu " +"funkcio difinas la detalojn de la projekto." + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" +"Kelkaj estas provizore klarigitaj ĉi-sube, ĝis kiam la informoj moviĝas " +"aliloken. La plena listo ĉeestas :doc:`ĉe la dokumentaro de setuptools " +"`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" +"Plejparto de la ekzemploj devenas de `setup.py `_ en " +"la `ekzempla projekto de PyPA `_." + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" +"Vidu :ref:`Elekti versian skemon ` por pli pri " +"kiel uzi version por komuniki informojn pri kongrueco al uzantoj." + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "``packages``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +msgstr "``py_modules``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:198 +msgid "" +"If your project contains any single-file Python modules that aren't part of " +"a package, set ``py_modules`` to a list of the names of the modules (minus " +"the ``.py`` extension) in order to make :ref:`setuptools` aware of them." +msgstr "" +"Se via projekto enhavas ajnan unu-dosieran Python-modulon ne en pako, agordu " +"``py_modules`` al listo de la nomoj de tiaj moduloj (sen la dosiersufikso " +"``.py``) por sciigi :ref:`setuptools`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +#, fuzzy +msgid "``install_requires``" +msgstr "install_requires" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" +"Oni uzu ``install_requires`` por specifi la minimumajn dependecojn de " +"projekto por rulado. Kiam :ref:`pip` instalas projekton, ĝi uzas tion por " +"instali dependaĵojn." + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" +"Por pli pri «install_requires», vidu :ref:`install_requires kontraste al " +"Postulo-dosiero `." + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "``package_data``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"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 "" +"Ofte oni devas instali pliajn dosierojn en :term:`pakon `. " +"Tiaj dosieroj estas ofte datenoj rilataj al la kodo de la pako, aŭ tekstoj " +"enhavantaj dokumentaron por programistoj uzantaj la pakon. Tiaj dosieroj " +"nomiĝas «pakaj datenoj»." + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" +"La valoro devas esti mapigo de paknomoj al listoj de relativaj dosierlokoj " +"kopiotaj en la pakojn. Dosierloko estas relativa al la dosierujo enhavanta " +"la pakon." + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" +"Por pliaj informoj, vidu la paragrafon :std:doc:`Inkluzivi Datenajn " +"Dosierojn ` en la :std:doc:`dokumentaro de " +"setuptools `." + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "``data_files``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" +"Por pliaj informoj, vidu la paragrafon pri distutils en :ref:`Installing " +"Additional Files `." + +#: ../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 "" +"Dum instalado de pako kiel egg, ``data_files`` ne estas subtenata. Do, se " +"projekto uzas :ref:`setuptools`, oni devas uzi ``pip`` por instali ĝin. " +"Alternative, se oni devas uzi ``python setup.py``, oni devas uzi la flagon " +"``--old-and-unmanageable``." + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +#, fuzzy +msgid "``scripts``" +msgstr "``description``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" +"Kvankam ``setup()`` subtenas ŝlosilvorton :ref:`scripts " +"` por antaŭfarita instalota " +"programeto, la rekomendata metodo por interplatforma kongrueco estas uzi " +"enirpunktojn :ref:`console_scripts` (vidu ĉi-sube)." + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "Elekti versian skemon" + +#: ../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 "" +"Vidu :ref:`versiadon ` por informoj pri oftaj versiaj skemoj kaj " +"kiel elekti inter ili." + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "Labori en «programada reĝimo»" + +#: ../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 "" +"Vi povas instali projekton en «modifebla» aŭ «programada» reĝimo, kiam vi " +"verkas ĝin. Se projekto estas modifeble instalita, ĝi estas modifebla enloke " +"sen reinstalado: ŝanĝoj al Python-fontdosieroj en modifeble instalita " +"projekto efektiviĝos, kiam la interpretila procezo relanĉiĝos." + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" +"Por instali Python-pakan en «modifebla»/«evoluata» reĝimo, iru al la radiko " +"de la projekta dosierujo, kaj rulu la jenon:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" +"La komandlinia flago ``-e`` de pip estas mallongigo de ``--editable``, kaj " +"``.`` signifas la aktualan labordosierujon. Tial kune tio signifas instali " +"la aktualan dosierujon (t.e. via projekto) en modifebla reĝimo. Tio ankaŭ " +"instalos ajnajn dependaĵojn deklaritajn per ``install_requires`` kaj ajnajn " +"programetojn deklaritajn per ``console_scripts``. Dependaĵoj instaliĝos en " +"la ordinara nemodifebla reĝimo." + +#: ../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::" +msgstr "" +"Oni eble volas ankaŭ instali kelkajn dependaĵon en modifebla reĝimo. " +"Ekzemple, se onia projekto postulus «foo» kaj «bar», kaj oni volus instali " +"«bar» el versikontrola sistemo en modifebla reĝimo, oni uzus la jenan " +"postulo-dosieron::" + +#: ../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 "" +"La unua linio instalas vian projekton kaj ĝiajn dependaĵojn. La dua linio " +"anstataŭigas la dependecon sur «bar», uzante versikontrolan sistemon, ne " +"PyPI." + +#: ../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 "" +"Tamen, se vi volas instali «bar» el loka dosierujo en modifebla reĝimo, la " +"postulo-dosiero estu jene, kun la lokaj dosierlokoj ĉe la supro de la " +"dosiero::" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "Laste, se vi ne volas instali ajnan dependaĵon, rulu la jenon:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" +"Por pli da informo, vidu la paragrafon :doc:`Evoluada Reĝimo " +"` de la dokumentaro " +"de :ref:`setuptools`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "Paki vian projekton" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" +"Por igi vian projekton instalebla ĉe :term:`Pakindekso ` " +"kiel :term:`PyPI `, vi kreu :term:`Distribuon " +"` (ankaŭ konatan kiel «:term:`pakon `») por via projekto." + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" +"Antaŭ ol konstrui wheel kaj fontan distribuon por via projekto, vi devas " +"instali la pakon ``build``:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "Fontaj distribuoj" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" +"Minimume, vi kreu :term:`Fontan Distribuon `:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" +"«Fonta distribuo» ne estas kontruita (alivorte, ĝi ne " +"estas :term:`Konstruita Distribuo `) kaj postulas paŝon " +"de konstruado dum instalado per pip. Eĉ se la distribuo konsistas nur el " +"Python (alivorte, etendaĵo mankas), konstruada paŝo necesas por konstrui la " +"instalajn metadatenojn el :file:`setup.py` kaj/aŭ :file:`setup.cfg`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "Wheel" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" +"Vi ankaŭ kreu wheel por via projekto. Wheel estas :term:`konstruita pako " +"` instalebla sen konstruado. Instalado de wheel estas " +"multe pli rapida ol instalado de fonta distribuo." + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" +"Se via projekto estas pure Python-a, do vi kreos :ref:`«Pure Python-an " +"Wheel» (vidu la ĉi-suban paragrafon) `." + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" +"Se via projekto enhavas tradukitan etendaĵon, vi kreos la tiel " +"nomatan :ref:`*Platforman Wheel* (vidu ĉi-suban paragrafon) `." + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" +"Se via projekto ankaŭ subtenas Python 2 *kaj* ne enhavas C-etendaĵon, vi " +"kreu *Universalan Wheel* aldonante la jenon al la dosiero :file:`setup.cfg`:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" +"Nur uzu tiun agordon, se via projekto ne havas iun ajn C-etendaĵon *kaj* " +"subtenas Python 2 kaj 3." + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "Pure Python-a Wheel" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" +"*Pure Python-a Wheel* enhavas neniu tradukitan etendaĵon kaj tial nur " +"postulas unu Python-wheel." + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "Por konstrui la wheel:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" +"La pako ``wheel`` detektos, ke la pako estas pure Python-a, kaj konstruos " +"wheel nomitan tiel, ke ĝi estos uzebla sur ajna instalo de Python 3. Por " +"pliaj detaloj pri la nomado de wheel-dosiero, vidu :pep:`425`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" +"Se oni rulos ``build`` sen ``--wheel`` aŭ ``--sdist``, ĝi konstruos ambaŭ " +"dosierojn; tio utilas, se vi ne bezonas plurajn wheel-ojn." + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "Platformaj Wheel-oj" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" +"*Platforma Wheel* estas wheel specifa al iu platformo kiel Linux, macOS aŭ " +"Windows, ordinare pro enhavo de tradukitaj etendaĵoj." + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" +"La pako ``wheel`` detektos, ke la kodo ne konsistas sole el Python, kaj " +"konstruos wheel nomitan tiel, ke ĝi estos nur uzebla sur la platformo, sur " +"kiu ĝi estis konstruita. Por detaloj pri la nomado de wheel-dosiero, " +"vidu :pep:`425`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" +":term:`PyPI ` aktuale subtenas alŝutadon de " +"platforma wheel por Windows, macOS, kaj la ABI ``manylinux*`` por pluraj " +"distribuoj. :pep:`513` difinas la detalojn pri ``manylinux*``." + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "Alŝuti Vian Projekton al PyPI" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" +"Kiam vi rulis la komandon por krei vian distribuon, kreiĝis nova dosierujo " +"``dist/`` sub la radika dosierujo de via projekto. Tie vi troviĝas la " +"alŝutota(j)n distribua(j)n dosiero(j)n." + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" +"Antaŭ ol eldoni al la ĉefdeponejo PyPI, vi eble volas ekzerci vin per la " +"`Prova PyPI `_, kiu fojfoje forviŝiĝas. " +"Vidu :ref:`using-test-pypi` pri la agordoj por uzi ĝin." + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" +"Aliaj dokumentoj kelkfoje mencias uzi ``python setup.py register`` kaj " +"``python setup.py upload``. Tiuj manieroj de registrado kaj alŝutado de pako " +"estas **malrekomendegata**, ĉar ili uzas neĉifritan HTTP-konekton aŭ " +"nekonfirmitan HTTPS-konekton sur kelkaj versioj de Python, permesante " +"ŝtelado de viaj salutnomo kaj pasvorto dum transsendado." + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" +"La sintaksanalizilo por restructuredText uzata ĉe PyPI **ne** estas Sphinx! " +"Krome, por sekureco de ĉiuj uzantoj, kelkaj retadresoj kaj direktivoj estas " +"malpermesataj aŭ forigitaj (ekzemple, la direktivo ``.. raw::``). **Antaŭ** " +"ol alŝuti la distribuon, oni kontrolu, ĉu la mallonga kaj longa priskriboj " +"en :file:`setup.py` validas. Oni faras tion rulante :std:doc:`twine check " +"` pri la pakaj dosieroj:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "Krei konton" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" +"Unue, necesas konto ĉe :term:`PyPI `. Vi povas " +"krei konton `per formularo ĉe la retejo de PyPI `_." + +#: ../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 "" +"Nun vi kreos `API-ĵetonon `_ por PyPI, tiel ke vi povos sekure " +"alŝuti vian projekton." + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" +"Iru al https://pypi.org/manage/account/#api-tokens kaj kreu novan `API-" +"ĵetonon `_; ne limigu ĝian rajton al iu projekto, ĉar vi estas " +"kreanta novan projekton." + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" +"**Ne fermu la paĝon, ĝis vi kopiis kaj konservis la ĵetonon – vi ne vidos " +"tiun ĵetonon denove.**" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" +"Se vi ne volas kopii kaj alglui la ĵetonon ĉiun fojon dum alŝutado, vi povas " +"krei dosieron :file:`$HOME/.pypirc`:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +msgstr "**Averto: tio senĉifre tenas vian ĵetonon.**" + +#: ../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 details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" +"Por pliaj detaloj, vidu la :ref:`specifon ` pri :file:`.pypirc`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "Alŝuti viajn distribuojn" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" +"Post kiam vi kreis vian konton, vi rajtas alŝuti viajn distribuojn " +"al :term:`PyPI ` per :ref:`twine`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" +"La procedo por alŝutado de eldono estas sama, ĉu aŭ ne la projekto jam " +"ekzistas ĉe PyPI. Se ĝi ankoraŭ ne ekzistas, ĝi estas aŭtomate kreota dum " +"alŝutado de la unua eldono." + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" +"Por la dua kaj sekvaj eldonoj, PyPI nur postulas, ke la versia numero de la " +"nova eldono diferencu de ajnaj antaŭaj versioj." + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" +"Oni povas kontroli, ĉu pako estis sukcese alŝutita, vizitante la retadreson " +"``https://pypi.org/project/``, en kiu ```` estas la nomo " +"de la alŝutita projekto. Eble oni devas atendi unu minuton aŭ du." + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" +"Depende de la platformo, tio eble postulas rajtojn de ĉefuzanto aŭ " +"Administranto. :ref:`pip` estas konsideranta ŝanĝi tion, `igante instalon " +"por uzanto la implicita konduto `_." + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "Malsubteni malnovajn versiojn de Python" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" +"La kapablo ekmalsubteni malnovajn versioj de Python estiĝis per la " +"atributo :ref:`«Requires-Python» ` en la " +"norma specifo :ref:`core-metadata` 1.2." + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" +"Instalilo subtenanta la normon Metadatenoj 1.2+ obeas tiun specifon " +"kontrolante, ĉu la aktuala Python-versio kongruas kun la postulata versio en " +"la pakaj metadatenoj. Se ĝi ne kongruos, ĝi provos instali la lastan pakan " +"distribuon subtenantan tiun Python-version." + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" +"Tiu meĥanismo povas esti uzata por ĉesigi subtenon por malnovaj versioj de " +"Python, modifante la atributon ``Requires-Python`` en la pakaj metadatenoj." + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "Postuloj" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" +"Tiu laborfluo postulas, ke la uzanto instalanta la pakon uzu Pip [#]_ aŭ " +"alian instalilon subtenantan la specifon Metadatenoj 1.2." + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "Pritrakti universalan wheel" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" +"Tradicie, projekto uzanta :ref:`setuptools`, kies Python-kodo semantike " +"kongruas kun kaj Python 2 kaj Python 3, havas :term:`wheel `, kies " +"nomo inkluzivas la sufikson ``py2.py3``. Kiam oni ĉesigas subtenon de Python " +"2, gravas ŝanĝi tiun etikedon al simple ``py3``. Tio estas ofte agordita " +"en :file:`setup.cfg` sub la sekcio ``[bdist_wheel]`` kiel ``universal=1``." + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" +"Se vi uzas tiun metodon, aŭ forigu tiun opcion aŭ sekcion, aŭ eksplicite " +"agordu ``universal`` kiel ``0``:" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" +"Pri :ref:`evitinda ` rekta alvoko de ``setup.py``, " +"uzado de la komandlinia flago ``--universal`` povas igi tiun agordon " +"ignorata." + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "Difini la postulatan version de Python" + +#: ../source/guides/dropping-older-python-versions.rst:48 +msgid "1. Install twine" +msgstr "1. Instalu twine" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "Certigu, ke vi havas la plej novan version de twine, jene:" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "2. Specifu la versian intervalon de subtenataj versioj de Python" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" +"Deklaru la gamon de versioj de Python subtenataj en la " +"dosiero :file:`pyproject.toml` de via projekto. La agorda " +"kampo :ref:`requires-python` respondas al la kerna metadatena " +"kampo :ref:`Requires-Python `:" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" +"Oni povas specifi intervalojn de versioj kaj ekskluzivotajn versiojn (laŭ la " +"normo :ref:`version-specifiers`), ekzemple «minimume Python 3.9» aŭ " +"«minimume Python 3.7, sed ne 3.7.0 nek 3.7.1»:" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" +"Se oni uzas la konstruan malfasadon :ref:`setuptools`, oni konsultu la " +"dokumentaron `dependency-management`_ por pliaj opcioj." + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" +"Evitu supran limon de versia gamo, ekz. ``\">= 3.8, < 3.10\"``. Tio povas " +"kaŭzi diversajn erarojn kaj versio-konfliktojn. Vidu `diskuton ĉe Discourse " +"`_ por pliaj informoj." + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "3. Kontrolu la validecon de la Metadatenoj antaŭ eldonado" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" +"En fonta pako de Python (la zip-arĥivo aŭ tar.gz-arĥivo elŝutita de vi) " +"troviĝas teksta dosiero nomita PKG-INFO." + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` 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 "" +"Tiu dosiero estas generita de la :term:`konstrua malfasado ` " +"dum generado de la fonta pako. La dosiero enhavas parojn de ŝlosiloj kaj " +"valoroj; la listo de ŝlosiloj estas parto de la norma metadatena formo de " +"PyPA." + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "Oni povas vidi la enhavon de la generita dosiero jene:" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" +"Konfirmu, ke la jenaj kondiĉoj estas plenumitaj, antaŭ ol eldoni la pakon:" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" +"Se vi ĝisdatigis ĝuste, la valoro de ``Metadata-Version`` estu 1.2 aŭ pli " +"alta." + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" +"La kampo ``Requires-Python`` ekzistu kaj kongruu kun via specifo en la " +"agorda dosiero." + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "4. Eldonu la pakon" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" +"Daŭrigu laŭ la paragrafo :ref:`Alŝuti Vian Projekton al PyPI `." + +#: ../source/guides/dropping-older-python-versions.rst:120 +msgid "Dropping a Python version" +msgstr "Malsubteni version de Python" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "Ĉiu versio-kongrueca ŝanĝo havu sian propran eldonon." + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "Subteno por la specifo Metadatenoj 1.2 estis aldonita al Pip 9.0." + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "Gastigi vian propran simplan deponejon" + +#: ../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 "" +"Se oni volas gastigi sian propran simplan deponejon [1]_, oni aŭ uzu " +"programon kiel :doc:`devpi `, aŭ oni povas simple kreu la " +"ĝustan dosierujan strukturon kaj uzu ajnan retservilon kapablan servi " +"statikajn dosierojn kaj generi aŭtomatan indekson." + +#: ../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:" +msgstr "" +"En ambaŭ kazoj, ĉar vi gastigas deponejon, kiu verŝajne ne estas inter la " +"aprioraj deponejoj de la uzanto, vi instruu la uzanton agordi sian " +"instalilon taŭge. Ekzemple, per 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." +msgstr "" +"Krome, ni **rekomendegas**, ke la deponejo uzu validan HTTPS. Nuntempe la " +"sekureco de la instaloj de la uzanto dependas de la valida HTTPS de ĉiuj " +"deponejoj." + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "«Malaŭtomata» deponejo" + +#: ../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 "" +"La dosieruja aranĝo estas simpla. En radika dosierujo, oni kreu po unu " +"dosierujo por ĉiu projekto. La dosierujo devas esti la :ref:`normigita nomo " +"` de la projekto. En ĉiu projekto, oni metu ĉiujn " +"elŝuteblajn dosierojn. Se oni havus la projektojn «Foo» (kun versioj 1.0 kaj " +"2.0) kaj «bar» (kun la versio 0.1), oni havus la jenan dosierujan " +"strukturon::" + +#: ../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 "" +"Kun tia aranĝo, simple igu vian TTT-servilon servi la radikan dosierujon kun " +"aŭtomata indekso. Ekzemple, uzante la aprioran TTT-servilon en `Twisted`_, " +"simple rulu ``twistd -n web --path .`` kaj igu la uzantojn aldoni la " +"retadreson al la agordoj de la instalilo." + +#: ../source/guides/hosting-your-own-index.rst:57 +#: ../source/guides/index-mirrors-and-caches.rst:47 +msgid "Existing projects" +msgstr "Ekzistantaj projektoj" + +#: ../source/guides/hosting-your-own-index.rst:63 +msgid "Package upload" +msgstr "Alŝuto de pako" + +#: ../source/guides/hosting-your-own-index.rst:64 +msgid "PyPI fall-through [2]_" +msgstr "Retroiro al 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 "Pliaj notoj" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" +"pluraj indeksoj kun heredado, kun sinkronigo, replikado, rezervosistemo; " +"spegulado" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr ":ref:`simpleindex`" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr ":ref:`pypiserver`" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr ":ref:`pypiprivate`" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr ":ref:`pypicloud`" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "nemastrumata; ankaŭ kaŝmemora perado; aŭtentikigo, rajtigo" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr ":ref:`pywharf`" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "nemastrumata; servi dosierojn ĉe GitHub" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr ":ref:`pulppython`" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "ankaŭ spegulado, perado; kromaĵo por Pulp" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr ":ref:`pip2pi`" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "ankaŭ spegulado; malaŭtomata sinkronigo" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr ":ref:`dumb-pypi`" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "ne servilo, sed statikdosiera retejogenerilo" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr ":ref:`httpserver`" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "standard-library" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "`Apache `_" + +#: ../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 "" +"uzante `mod_rewrite `_ kaj `mod_cache_disk `_, vi povas enkaŝmemirigi petojn al " +"pakindeksoj per Apache-servilo" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" +"Por plena dokumentaro pri la simpla deponeja protokolo, vidu :ref:`la " +"simplan deponejan API `." + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" +"Estas agordebla por uzi PyPI (aŭ alian pakindekson), se petita pako mankas." + +#: ../source/guides/index.rst:4 +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`." +msgstr "" +"**Gvidilo** temas pri plenumado de iu tasko kaj supozas, ke vi jam scias la " +"fundamentojn pri la pakado de Python. Se vi serĉas enkondukon al pakado, " +"vidu :doc:`/tutorials/index`." + +#: ../source/guides/index-mirrors-and-caches.rst:5 +msgid "Package index mirrors and caches" +msgstr "Pakindeksaj speguloj kaj kaŝmemoroj" + +#: ../source/guides/index-mirrors-and-caches.rst:8 +msgid "2023-11-08" +msgstr "8 Novembro 2023" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" +"Spegulado aŭ enkaŝmemorigo de PyPI (aŭ alia :term:`pakindekso `) povas rapidigi instaladon de loka pako, ebligi senkonektan " +"funkciadon, kongrui kun entreprena fajromuro aŭ maski malbonan Interretan " +"konekton." + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "Ekzistas pluraj klasoj de opcioj en tiu areo:" + +#: ../source/guides/index-mirrors-and-caches.rst:17 +msgid "local/hosted caching of package indexes." +msgstr "loka/gastigita kaŝmemoro de pakindeksoj." + +#: ../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 "" +"loka/gastigita spegulado de pakindekso. Spegulo estas (plena aŭ parta) kopio " +"de pakindekso uzebla anstataŭ la originalo." + +#: ../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 "" +"privata pakindekso kun retroiro al publikaj pakindeksoj (ekzemple por " +"malhelpi atakon per konfuzo de dependeco), ankaŭ konata kiel perilo." + +#: ../source/guides/index-mirrors-and-caches.rst:29 +msgid "Caching with pip" +msgstr "Kaŝmemoroj kaj pip" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" +"pip provizas servojn por rapidigi instaladon uzante loke memoritajn kopiojn " +"de :term:`pakoj `:" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" +":ref:`Rapida kaj loka instalado ` " +"elŝutante ĉiujn postulojn de projekto kaj montrante tiujn al pip anstataŭ " +"vizitadi PyPI." + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" +"Variaĵo de la ĉi-supro, kiu antaŭkonstruas la instalajn dosierojn por la " +"postuloj per :ref:`python3 -m pip wheel `:" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "Kaŝmemoro" + +#: ../source/guides/index-mirrors-and-caches.rst:54 +msgid "Mirror" +msgstr "Spegulo" + +#: ../source/guides/index-mirrors-and-caches.rst:55 +msgid "Proxy" +msgstr "Perilo" + +#: ../source/guides/index-mirrors-and-caches.rst:62 +msgid "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" +"pluraj indeksoj kun heredado, kun sinkronigo, replikado, rezervosistemo; " +"alŝutado de pakoj" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr ":ref:`bandersnatch`" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" +"propra kromprogramo ebligas kaŝmemoron; alidirektado al aliaj pakindeksoj" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "nemastrumata; aŭtentikigo, rajtigo" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "kromaĵo por Pulp; pluraj peritaj indeksoj; alŝuto de pako" + +#: ../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 "pluraj peritaj indeksoj" + +#: ../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 "nemastrumata" + +#: ../source/guides/installing-scientific-packages.rst:5 +msgid "Installing scientific packages" +msgstr "Instali sciencajn pakojn" + +#: ../source/guides/installing-scientific-packages.rst:8 +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." +msgstr "" +"Scienca programo ofte havas pli komplikajn dependecojn ol aliaj programoj, " +"kaj ofte havas plurajn konstruajn opciojn por diversaj aparatoj aŭ por " +"kunfunkcii kun diversaj eksteraj programoj." + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" +"Aparte, `NumPy `__, kiu estas la bazo de la plejparto " +"de la programaro en la `scienca Python-stako `_, povas kunfunkcii kun diversaj Fortranaj bibliotekoj kaj povas " +"ekspluati diversajn nivelojn de vektoraj instrukcioj en modernaj " +"ĉefprocesoroj." + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" +"Ekde versio 1.10.4 de NumPy kaj versio 1.0.0 de SciPy, antaŭkonstruitaj 32-" +"bitaj kaj 64-bitaj duumaĵoj de la formo ``wheel`` estas disponeblaj por ĉiuj " +"ĉefaj mastrumaj sistemoj (Windows, macOS kaj Linux) ĉe PyPI. Notu, tamen, ke " +"je Windows, duumaĵoj de NumPy estas binditaj al la biblioteko`ATLAS `__ por BLAS/LAPACK, kiu nur uzas la " +"instrukciojn SSE2 kaj tial povas esti neoptimuma pri lineara algebro." + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" +"Ekzistas kelkaj alternativoj por akiri sciencajn Python-bibliotekojn (aŭ " +"aliajn Python-bibliotekojn postulantajn tradukan medion por instali el fonto " +"kaj sen antaŭkonstruitajn wheel-dosierojn ĉe PyPI)." + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "Konstrui el fonto" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +msgstr "Linux-distribuaj pakoj" + +#: ../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 "" +"Por uzanto de Linux, la sistema pakadministrilo ofte havas antaŭtradukitajn " +"versiojn de diversaj sciencaj programoj inkluzive de NumPy kaj aliaj partoj " +"de la scienca Python-stako." + +#: ../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 "" +"Se uzi version plurmonate malaktualan estas akcepteble, do tio estas " +"verŝajne bona opcio (nur certigu, ke vi permesas atingon al distribuoj " +"instalitaj en la sistema Python dum uzado de virtuala medio)." + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "Windows-instaliloj" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" +"Multaj Python-projektoj, kiuj ne eldonas (aŭ ne povas eldoni) wheel-" +"dosierojn, minimume eldonas Windows-instalilojn, aŭ ĉe PyPI aŭ sur siaj " +"projektaj elŝutaj paĝoj. Uzante tian instalilon, uzanto ne bezonas starigi " +"taŭgan medion por konstrui etendaĵojn loke." + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" +"La etendaĵoj disponigitaj en tiuj instaliloj ofte kongruas kun la Windows-" +"instaliloj de CPython ĉe python.org." + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" +"Same kiel Linux-sistempakoj, la Windows instaliloj nur instalas en sisteman " +"Python-instalaĵon – ili ne povas instali en virtualan medion. Oni ofte " +"moderigas tiun limigon permesante al virtualaj medioj atingi distribuojn " +"instalitajn en la sisteman Python-instalaĵon." + +#: ../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 "" +"La projekto :term:`Wheel` ankaŭ provizas subkomandon :command:`wheel " +"convert`, kiu konvertas :command:`bdist_wininst`-instalilon por Windows al " +"wheel." + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +msgstr "Instaliloj kaj pakadministriloj por macOS" + +#: ../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 "" +"Simila al la situacio ĉe Windows, multaj projektoj (inkluzive de NumPy) " +"eldonas macOS-instalilojn kongruajn kun la CPython-duumaĵojn por macOS ĉe " +"python.org." + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" +"uzantoj de macOS ankaŭ povas uzi Linux-stilan pakadministrilon kiel " +"``Homebrew``. La retejo de SciPy havas pliajn detalojn pri `instalado de " +"SciPy sur macOS per Homebrew `_." + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "Distribuoj de SciPy" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" +"La retejo de SciPy listigas `plurajn distribuojn `_ provizantajn la plenan SciPy-stakon al uzanto en facile uzebla kaj " +"ĝisdatigebla formo." + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" +"Kelkaj el tiuj distribuoj eble ne kongruas kun la norma ilĉeno uzanta " +"``pip`` kaj ``virtualenv``." + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "Spack" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" +"`Spack `_ estas fleksebla pakadministrilo " +"subtenanta plurajn versiojn, agordojn, platformojn kaj tradukilojn. Ĝi estis " +"verkita por grandaj superkomputejoj kaj sciencaj teamoj, kiuj ofte devas " +"konstrui programojn plurmaniere. Spack ne estas limigita al Python; ĝi povas " +"instali pakojn por ``C``, ``C++``, Fortrano, ``R``, kaj aliajn lingvojn. Ĝi " +"estas nedetruema; instalado de nova versio de unu pako ne rompas " +"ekzistantajn instalojn; tial pluraj agordoj povas kunekzisti sur unu sistemo." + +#: ../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 provizas simplan sed potencan sintakson, kiu permesas al uzanto facile " +"specifi versiojn kaj agordajn opciojn. Pak-dosiero estas verkita en pura " +"Python kaj estas ŝablona tiel, ke per unu pakdosiero facilas ŝanĝi " +"tradukilon, realigon de dependaĵo (kiel MPI), versiojn kaj konstruaj " +"opciojn. Spack ankaŭ produktas *modul-dosierojn*, por ŝargi kaj malŝargi " +"pakojn al/el la medio de la uzanto." + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "La plurplatforma pakadministrilo conda" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" +"``conda`` estas malfermitfonta (BSD-licenca) pakadministra kaj " +"mediadministra sistemo, kiu permesas instali plurajn versiojn de duumaj " +"programaj pakoj kaj iliaj dependaĵoj kaj facile ŝanĝi inter ili. Ĝi estas " +"plurplatforma, sur Windows, macOS kaj Linux. Conda povas esti uzita por paki " +"kaj distribui ĉiajn pakojn; ĝi ne estas limigita al nur Python-pakoj. Ĝi " +"plene subtenas indiĝenajn virtualajn mediojn. Conda igas mediojn unuaklasaj " +"civitanoj, faciligante krei sendependajn mediojn eĉ por C-bibliotekoj. Ĝi " +"estas verkita en Python, sed ne estas nur por Python. Conda administras " +"Python mem kiel pakon, tiel ke :command:`conda update python` eblas, " +"kontraste al pip, kiu nur administras Python-pakojn." + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" +"`Anaconda `_ estas Python-distribuo " +"eldonita de la firmao Anaconda, Inc. Ĝi estas stabila kolekto de " +"Malfermitfontaj pakoj por grandaj datenoj kaj scienca uzado kune kun " +"grafikfasadaj ilaĵoj por administri ``conda``-medion." + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" +"Krom la plena distribuo provizita de Anaconda, la pakadministrilo ``conda`` " +"mem estas disponebla en `miniconda `_, `miniforge `_ kaj `pixi " +"`_." + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" +"Conda-pakoj disponeblas ĉe pluraj kanaloj en Anaconda.org, inkluzive de la " +"apriora kanalo de Anaconda, Inc.; la komunume subtenata kanalo ``conda-" +"forge``, kiu provizas multe da antaŭkonstruitaj pakoj; kaj fakaj " +"pakokolektoj." + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "Instali memstarajn komandliniajn ilojn" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" +"Multaj pakoj provizas komandliniajn aplikprogramojn. Jen kelkaj ekzemploj: " +"`mypy `_, `flake8 `_, `black `_ kaj :ref:`pipenv`." + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" +"Kutime oni volas atingi tiujn programojn de ie ajn sur la sistemo, sed " +"instalado de pakoj kaj dependaĵoj al la sama malloka medio povas kaŭzi " +"versio-konfliktojn kaj rompi Python-dependecojn de la mastruma sistemo." + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" +":ref:`pipx` solvas tiun problemon kreante virtualan medion por ĉiu pako, " +"certigante ke programoj estas atingeblaj per dosierujo en via ``$PATH``. Tio " +"permesas ĝisdatigadon aŭ malinstaladon de ĉiu pako sen konflikto kun aliaj " +"pakoj kaj sekuran ruladon ie ajn." + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "pipx nur funkcias kun Python 3.6+." + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "Oni instalas pipx per pip:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" +"``ensurepath`` certigas, ke la programa dosierujo estas en via ``$PATH``. Vi " +"eble bezonas relanĉi vian terminalon por efektivigi la ĝisdatigon." + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" +"Nun vi povas instali pakon per ``pipx install`` kaj ruli la programojn de la " +"pako ie ajn." + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "Ekzemple:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" +"Por vidi liston de pakoj instalitaj per pipx kaj liston de haveblaj " +"programoj, uzu ``pipx list``:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "Por ĝisdatigi aŭ malinstali pakon:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "pipx estas ĝisdatigebla kaj malinstalebla per pip:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" +"pipx ankaŭ permesas al vi instali kaj ruli la plej novan version de programo " +"en provizora, efemera medio. Ekzemple:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "Por vidi la plenan liston de komandoj de pipx, rulu la jenon:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "Lernu pli pri pipx ĉe https://pipx.pypa.io/." + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "Instali pip/setuptools/wheel per Linux-pakadministrilojn" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "26 Julio 2021" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" +"Jen paragrafo pri kiel instali :ref:`pip`, :ref:`setuptools`, " +"kaj :ref:`wheel` per Linux-pakadministriloj." + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" +"Se vi uzas Python elŝutitan el `python.org `_, ĉi " +"tiu paragrafo ne rilatas. Anstataŭe vidu la " +"paragrafon :ref:`installing_requirements`." + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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 "" +"Ankaŭ notu, ke Distribuoj ofte flikas por sekureco kaj konformeco al siaj " +"normoj. Kelkfoje, tio povas kaŭzi cimojn aŭ neatenditajn kondutojn " +"diferencajn de originalaj neflikitaj versioj. Kiam tio estas konata, ni " +"rimarkos tion ĉi-sube." + +#: ../source/guides/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "Fedora" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" +"Por lerni pli pri Python en Fedora, bonvolu legi `la oficialan dokumentaron " +"de Fedora `_, `Python Classroom`_ aŭ `Fedora Loves " +"Python`_." + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "CentOS/RHEL" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" +"CentOS kaj RHEL ne ofertas :ref:`pip` nek :ref:`wheel` en siaj ĉefdeponejoj, " +"kvankam :ref:`setuptools` estas apriore instalita." + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "Por instali pip kaj wheel por la sistema Python, ekzistas du opcioj:" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" +"Ŝaltu la `deponejon EPEL `_ laŭ `la " +"jenaj instrukcioj `__. Sur EPEL 7, vi povas instali pip kaj wheel jene:" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" +"EPEL nur ofertas ekstrajn, senkonfliktajn pakojn. Tial EPEL ne ofertas " +"setuptools, ĉar ĝi estas en la ĉefdeponejo." + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" +"Ŝaltu la `Copr-deponejon de PyPA `_ laŭ `tiuj instrukcioj `__ [1]_. Vi povas instali pip kaj " +"wheel jene:" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "Por ankaŭ ĝisdatigi setuptools, rulu la jenon:" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" +"Por instali pip, wheel kaj setuptools en paralela, nesistema medio (uzante " +"yum), ekzistas du opcioj:" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" +"Uzu la funkcion «Software Collections» por ŝalti paralelan kolekton " +"inkluzivantan pip, setuptools kaj wheel." + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" +"Por Red Hat, vidu la jenon: https://developers.redhat.com/products/" +"softwarecollections/overview" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "Por CentOS, vidu la jenon: 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 "Konsciu, ke kolektoj eble ne havas la plej novajn versiojn." + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" +"Ŝaltu la `deponejon IUS `_, kaj instalu unu el la " +"`paralele instaleblaj `_ " +"Python-oj kune kun pip, setuptools, kaj wheel, kiuj estas plejparte ĝisdataj." + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "Ekzemple, por Python 3.4 sur CentOS 7 / RHEL 7:" + +#: ../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 kaj idoj" + +#: ../source/guides/installing-using-linux-tools.rst:120 +msgid "Firstly, update and refresh repository lists by running this command:" +msgstr "Unue, ĝisdatigu la liston de deponejoj per la jena komando:" + +#: ../source/guides/installing-using-linux-tools.rst:129 +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." +msgstr "" +"Novaj versioj de Debian/Ubuntu modifis pip apriore uzante la `«Uzanto-" +"Skemon» `_, kio " +"estas signifa konduta ŝanĝo eble surprizanta kelkajn uzantojn." + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "Arch Linux" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" +"Aktuale ne ekzistas ``yum``-kromprogramo por ``copr`` havebla ĉe CentOS/" +"RHEL. Tial, oni devas malaŭtomate enmetu deponejajn dosierojn laŭ la ĉi-" +"supra maniero." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +msgid "Install packages in a virtual environment using pip and venv" +msgstr "Instali pakojn en virtuala medio per pip kaj venv" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" +"Ĉi tiu estas gvidilo pri kiel krei kaj aktivigi virtualan medion per la " +"ilo :ref:`venv` en la norma biblioteko kaj instali pakojn tien. La gvidilo " +"diskutas la jenon:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:8 +msgid "Create and activate a virtual environment" +msgstr "Krei kaj aktivigi virtualan medion" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:9 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:153 +msgid "Prepare pip" +msgstr "Prepari pip" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "Instali pakojn en virtualan medion per la komando ``pip``" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "Uzi kaj krei postulo-dosieron" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" +"Ĉi tiu gvidilo validas pri subtenataj versioj de Python, aktuale 3.8 kaj pli " +"novaj." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" +"Ĉi tiu gvidilo uzas la terminon **pako** por signifi :term:`Distribuan Pakon " +"`, instalitan el ekstera gastiganto. Tio diferencas de " +"la termino :term:`Importa Pako `, kiu estas importebla " +"modulo en Python-fontokodo." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" +"Ĉi tiu gvidilo supozas, ke vi uzas oficialan version de Python el . Se vi uzas la pakadministrilon de via mastruma " +"sistemo por instali Python, bonvolu certigi, ke Python estas instalita, " +"antaŭ ol sekvi la ĉi-subajn paŝojn." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:32 +msgid "Create and Use Virtual Environments" +msgstr "Krei kaj Uzi Virtualajn Mediojn" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:35 +msgid "Create a new virtual environment" +msgstr "Krei novan virtualan medion" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:37 +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." +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 "" +"Estas rekomendate uzi virtualan medion dum laborado kun triapartiaj pakoj." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" +"Por krei virtualan medion, iru al la dosierujo de via projekto, kaj rulu la " +"jenan komandon. Tio kreos novan virtualan medion en loka dosierujo nomita " +"``.venv``:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" +"La dua argumento estas la loko de la virtuala medio. Ĝenerale, oni povas " +"simpli krei ĝin en sia projekto kaj nomi ĝin ``.venv``." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "``venv`` kreos virtualan Python-instalon en la dosierujo ``.venv``." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" +"Vi ekskluzivu vian virtualmedian dosierujon el via versikontrola sistemo per " +"``.gitignore`` aŭ io simila." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "Aktivigi virtualan medion" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" +"Antaŭ ol oni povas ekinstali aŭ ekuzi pakojn en sia virtuala medio, oni " +"devas «aktivigi» ĝin. Aktivigado de virtuala medio metos ruleblaĵojn " +"``python`` kaj ``pip`` por la virtuala medio en la medivariablon ``PATH`` de " +"la ŝelo." + +#: ../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 "" +"Por konfirmi, ke la virtuala medio estas aktiva, kontrolu la lokon de via " +"Python-interpretilo:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" +"Dum la virtuala medio aktivas, la ĉi-supra komando eligos dosierindikon " +"inkluzivan la dosierujon ``.venv``, finiĝante jene:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" +"Kiam virtuala medio estas aktiva, pip instalas pakojn en tiun medion. Tio " +"permesas importi kaj uzi pakojn en sia Python-programo." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "Malaktivigi virtualan medion" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" +"Se vi volas ŝanĝi projektojn aŭ lasi vian virtualan medion, ``malaktivigu`` " +"la medion:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" +"Fermado de la ŝelo malaktivigos la virtualan medion. Se vi malfermas novan " +"ŝelan fenestron kaj volas uzi la virtualan medion, reaktivigu ĝin." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "Reaktivigi virtualan medion" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" +"Se vi volas reaktivigi ekzistantan virtualan medion, sekvu la samajn " +"instrukciojn pri aktivigado de virtuala medio. Ne necesas krei novan " +"virtualan medion." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" +":ref:`pip` estas la referenca Python-pakadministrilo. Oni uzas ĝin por " +"instali kaj ĝisdatigi pakojn en virtualan medion." + +#: ../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 "" +"La Python-instalilo por macOS inkluzivas pip. Sur Linux, oni eble devas " +"instali plian pakon kiel ``python3-pip``. Oni certigas la ĝisdatigitecon de " +"pip rulante la jenon:" + +#: ../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 "" +"Poste, vi estos instalinta la plej novan version de pip en vian lokon de " +"uzanto:" + +#: ../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 "" +"La Python-instaliloj por Windows inkluzivas pip. Vi povas certigi ke pip " +"estas ĝisdata rulante la jenon:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "Poste, vi havos la plej novan version de pip:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +msgid "Install packages using pip" +msgstr "Instali pakojn per pip" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" +"Kiam via virtuala medio estas aktivigita, vi povas instali pakojn. Uzu la " +"komandon ``pip install`` por instali pakojn." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "Instali pakon" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +#, fuzzy +#| msgid "" +#| "For example,let's install the `Requests`_ library from the :term:`Python " +#| "Package Index (PyPI)`:" +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" +"Ekzemple, ni instalos la biblioteko `Requests`_ el la :term:`Python-" +"Pakindico (PyPI) `:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "pip elŝutos requests kaj ĝiajn dependaĵojn kaj instalos ilin:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "Instali specifan version de pako" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" +"pip permesas al vi precizigi la instalotan version de pako per :term:`versio-" +"specifilo `. Ekzemple, por instali specifan version de " +"``requests``:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "Por instali la plej novan version ``2.x`` de requests:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "Por instali antaŭeldonan version de pako, uzu la flagon ``--pre``:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +msgid "Install extras" +msgstr "Instali ekstraĵojn" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" +"Kelkaj pakoj havas nedevigajn `ekstraĵojn `_. Vi povas igi pip " +"instali tiun specifante la ekstraĵon en rektaj krampoj:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "Instali pakon el fonto" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" +"pip povas instali pakon rekte de la fontkodo. Ekzemple, por instali la " +"fontkodon en la dosierujo ``google-auth``:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +msgid "" +"Additionally, pip can install packages from source in :doc:`development mode " +"`, meaning that changes to the source " +"directory will immediately affect the installed package without needing to " +"re-install:" +msgstr "" +"Krome, pip povas instali pakojn el fonto en :doc:`evoluada reĝimo " +"`, tiel ke ŝanĝoj pri la fonta " +"dosierujo tuje efektiviĝas por la instalita pako sen la bezono reinstali:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:347 +msgid "Install from version control systems" +msgstr "Instali el versikontrola sistemo" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:349 +msgid "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" +"pip povas instali pakon rekte el versikontrola sistemo. Ekzemple, vi povas " +"instali rekte el git-deponejo:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" +"Por pli da informoj pri subtenataj versikontrolaj sistemoj kaj sintakso, " +"vidu la dokumentaron de pip pri :ref:`Subtenado de Versikontrola Sistemo " +"`." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "Instali el loka arĥivo" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" +"Se oni havas lokan kopion de la arĥivo de :term:`Distribua Pako " +"` (zip-arĥivo, wheel, aŭ tar-arĥivo), oni povas " +"instali ĝin rekte per pip:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" +"Se vi havas dosierujon enhavantan arĥivojn de pluraj pakoj, oni povas igi " +"pip serĉi pakojn tie kaj ne uzi la :term:`Python-Pakindekson `:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" +"Tio utilas, se oni instalas pakon sur sistemo de limigita konektiteco aŭ se " +"oni volas strikte kontroli la originon de distribuaj pakoj." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "Instali el aliaj pakindeksoj" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" +"Por elŝuti el indekso alia ol :term:`PyPI `, " +"uzu la flagon ``--index-url``:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" +"Se vi volas permesi pakojn el kaj :term:`PyPI ` " +"kaj aparta indekso, vi povas anstataŭe uzi la flagon ``--extra-index-url``:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "Ĝisdatigi pakojn" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" +"pip povas ĝisdatigi pakon en loko uzante la flagon ``--upgrade``. Ekzemple, " +"por instali la plej novan version de ``requests`` kaj ĉiuj ĝiaj dependaĵoj:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "Usi postulo-dosieron" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" +"Anstataŭ instalado de pakoj unuope, pip ebligas deklaradon de ĉiuj " +"dependecoj en :ref:`Postulo-Dosiero `. Ekzemple oni " +"povas krei :file:`requirements.txt` enhavantan la jenon:" + +#: ../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 "" +"Kaj igi pip instali ĉiujn pakojn en ĉi tiu dosiero per la flago ``-r``:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +msgstr "Frostigi dependecojn" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:480 +msgid "" +"Pip can export a list of all installed packages and their versions using the " +"``freeze`` command:" +msgstr "" +"Pip povas eksporti liston de ĉiuj instalitaj pakoj kaj iliaj versioj per la " +"komando ``freeze``:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 +msgid "Which will output a list of package specifiers such as:" +msgstr "Tio eligos liston de pako-specifiloj jene:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" +"La komando ``pip freeze`` utilas por krei :ref:`Postulo-Dosieron " +"` kiu povas rekrei la ekzaktajn versiojn de ĉiuj " +"pakoj instalitaj en iu medio." + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "Instali pakojn per virtualenv" + +#: ../source/guides/installing-using-virtualenv.rst:4 +msgid "" +"This guide discusses how to install packages using :ref:`pip` " +"and :ref:`virtualenv`, a tool to create isolated Python environments." +msgstr "" +"Jen gvidilo pri kiel instali pakojn per :ref:`pip` kaj :ref:`virtualenv`, " +"kiu estas ilo por krei izolitajn Python-mediojn." + +#: ../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 "" +"Ĉi tiu gvidilo pri instalado de pakoj kaj uzado de :ref:`virtualenv` estas " +"ankoraŭ verkata. Bonvolu vidi la dokumentaro de :ref:`virtualenv` por " +"detaloj pri instalado kaj uzado." + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" +"Ĉi tiu dokumento uzas la terminon **pako** por signifi :term:`Distribuan " +"Pakon `, kiu diferencas de :term:`Importa Pako ` uzata por importi modulon al via Python-fontkodo." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "Ekzemploj de licencoj kaj uzkazoj" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +#, fuzzy +#| msgid "" +#| ":pep:`639` has specified the way to declare a project's license and paths " +#| "to license files and other legally required information. This document " +#| "aims to provide clear guidance how to migrate from the legacy to the " +#| "standardized way of declaring licenses. Make sure your preferred build " +#| "backend supports :pep:`639` before trying to apply the newer guidelines." +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" +":pep:`639` precizigis la manieron deklari la licencon de projekto kaj " +"dosierlokojn de licencodosieroj kaj aliajn leĝe postulataj informoj. Ĉi tiu " +"dokumento celas klarigi, kiel migri de la malnova maniero al la normigita " +"maniero deklari licencojn. Certigu, ke via preferata konstrua malfasado " +"subtenas :pep:`639`, antaŭ ol provi la novajn gvidnormojn." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "Ekzemploj de Licencoj" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "Baza ekzemplo" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" +"La projekto Setuptools mem, je `versio 75.6.0 `__, ne uzas " +"la kampon ``License`` en siaj propraj projektaj fontaj metadatenoj. Ĝi ankaŭ " +"ne plu eksplicas ``license_file``/``license_files`` malkiel antaŭe, ĉar ĝi " +"uzas sian propran aŭtomatan inkluzivon de licenco-rilataj dosieroj, kies " +"dosiernomoj estas kutimaj, ekzemple :file:`LICENSE`." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" +"Ĝi inkluzivas la jenajn licencajn metadatenojn en :file:`pyproject.toml`:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "La plej simpla migrado al PEP 639 uzos jenon anstataŭe:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" +"Aŭ, se la projekto uzis :file:`setup.cfg` en sia tabelo ``[metadata]``:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +#, fuzzy +#| msgid "" +#| "The output Core Metadata for the distribution packages would then be:" +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "La eligitaj Kernaj Metdatenoj por la distribuaj pakoj estos jenaj:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" +"La dosiero :file:`LICENSE` troviĝus en :file:`/setuptools-{VERSIO}/LICENSE` " +"en la fonta distribuo kaj :file:`/setuptools-{VERSIO}.dist-info/licenses/" +"LICENSE` en la wheel, kaj malpakiĝus de tie al la dosierujo de la instalaĵo " +"(ekz. :file:`site-packages/`) dum instalado; :file:`/` estas la radiko de la " +"arĥivo, kaj ``{VERSIO}`` la versio de la eldono de Setuptools laŭ Kernaj " +"Metadatenoj." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "Altnivela ekzemplo" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" +"Supozu, ke Setuptools inkluzivus la licencojn de la triapartiaj projektoj en " +"la dosierujoj :file:`setuptools/_vendor/` kaj :file:`pkg_resources/_vendor/" +"`; specife:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +#, fuzzy +#| msgid "Examples of invalid license expressions:" +msgid "The appropriate license expressions are:" +msgstr "Ekzemploj de nevalidaj licenco-esprimoj:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" +"Ampleksa licenco-esprimo pri kaj Setuptools mem kaj la inkluzivitaj " +"dependaĵoj enhavus tiujn metadatenojn, kombinante ĉiujn licenco-esprimojn. " +"Tia esprimo povas esti jena:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" +"Specife, ni supozas, ke la licenco-dosieroj troviĝas en la jenaj lokoj en la " +"projekta fontarbo (relative al la projekta radiko " +"kaj :file:`pyproject.toml`):" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "Resume, la dosiero :file:`pyproject.toml` estos jena:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" +"Alternative, la licenco-dosiero povas esti specifita eksplicite (dosierloko " +"interpretiĝas kiel patroneo):" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "Se nia projekto uzus :file:`setup.cfg`, ni povus difini tion en:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" +"Per ambaŭ metodoj, la eligitaj Kernaj Metadatenoj en la distribuo estos " +"jenaj:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" +"En la rezulta fonta distribuo, kun :file:`/` kiel la radiko de la arĥivo kaj " +"``{VERSION}`` la versio de la eldono de Setuptools specifita en la Kernaj " +"Metadatenoj, la licenco-dosieroj troviĝus ĉe:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" +"En la konstruita wheel, kun :file:`/` kiel la radiko de la arĥivo kaj " +"``{VERSION}`` sama kiel la ĉi-supra ekzemplo, la licenco-dosieroj troviĝus " +"ĉe:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" +"Fine, en la instalita projekto en :file:`site-packages/`, kun ``{VERSION}`` " +"sama kiel la ĉi-supra ekzemplo, la licenco-dosieroj instaliĝus al:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "Ekzemploj de esprimoj" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "Kelkaj pliaj ekzemploj de validaj valoroj de ``License-Expression``:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "Uzkazoj" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "Mi havas ne distribuotan privatan pakon" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" +"Se via pako ne estas havebla publike (ekster via firmao, organizaĵo aŭ " +"familio), *ordinare* ne necesas inkluzivi formalan licencon, tiel ke vi ne " +"devas fari ion ekstre." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "Mi simple volas disdoni mian verkon sen jura restrikto" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" +"Kvankam oni ne devas inkluzivi licencon, se licenco mankus, neniu rajtas " +"`elŝuti, uzi aŭ plibonigi vian verkon `__, kio estas " +"verŝajne la malo de tio, kio vi deziras. La `licenco MIT " +"`__ estas bona elekto, ĉar ĝi estas simpla, vaste uzata " +"kaj permesas al ĉiuj fari ion ajn deziratan pri via laboro (krom procesi " +"kontraŭ vi, kion vi verŝajne ankaŭ ne deziras)." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" +"Por efektivigi ĝin, simple algluu `la tekston `__ en " +"dosieron nomitan :file:`LICENSE.txt` ĉe la radiko de via deponejo, kaj " +"aldonu la jaron kaj vian nomon al la kopirajta linio. Poste, simple aldonu " +"``license = \"MIT\"`` sub ``[project]`` en :file:`pyproject.toml` se via " +"pakilo subtenas ĝin, aŭ en ĝia agorda dosiero. Jen finite!" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "Mi volas distribui mian projekton sub specifa licenco" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" +"Por uzi iu licencon, simple metu la licencan tekston " +"endosieron :file:`LICENSE.txt` ĉe la radiko de la deponejo (se ankoraŭ " +"mankas dosiero, kies nomo komenciĝas per :file:`LICENSE` " +"aŭ :file:`COPYING`), kaj aldonu ``license = \"LICENCA-IDENTIGILO\"`` sub " +"``[project]`` en :file:`pyproject.toml` (se la pakilo subtenas ĝin) aŭ en " +"alia agorda dosiero. La ``LICENCA-IDENTIGILO`` kaj kopiebla licenca teksto " +"troviĝas en retejoj kiel `ChooseALicense `__ aŭ `SPDX " +"`__." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" +"Multaj popularaj kodgastigejoj, projekto-ŝablonoj kaj pakiloj povas aldoni " +"la licenco-dosieron por vi kaj povos subteni la esprimon." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "Mi mastrumas ekzistantan pakon sub licenco" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" +"Se vi jam havas licencajn dosierojn kaj metadatenojn en via projekto, vi nur " +"devas fari kelkajn ŝanĝetojn por uzi la novajn funkciojn." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +#, fuzzy +#| msgid "" +#| "In your project config file, enter your license expression under " +#| "``license`` (``[project]`` table in :file:`pyproject.toml`), or the " +#| "equivalent for your packaging tool, and make sure to remove any legacy " +#| "``license`` table subkeys or ``License ::`` classifiers. Your existing " +#| "``license`` value may already be valid as one (e.g. ``MIT``, ``Apache-2.0 " +#| "OR BSD-2-Clause``, etc); otherwise, check the `SPDX license list " +#| "`__ for the identifier that matches the license used in your " +#| "project." +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" +"En via projekta agorda dosiero, tajpu vian licenco-esprimon sub ``license`` " +"(tabelo ``[project]`` en :file:`pyproject.toml`), aŭ la ekvivalentaĵon de " +"via pakilo. Certigu, ke vi forigis ajnan malnovan subŝlosilojn de tabelo " +"``license`` aŭ klasigilojn ``License ::``. Via ekzistanta valoro por " +"``license`` povas jam validi (ekz. ``MIT``, ``Apache-2.0 OR BSD-2-Clause`` " +"ktp); alie, vidu la `liston de SPDX-licencoj `__ por la " +"identigilo por la licenco de via projekto." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" +"Certe listigu viajn licenco-dosierojn sub ``license-files`` sub " +"``[project]`` en :file:`pyproject.toml` aŭ en la agorda dosiero de via ilo." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "Mia pako inkluzivas alian kodon sub malsamaj licencoj" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +#, fuzzy +#| msgid "" +#| "In short, ``License-1 AND License-2`` mean that *both* licenses apply to " +#| "your project, or parts of it (for example, you included a file under " +#| "another license), and ``License-1 OR License-2`` means that *either* of " +#| "the licenses can be used, at the user's option (for example, you want to " +#| "allow users a choice of multiple licenses). You can use parenthesis " +#| "(``()``) for grouping to form expressions that cover even the most " +#| "complex situations." +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" +"Resume, ``Licenco-1 AND Licenco-2`` signifas, ke *ambaŭ* licencoj efektivas " +"pri la projekto aŭ partoj de la projekto (ekzemple, la aŭtoro inkluzivis " +"dosieron sub alia licenco), kaj ``Licenco-1 OR Licenco-2`` signifas, ke *aŭ " +"unu aŭ la alia* el la licencoj estas uzeblaj laŭ la volo de la uzanto " +"(ekzemple, la aŭtoro volas permesi al la aŭtoro elekti inter pluraj " +"licencoj). Oni uzas rondajn krampojn (``()``) por grupigi esprimojn, " +"sufiĉante por eĉ la plej komplikaj situacioj." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" +"En via projekta agorda dosiero, tajpu vian licenco-esprimon sub ``license`` " +"(tabelo ``[project]`` en :file:`pyproject.toml`), aŭ la ekvivalentaĵon de " +"via pakilo. Certigu, ke vi forigis ajnan malnovan subŝlosilojn de tabelo " +"``license`` aŭ klasigilojn ``License ::``." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" +"Ekzemple, se via projekto estus sub la licenco MIT sed inkluzivus dependaĵon " +"(ekzemple ``packaging``) sub aŭ Apache 2.0 aŭ la dukondiĉa BSD, la licenco-" +"esprimo estus ``MIT AND (Apache-2.0 OR BSD-2-Clause)``. Oni " +"havus :file:`LICENSE.txt` en la deponeja radiko, kaj :file:`LICENSE-" +"APACHE.txt` kaj :file:`LICENSE-BSD.txt` en la subdosierujo :file:`_vendor/`. " +"Por inkluzivi ĉiujn, oni specifus aŭ la patroneon ``[\"LICENSE.txt\", " +"\"_vendor/packaging/LICENSE*\"]`` aŭ la dosierlokojn ``[\"LICENSE.txt\", " +"\"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-BSD.txt\"]``." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" +"Vidu :ref:`licensing-example-advanced` por plena ekzemplo de tio pri realeca " +"komplika projekto,, kun multaj teĥnikaj detaloj. Vidu `lernilon " +"`__ por pli da helpo kaj ekzemploj pri SPDX-identigiloj kaj " +"esprimoj." + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "Verki README-dosieron uzeblan por PyPI" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" +"README-dosiero helpas uzantojn kompreni vian projekton kaj provizas " +"priskribon pri via projekto ĉe PyPI. Ĉi tiu gvidilo helpas vin verki README " +"en PyPI-kongrua formo kaj inkluzivi la README en la pakon por montri ĝin ĉe " +"PyPI." + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "Krei README-dosieron" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" +"La README-dosieroj por Python-projektoj ofte nomiĝas ``README``, " +"``README.txt``, ``README.rst``, aŭ ``README.md``." + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" +"Por bona montrado de via README, elektu marklingvon subtenatan de PyPI. Jen " +"la dosierformoj subtenataj de `la README-montrilo de PyPI `:" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "ordinara teksto" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" +"`reStructuredText `_ (sen " +"etendaĵoj Sphinx)" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" +"Markdown (`GitHub-Stila Markdown `_ " +"implicite, aŭ `CommonMark `_)" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" +"Estas kutime meti la README-dosieron en la radiko de la projekto, en la sama " +"dosierujo kiel la dosiero :file:`setup.py`." + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "Inkluzivi vian README-dosieron en la metadatenojn de via pako" + +#: ../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 "" +"Por inkluzivi la enhavon de README kiel la priskribon de la pako, agordu la " +"metadatenojn ``Description`` kaj ``Description-Content-Type``, ofte en la " +"dosiero :file:`setup.py` de via projekto." + +#: ../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/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" +"Ekzemple, por agordi tiujn valorojn en la dosiero :file:`setup.py` de pako, " +"uzu la argumentojn ``long_description`` kaj " +"``long_description_content_type`` de ``setup()``." + +#: ../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``." +msgstr "" +"Agordu la valoron de ``long_description`` al la enhavo (ne la dosierloko) de " +"la dosiero README. Agordu ``long_description_content_type`` al akceptata " +"``Content-Type``-stila valoro por la marklingvo de via dosiero README, " +"ekzemple ``text/plain``, ``text/x-rst`` (por reStructuredText), aŭ ``text/" +"markdown``." + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" +"Se vi uzas GitHub-stilan Markdown por priskribi projekton, certigu, ke vi " +"ĝisdatigis la jenajn ilojn:" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "Jen la minimumaj postulataj versioj de tiuj iloj:" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" +"Ni rekomendas, ke vi uzu ``twine`` por alŝuti la distribuajn pakojn de via " +"projekto:" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" +"Jen ekzempla dosiero :file:`setup.py` leganta :file:`README.md` kiel " +"``long_description`` kaj identiganta la marklingvon kiel GitHub-stilan " +"Markdown:" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "Kontroli la validecon de reStructuredText" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" +"Se via README estas en reStructuredText, ajna nevalida marklingvaĵo " +"malhelpos montradon, kaŭzante la montradon de la kruda fonto ĉe PyPI." + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" +"Notu, la Sphinx-etendaĵoj uzataj en docstring, kiel :doc:`direktivoj " +"` kaj :doc:`roloj ` (ekzemple «``:py:func:`getattr```» aŭ «``:ref:`mia-" +"referenca-etikedo```») ne estas permesata ĉi tie kaj kaŭzos erarmesaĝojn " +"kiel «``Error: Unknown interpreted text role \"py:func\".``»." + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" +"Vi povas kontroli vian README pri marklingvaj erarojn antaŭ alŝutado jene:" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +msgstr "" +"Instalu la plej novan version de `twine `_; " +"versio 1.12.0 aŭ pli nova estas bezonata:" + +#: ../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 "" +"Konstruu la fontan distribuon kaj la wheel por via projekto laŭ :ref:`Paki " +"Vian Projekton `." + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "Rulu ``twine check`` pri la fonta distribuo kaj la wheel:" + +#: ../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 "" +"Ĉi tiu komando raportis ajnan problemon pri montrado de via README. Se ĉio " +"estas senproblema, la komando eligos ``Checking distribution DOSIERNOMO: " +"Passed``." + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "Migri al 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 "Evitinda" + +#: ../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` estas la nova, reverkita versio de PyPI anstataŭinta la " +"malnovan kodon de PyPI. Ĝi estas la apriora versio de PyPI, kiun ĉiuj uzu. " +"Jen la iloj kaj procedoj por interagi kun ``PyPI.org``." + +#: ../source/guides/migrating-to-pypi-org.rst:16 +msgid "Publishing releases" +msgstr "Publikigi eldonojn" + +#: ../source/guides/migrating-to-pypi-org.rst:18 +msgid "``pypi.org`` is the default upload platform as of September 2016." +msgstr "``pypi.org`` estas la implicita alŝuta platformo en Septembro 2016." + +#: ../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 "" +"Alŝutoj per ``pypi.python.org` *ne plu eblas* ekde **3 Julio 2017**. Je 13 " +"Aprilo 2018, ``pypi.org`` estas la retadreso por PyPI." + +#: ../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 "" +"La rekomendata maniero migri al PyPI.org por alŝutado estas certigi, ke vi " +"uzas sufiĉe novan version de via alŝutilo." + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "La implicita alŝuta celo ŝanĝiĝis al ``pypi.org`` en la jenaj versioj:" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "Python 2.7.13 (ĝisdatigo de ``distutils``)" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "Python 3.4.6 (ĝisdatigo de ``distutils``)" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "Python 3.5.3 (ĝisdatigo de ``distutils``)" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "Python 3.6.0 (ĝisdatigo de ``distutils``)" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" +"Poste simple forigu la linion komenciĝanta per ``repository``, kaj vi uzos " +"la aprioran retadreson de via alŝutilo." + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +msgstr "" +"Se ial vi ne povas ĝisdatigi ilon al versio, kiu apriore uzas PyPI.org, do " +"vi modifu :file:`$HOME/.pypirc` kaj inkluzivu la linion ``repository:``, sed " +"anstataŭe uzu la valoron ``https://upload.pypi.org/legacy/``:" + +#: ../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 "" +"(``legacy`` en ĉi tiu retadreso signifas, ke tio estas la imitado, far la " +"nova servila realigo, de la alŝuta API de la malnova servila realigo.)" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "Registri pakajn nomojn kaj metadatenojn" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" +"Eksplicita antaŭregistrado de paknomo per la komando ``setup.py register`` " +"antaŭ la unua alŝuto ne plu necesas kaj aktuale ne estas subtenata de la " +"imitado de la malnova alŝuta API ĉe PyPI.org." + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" +"Tial, provado registri eksplicite post ŝanĝado al PyPI. org por alŝutado " +"kaŭzos la jenan eraron::" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "La solvo estas transsalti la registradon kaj rekte alŝuti artefaktojn." + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "Uzi TestPyPI" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" +"La malonva Prova PyPI (testpypi.python.org) ne plu haveblas; uzu " +"`test.pypi.org `_ anstataŭe. Se vi uzas la Provan " +"PyPI, vi devas ĝisdatigi la :file:`$HOME/.pypirc` por la nova loko de Prova " +"PyPI, anstataŭigante ``https://testpypi.python.org/pypi`` per ``https://" +"test.pypi.org/legacy/``, jene:" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "Registri novajn uzantokontojn" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" +"Por malpliigi atakojn kontraŭ PyPI, registrado de nova uzanto per " +"``pypi.python.org`` *malebliĝis* je *20a de Februaro 2018*. Eblas registrado " +"de nova uzanto ĉe ``pypi.org``." + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "Foliumi pakojn" + +#: ../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." +msgstr "" +"Kvankam hiperligoj en alia dokumentoj de PyPA povas ankoraŭ uzi " +"``pypi.python.org'', la apriora fasado por foliumi pakojn estas " +"``pypi.org``. La retejo ``pypi.python.org`` nun estas redirektata al " +"``pypi.org``, kaj povas ekmalesti estontece." + +#: ../source/guides/migrating-to-pypi-org.rst:134 +msgid "Downloading packages" +msgstr "Elŝuti pakojn" + +#: ../source/guides/migrating-to-pypi-org.rst:136 +msgid "``pypi.org`` is the default host for downloading packages." +msgstr "``pypi.org`` estas la implicita servilo por elŝuti pakojn." + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "Administri eldonitajn pakojn kaj eldonojn" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" +"``pypi.org`` provizas plenfunkcian fasadon por salutintaj uzantoj administri " +"siajn eldonitajn pakojn kaj versiojn." + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "Kiel modernigi projekton uzantan ``setup.py``?" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "Ĉu aldoni ``pyproject.toml``?" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" +"Dosiero :term:`pyproject.toml` estas rekomendegata. La ekzisto de " +"dosiero :file:`pyproject.toml` mem ne tre gravas. [#]_ Tio, kio estas " +"rekomendegata, estas la tabelo ``[build-system]`` en :file:`pyproject.toml`." + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" +"Notu, ke tio influas la konstruado-izolan funkcion de pip; vidu ĉi-sube." + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" +"Ne, :file:`setup.py` povas ekzisti en moderna :ref:`setuptools`-baza " +"projekto. La dosiero :term:`setup.py` estas valida agorda dosiero por " +"setuptools, verkita en Python. Tamen, la jenaj komandoj estas evitindaj; oni " +"**DEVAS NE** ruli tiujn, kaj oni anstataŭe uzu la rekomendatajn " +"anstataŭantajn komandojn:" + +#: ../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 "Por pliaj detaloj:" + +#: ../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 "De kie komenci?" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" +"La :term:`projekto ` devas ĉe la radiko de sia fontarbo enhavi " +"dosieron :file:`pyproject.toml` enhavantan tabelon ``[build-system]`` jene:" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" +"Tio estas la norma metodo por sciigi :term:`konstruan fasadon `, ke :ref:`setuptools` estas la :term:`konstrua malfasado ` por la projekto." + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" +"Notu ke la ĉeesto de dosiero :file:`pyproject.toml` (eĉ malplena) " +"igas :ref:`pip` ŝanĝi la aprioran konduton al uzo de *konstrua izolado*." + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr ":ref:`distributing-packages`" + +#: ../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/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +#, fuzzy +#| msgid ":doc:`pip:reference/build-system/pyproject-toml`" +msgid ":doc:`pip:reference/build-system`" +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 "Kiel pritrakti pliajn konstrutempajn dependecojn?" + +#: ../source/guides/modernize-setup-py-project.rst:76 +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 " +"`." +msgstr "" +"Krom setuptools mem, se :file:`setup.py` dependas de alia triapartia " +"bibilioteko (ekster la norma biblioteko de Python), la listo ``requires`` de " +"la tabelo ``[build-system]`` devas inkluzivi ĝin, por ke la konstrua fasado " +"instalos ĝin dum konstruado de la :term:`distribuo `." + +#: ../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 "Ekzemple, jena dosiero :file:`setup.py`:" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" +"postulas dosieron :file:`pyproject.toml` jene (:file:`setup.py` restas " +"senŝanĝe):" + +#: ../source/guides/modernize-setup-py-project.rst:117 +msgid "What is the build isolation feature?" +msgstr "Kio estas la konstruo-izolada funkcio?" + +#: ../source/guides/modernize-setup-py-project.rst:119 +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." +msgstr "" +"Konstrua fasado tipe kreas provizoran virtualan medion, en kiu instaliĝas " +"nur la konstruaj dependaĵoj (kaj la dependaĵoj de dependaĵoj) en la listo de " +"``build-system.requires``, kaj konstruas en tiu medio." + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" +"Por kelkaj projektoj, tia izolado estas nedezirata kaj malaktivigebla jene:" + +#: ../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 "Kiel enmeti pakajn metadatenojn?" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" +"Ĉiaj statikaj metadatenoj estas nedevige moveblaj al tabelo ``[project]`` " +"en :file:`pyproject.toml`." + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "estas plene anstataŭigebla per :file:`pyproject.toml` jene:" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" +"Vidu :ref:`pyproject-project-table` por la plena specifo pri la enhavo " +"permesata en la tabelo ``[project]``." + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "Kiel enmeti dinamikajn metadatenojn?" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" +"Se iu paka metadatena kampo ne estas statika, ĝi devas esti markita kiel " +"``dynamic`` en tiu tabelo ``[project]``." + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "estas modernigebla jene:" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr ":ref:`declaring-project-metadata-dynamic`" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "Kiel fari, se io neŝanĝebla atendas dosieron ``setup.py``?" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" +"Ekzemple, ekzistas procezo ne facile ŝanĝebla, kiu devas ruli komandon kiel " +"``python setup.py --name``." + +#: ../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 "" +"Estas bone lasi dosieron :file:`setup.py` en la projekta fontarbo, eĉ post " +"oni movis ĉiom da enhavo al :file:`pyproject.toml`. La dosiero povas esti " +"tiel minimuma kiel la jeno:" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr ":ref:`pyproject-toml-spec`" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr ":doc:`setuptools:build_meta`" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "Plurversiaj instaloj" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" +"easy_install permesas samtempan instaladon de malsamaj versioj de la sama " +"projekto en unu medio komuna por pluraj programoj, kiuj devas postuli taŭgan " +"version de la projekto rultempe (per ``pkg_resources``)." + +#: ../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." +msgstr "" +"Por multaj uzkazoj, virtuala medio solvas tion sen la komplikaĵo de la " +"direktivo ``require``. Tamen, la avantaĝo de paralelaj instalaĵoj en la sama " +"medio estas, ke tio funkcias por medio uzata de pluraj programoj, ekzemple " +"por la sistema Python en Linux-distribuo." + +#: ../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." +msgstr "" +"La grava problemo pri ``pkg_resources``-baza paralela instalado estas, ke " +"importado de ``pkg_resources`` tuj ŝlosas la *aprioran* version de ĉio " +"havebla ĉe ``sys.path``. Tio estas problema, ĉar ``setuptools``-kreita " +"komandlinia programeto uzas ``pkg_resources`` por serĉi rulotan enirpunkton. " +"Tio implicas, ke ekzemple vi ne povas uzi ``require``-teston alvokitan per " +"``nose`` or WSGI-programon alvokitan per ``gunicorn``, se via programo " +"bezonas alian version de io havebla ĉe la norma ``sys.path`` – la " +"programvolvilo por la ĉefprogramo ŝlosos la aprioran version, kaj la posta " +"alvoko al ``require`` en via propra kodo malsukcesos pro iluzia versia " +"konflikto." + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "Paki duumajn etendaĵojn" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "8 Decembro 2013" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" +"La referenca interpretilo CPython, krome permesanta ruli Python-kodon, ankaŭ " +"disponigas riĉan API en C por aliaj programoj. Unu el la plej oftaj uzoj de " +"tiu API en C estas krei importeblan C-etendaĵon por tio, kio malfacilas per " +"pura Python-kodo." + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "Superrigardo pri duumaj etendaĵoj" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "Uzkazoj" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "Jen la tri oftaj uzkazoj de duumaĵ etendaĵoj:" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" +"**akcelila modulo**: tia modulo estas plene memstara kaj celas pli rapidi ol " +"la ekvivalenta pur-Python-a kodo en CPython. Ideale, akcelila modulo ĉiam " +"havas pur-Python-an ekvivalenton uzotan, se la akcelita versio ne estas " +"disponebla ĉe iu sistemo. La norma biblioteko de CPython ofte uzas " +"akcelilaijn modulojn. *Ekzemple*: Importante ``datetime``, Python uzas la " +"modulon `datetime.py `_, se la C-realigo ( `_datetimemodule.C `_) ne estas disponebla." + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" +"Unu rimarkinda trajto de C-etendaĵo estas, ke ĝi povas liberigi la mallokan " +"interpretilan seruron de CPython dum longdaŭra operacio, se ĝi ne bezonas " +"alvoki interpretilan rultempon reen (por kaj ĉefprocesoraj kaj eneligaj " +"operacioj)." + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" +"Ne ĉia etendaĵo-modulo estas sole en unu el la ĉi-supraj kategorioj. La " +"etendaĵo-modulo en NumPy, ekzemple, estas por ĉiuj tri uzkazoj – ĝi movas " +"internajn iteraciojn al C por rapidigo, volvas eksterajn bibliotekojn en C, " +"Fortrano kaj aliaj lingvoj, kaj uzas malaltnivelajn sistemajn interfacojn " +"por kaj CPython kaj la mastruma sistemo por samtempa rulado de vektorigitaj " +"operacioj kaj por regi la precizan memoraranĝon de kreitaj objektoj." + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "Malavantaĝoj" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" +"La ĉefmalavantaĝo de duuma etendaĵo estas, ke posta distribuado de la " +"programo estas malfacila. Unu el la avantaĝoj de Python estas la " +"plurplatformeco. La lingvoj por etendaĵa modulo (ofte C aŭ C++, sed povas " +"esti ajna lingvo bindebla al la C API de CPython) ordinare postulas kreadon " +"de duumaĵoj po unu por ĉiu platformo." + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "Tio signifas, ke duumaj etendaĵoj:" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" +"postulas, ke aŭ uzantoj povu konstrui ilin de fonto, aŭ aliulo eldonu " +"konstruitajn duumaĵojn por oftaj platformoj" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" +"eble ne kongruas kun diversaj konstruoj de la referenca interpretilo CPython" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" +"ofte ne funkcias ĝuste kun alternativaj interpretiloj kiel ekzemple PyPy, " +"IronPython aŭ Jython" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" +"se ĝi mankodita, malfaciligas evoluadon postulante, ke evoluiganto konu ne " +"nur Python, sed ankaŭ la programlingvon por la duuma etendaĵo kaj la " +"detalojn de la C API de CPython." + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" +"malfaciligas mastrumadon (se pure Python-a alternativo estas provizita), " +"postulante duoblan realigon de ĉiuj ŝanĝoj kaj komplikante la testaron pri " +"rulado de ambaŭ versioj." + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" +"Alia malavantaĝo de dependado je duuma etendaĵo estas, ke alternativa " +"importa meĥanismo (kiel importado de modulo rekte el zip-arĥivo) ofte ne " +"funkcias por etendaĵmodulo (ĉar la dinamika ŝargada meĥanismo en la " +"plejmulto de platformoj nur povas ŝargi bibliotekon el disko)." + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "Alternativoj al malaŭtomate koditaj akcelilaj moduloj" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" +"Se oni uzus etendaĵan modulon nur por plirapidigi kodon (post kiam profilo " +"markis tiujn partojn de la kodo, por kiuj la plirapidigo sufiĉe necesas " +"malgraŭ la plia bezonata mastrumado), oni konsideru kelkajn alternativojn:" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" +"por longe ruliĝanta programo, la ĝustatempe tradukita `interpretilo PyPy " +"`__ povas esti taŭga alternativo al la norma " +"interpretilo CPython. La ĉefobstaklo kontraŭ ekuzado de PyPy estas ofte " +"dependo de alia duumaĵa etendaĵo-modulo – dum PyPy ja imitas la C API de " +"CPython, modulo dependanta de tiu API kaŭzas problemojn por la ĝustatempa " +"tradukilo de PyPy, kaj la imitada tavolo ofte reliefigas kaŝitajn makulojn " +"en etendaĵo-modulo aktuale toleratan de CPython (ofte pri eraroj pri " +"referenco-kalkulado – objekto havanta unu vivan referencon anstatŭ du ne " +"estas problema, sed neniu referenco anstataŭ unu estas grave problema)." + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" +"`Cython `__ estas matura statika tradukilo, kiu povas " +"traduki la plejparton de Python-kodo al C-etendaĵomoduloj. La komenca " +"tradukado povas iom rapidigi la kodon (preterpasante la interpretilon " +"CPython), kaj la nedeviga statika tipado de Cython povas plu rapidi la " +"kodon. Uzado de Cython ankoraŭ havas la `malavantaĝojn `_ pri " +"duumaj etendaĵoj, sed havas la avantaĝon de kutimeco por Python-programantoj " +"(relative al aliaj lingvoj kiel C aŭ C++)." + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" +"`Numba `__ estas pli nova ilo, kreita de anoj de " +"la scienca Python-komunumo, celanta uzi LLVM por rultempa tradukado de " +"partoj de Python-programo al maŝinkodo. Ĝi postulas la haveblon de LLVM je " +"tiu sistemo, sur kiu ruliĝas la kodo. Tamen ĝi povas multe plirapidigi la " +"kodon, speciale por operacioj vektorigeblaj." + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "Alternativoj al malaŭtomate koditaj volvilaj moduloj" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" +"La ĉi-subaj manieroj ne simpligas la kazon de distribuo sed *ja* povas " +"simpligi la taskon de ĝisdatigado de volvantaj moduloj." + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" +"Krom sia utileco por krei akcelilan modulon, `Cython `__ estas ankaŭ vaste uzata por krei volvantan modulon de API en C aŭ C++. " +"Por tio oni volvas la interfacojn malaŭtomate. Ekzistas multo da libereco " +"pri fasonado kaj optimumado de la volvanta kodo. Tamen, tio eble ne estas " +"bona elekto por rapide volvi grandegan API. Vidu la `liston de triapartiaj " +"iloj `_ por aŭtomata volvado " +"per Cython. Ĝi ankaŭ subtenas rapidajn Python-realigojn kun CPython-eca C-" +"API kiel PyPy kaj Pyston." + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" +":doc:`pybind11 ` estas pure C++11-a biblioteko provizanta " +"puran C++-interfacon al la API de CPython (kaj PyPy). Ĝi ne postulas " +"antaŭtraktadon; ĝi estas plene en ŝablona C++. Helpiloj inkluziviĝas por " +"konstruado kun Setuptools aŭ CMake. Ĝi estis bazita sur `Boost.Python " +"`__, " +"sed ne postulas la Boost-bibliotekojn aŭ BJam." + +#: ../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 "" + +#: ../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." +msgstr "" +"Unu el la ĉefavantaĝoj de ``cffi`` estas kongrueco kun la ĝustatempa " +"tradukado de PyPy, tiel ke volvanta modulo uzanta CFFI povas plene " +"partopreni en la spuradaj optimumigoj de la ĝustatempa tradukilo de PyPy." + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" +"`SWIG `__ estas generilo de volva interfaco, por " +"alvoki C/C++-kodon el multaj programlingvoj inkluzive de Python." + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" +"La modulo ``ctypes`` de la norma biblioteko, kiu utilas por atingi C-" +"interfacojn kiam ĉapaj informoj ne estas haveblaj, tamen suferas de la " +"fakto, ke ĝi funkciigas sole ĉe la nivelo de la ABI de C kaj tial ne povas " +"kontroli kongruecon inter la interfaco fakte eksportita de la biblioteko kaj " +"tiu deklarita en la Python-kodo. Kompare, la ĉi-supraj alternativoj ĉiuj " +"funkcias ĉe la nivelo de la *ABI* de C, uzante C-ĉapdosierojn por certigi " +"kongruecon inter la interfaco eksportita de la uzata biblioteko kaj tiu " +"atendata de la uzanta Python-modulo. Dum `cffi` *povas* funkcii rekte ĉe la " +"nivelo de C ABI, ĝi suferas de la samaj interfaco-kongruecaj problemoj kiel " +"``ctypes``, se ĝi estas tiel uzata." + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "Alternativoj por malaltnivela sistema atingado" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "Realigi duumajn etendaĵojn" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" +"The CPython-gvidilo :doc:`Extending and Embedding ` " +"inkluzivas enkondukon al verkado de :doc:`propra etendaĵa modulo en C " +"`." + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" +"FIXME: Klarigu, ke tio estas unu el la kialoj por *ne* malaŭtomate kodi " +"etendaĵajn modulojn ☺" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "Vivciklo de etendaĵa modulo" + +#: ../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: Plenigu ĉi tiun paragrafon." + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "Implicoj pri komuna statika stato kaj subinterpretiloj" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "Implicoj de la Malloka Interpretila Seruro" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "Memoro-asignaj API-oj" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "ABI-Kongrueco" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" +"La C API de CPython ne garantias stabilecon de ABI inter minoraj eldonoj " +"(3.2, 3.3, 3.4 ktp). Tio tipe signifas, ke se oni konstruas etendaĵo-modulon " +"por unu versio de Python, do ĝi nur garantiite funkcias por la sama minora " +"versio de Python kaj ne por aliaj minoraj versioj." + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" +"La paĝo de CPython pri :doc:`stabileco de C API ` " +"detalas informojn pri la garantioj de la stabileco de API kaj ABI, kiel uzi " +"la Limigitan API, kaj la ekzakta enhavo de la «Limigita API»." + +#: ../source/guides/packaging-binary-extensions.rst:283 +msgid "Building binary extensions" +msgstr "Konstrui duumajn etendaĵojn" + +#: ../source/guides/packaging-binary-extensions.rst:285 +msgid "FIXME: Cover the build-backends available for building extensions." +msgstr "FIXME: Diskuti konstruajn malfasadojn por konstrui etendaĵojn." + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "Konstrui etendaĵojn por pluraj platformoj" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" +"Por tipaj etendaĵoj, oni devas konstrui wheel-ojn por ĉiuj subtenataj " +"platformoj. Tio signifas, ke la nombro de konstruendaj wheel-oj estas la " +"jena produto::" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "Duumaj etendaĵoj por Windows" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" +"Antaŭ ol konstrui duuman etendaĵon, oni devas havi taŭgan tradukilon. Sur " +"Windows, la oficiala CPython-interpretilo estis konstruita per Visual C, kaj " +"oni uzu ĝin por konstrui kongruan duuman etendaĵon. Por starigi konstruan " +"medion por duuma etendaĵo, instalu `Visual Studio Community Edition `__ – ajna lastatempa versio taŭgas." + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" +"Unu averto: se vi uzas Visual Studio 2019 aŭ pli novan, via etendaĵo " +"dependos de «ekstra» dosiero, ``VCRUNTIME140_1.dll``, kune kun " +"``VCRUNTIME140.dll``, de kiu ĉiuj antaŭaj versioj ĝis 2015 dependas. Tio " +"estas ekstra postulo por uzi vian etendaĵon kun versioj de CPython ne " +"inkluzivanta la ekstran dosieron. Por eviti tion, vi povas aldoni la " +"tradukilan argumenton ``/d2FH4-``. Novaj versioj de Python eble inkluzivas " +"ĉi tiun dosieron." + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" +"Ni ne rekomendas konstruadon por versio de Python antaŭ 3.5, ĉar malnova " +"versio de Visual Studio ne plu haveblas de Microsoft. Se oni devas konstrui " +"por malnova versio, oni agordu ``DISTUTILS_USE_SDK=1`` kaj `MSSdk=1`` por " +"uzi la aktuale aktivan version de MSVC, kaj oni zorge fasonu la etendaĵon ne " +"uzante ``malloc``/``free`` el malsamaj bibliotekoj, evitante dependon de " +"ŝanĝitaj datenstrukturoj ktp. Ilo por generado de etendaĵa modulo ofte " +"aŭtomate evitas tion." + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "Duumaj etendaĵoj por Linux" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" +"Linux-duumaĵo devas uzi sufiĉe malnovan ``glibc`` por kongrueco kun malnovaj " +"distribuoj. La Docker-diskokopio por `manylinux `_ estas konstrua medio kun ``glibc`` sufiĉe malnova por la " +"plejmulto de aktualaj Linux-distribuoj sur oftaj arĥitekturoj." + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "Duumaj etendaĵoj por macOS" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" +"Binara kongrueco sur macOS dependas de la celata minimuma disponiga sistemo, " +"ekz. *10.9*, kio estas ordinare specifita per la media variablo " +"``MACOSX_DEPLOYMENT_TARGET`` dum konstruaĵo de duumaĵoj sur macOS. Dum " +"konstruado kun setuptools / distutils, oni specifas la disponiga celo per la " +"flago ``--plat-name``, ekz. kun la valoro ``macosx-10.9-x86_64``. Por oftaj " +"disponigaj celoj por Python-distribuoj por macOS, vidu `MacPython Spinning " +"Wheels Wiki `_." + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "Eldoni duumajn etendaĵojn" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" +"Eldonado de duuma etendaĵo al PyPI uzas la saman alŝutan meĥanismon kiel " +"eldonado de pure Python-a pako. Oni konstruas wheel-dosieron por la etendaĵo " +"per la konstrua malfasado kaj alŝutas ĝin al PyPI per :doc:`twine " +"`." + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "Evitu nur-duumajn eldonojn" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" +"Estas forte rekomendate, ke vi eldonu kaj la duumajn etendaĵojn kaj la " +"fontkodon por konstrui ilin. Tio permesas al uzantoj laŭbezone konstrui la " +"etendaĵon de fonto. Speciale, tio necesas por tiuj Linux-distribuoj, kiuj " +"konstruas de fonto per siaj propraj konstrusistemoj por siaj pakdeponejoj." + +#: ../source/guides/packaging-binary-extensions.rst:374 +msgid "Weak linking" +msgstr "Malforta bindado" + +#: ../source/guides/packaging-binary-extensions.rst:379 +msgid "Additional resources" +msgstr "Pliaj rimedoj" + +#: ../source/guides/packaging-binary-extensions.rst:381 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "Interplatforma generado de wheel per scikit-build" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" +"La pako `scikit-build `_ " +"helpas abstraktigi interplatforman konstruadon kaj provizas pliajn kapablojn " +"pri kreado de duumaj etendaĵaj pakoj. Pliaj informoj disponeblas ĉe la " +"paragrafo pri `la C-rultempo, tradukilo, kaj konstrusistema generilo " +"`_ por duumaj " +"etendaĵmoduloj de Python." + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "Enkonduko al C/C++-aj etendaĵaj moduloj" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" +"Por plia klarigo pri kiel CPython uzas etendaĵan modulon sur Debian-sistemo, " +"vidu la jenajn artikolojn:" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" +"`Kio estas etendaĵ-moduloj de (C)Python? `_" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" +"`Malakiri la mallokan interpretilan seruron `_" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" +"`Verki cpython-etendaĵaj moduloj per C++ `_" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "Pliaj konsideroj por duuma wheel" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" +"La retejo `pypackaging-native `_ " +"havas pliajn detalojn pri pakado de Python-pako kun indiĝena kodo. Ĝi estas " +"resumo de la plej gravaj problemoj pri pakado de tia projekto kune kun " +"detalaj klarigoj kaj referencoj." + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" +"Jen ekzemploj de diskutotaj temoj: ne-Python-a tradukita dependeco " +"(«indiĝena dependeco»), la graveco de la ABI (aplika binara interfaco) de " +"indiĝena kodo, dependeco sur SIMD-kodo, intertradukado." + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "Paki nomspacajn pakojn" + +#: ../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 "" +"Nomspaca pako permesas al vi disfendi la subpakojn kaj modulojn en " +"unu :term:`pako ` al pluraj, apartaj :term:`distribuaj pakoj " +"` (nomitaj **distribuoj** en ĉi tiu dokumento por " +"eviti ambiguecon). Ekzemple, se oni havas la jenan pako-strukturon:" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "Kaj vi uzas ĉi tiun pakon en via kodo jene::" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "Do vi povas disrompi tiujn subpakojn en du apartajn distribuojn:" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "Ĉiu subpako estas nun aparte instalebla, uzebla kaj versihava." + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" +"Nomspaca pako povas utili por granda kolekto de loze rilataj pakoj (kiel " +"ekzemple granda aro da klientobibliotekoj por pluraj servoj de unu firmao). " +"Tamen, nomspaca pako havas kelkajn problemojn kaj ne taŭgas por ĉiaj celoj. " +"Simpla alternativo estas uzi prefikson en la nomojn de distribuoj kiel " +"ekzemple ``import mianomspaco_subpako_a`` (oni povas eĉ uzi ``import " +"mianomspaco_subpako_a as subpako_a`` por mallongigi)." + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "Krei nomspacan pakon" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" +"Ekzistas nuntempe du malsamaj manieroj krei nomspacan pakon, el kiu la dua " +"estas evitinda:" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" +"Uzi `indiĝenan nomspacan pakon `_. Tiu speco de " +"nomspaca pako estas difinita en :pep:`420` kaj havebla ekde Python 3.3. Tio " +"estas rekomendata, se pakoj en via nomspaco subtenas Python 3 aŭ instaladon " +"per ``pip``." + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" +"Uzi `malnovan nomspacan pakon `_, kiu estas aŭ " +"`pkgutil-stila nomspaca pako `_ aŭ " +"`pkg_resources-stila nomspaca pako `_." + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "Indiĝenaj nomspacaj pakoj" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" +"Python 3.3 aldonis **implicitan** nomspacan pakon per :pep:`420`. Por krei " +"indiĝenan nomspacan pakon, necesas nur preterlasi :file:`__init__.py` en la " +"nomspaca paka dosierujo. Jen ekzempla dosierstrukturo (laŭ :ref:`src-layout " +"`):" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" +"Gravegas, ke ĉiu distribuo uzanta la nomspacan pakon aŭ ne " +"havas :file:`__init__.py` aŭ havas pkgutil-stilan :file:`__init__.py`. Se iu " +"distribuo ne faras tion, tio malsukcesigos la nomspacan logikon, kaj tial la " +"aliaj subpakoj ne estos importeblaj." + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "Oni povas fari la samon per :file:`setup.cfg`:" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "Aŭ :file:`setup.py`:" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" +":ref:`setuptools` aŭtomate serĉos implicitajn nomspacajn pakojn en la " +"dosieruja strukturo." + +#: ../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 "" +"Plena funkcianta ekzemplo de du indiĝenaj nomspacaj pakoj troviĝas en la " +"`indiĝen-nomspaca ekzempla projekto `_." + +#: ../source/guides/packaging-namespace-packages.rst:151 +msgid "" +"Because native and pkgutil-style namespace packages are largely compatible, " +"you can use native namespace packages in the distributions that only support " +"Python 3 and pkgutil-style namespace packages in the distributions that need " +"to support Python 2 and 3." +msgstr "" +"Ĉar indiĝenaj kaj pkgutil-stilaj nomspacaj pakoj estas plejparte kongruaj, " +"oni povas uzi indiĝenan nomspacan pakon en distribuo nur por Python 3 kaj " +"pkgutil-stilan nomspacan pakon en distribuo por kaj Python 2 kaj Python 3." + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +msgstr "Malnovaj nomspacaj pakoj" + +#: ../source/guides/packaging-namespace-packages.rst:160 +#, fuzzy +#| 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." +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 one of these " +"methods." +msgstr "" +"Tiuj du metodoj por krei nomspacopakojn antaŭ :pep:`420`, nun estas " +"malnoviĝintaj kaj evitindaj krom se oni bezonas kongruecon kun pako jam " +"uzanta tiun metodon. Ankaŭ, :doc:`pkg_resources ` " +"estas evitinda." + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" +"Por migri ekzistantan pakon, ĉiuj pakoj en la nomspaco devas esti migritaj " +"samtempe." + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" +"Dum indiĝena nomspaca pako kaj pkgutil-stila nomspaca pako kongruas inter " +"si, pkg_resources-stila nomspaca pako ne kongruas kun la aliaj metodoj. " +"Estas malrekomendate miksi plurajn metodojn en malsamaj distribuoj " +"provizantaj pakojn en la saman nomspacon." + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "pkgutil-stilaj nomspacaj pakoj" + +#: ../source/guides/packaging-namespace-packages.rst:175 +#, fuzzy +#| 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." +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" +"Python 2.3 enkondukis la modulon :doc:`pkgutil ` kaj " +"la funkcion :py:func:`python:pkgutil.extend_path`. Oni povas uzi tiujn por " +"deklari nomspacopakon kongruan kun kaj Python 2.3+ kaj Python 3. Tio estas " +"la rekomendata metodo por la plej alta nivelo de kongrueco." + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" +"Por krei pkgutil-stilan nomspacan pakon, oni devas provizi " +"dosieron :file:`__init__.py` por la nomspaca pako:" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" +"La dosiero :file:`__init__.py` por la nomspaca pako devas enhavi la jenon:" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" +"**Ĉiu** distribuo uzanta la nomspacan pakon devas inkluzivi " +"tian :file:`__init__.py`. Se distribuo ne inkluzivus tian, la namspaca " +"logiko malsukcesus, kaj aliaj subpakoj ne estus importeblaj. Ajna kroma kodo " +"en :file:`__init__.py` ne estus uzebla." + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" +"Plena funkcianta ekzemplo de du pkgutil-stilaj nomspacaj pakoj troviĝas en " +"la `pkgutil-nomspaca ekzempla projekto `_." + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "pkg_resources-stilaj nomspacaj pakoj" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +#, fuzzy +#| 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." +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 ` provizas la funkcion " +"`pkg_resources.declare_namespace`_ kaj la argumenton ``namespace_packages`` " +"de :func:`~setuptools.setup`. Oni uzas tiujn kune por deklari nomspacan " +"pakon. Kvankam tiu maniero ne plu estas rekomendata, ĝi estas vaste uzata en " +"ekzistantaj nomspacaj pakoj. Se oi verkas novan distribuon en ekzistanta " +"nomspaca pako uzanta tiun metodon, estas rekomendate daŭre uzi tion, ĉar la " +"diversaj metodoj ne kongruas inter si, kaj ne konsilindas provi migri " +"ekzistantan pakon." + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" +"Por krei pkg_resources-stilan nomspacan pakon, oni devas provizi " +"dosieron :file:`__init__.py` por la nomspaca pako:" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" +"Kelkaj malnovaj rekomendoj konsilas la jenon en la nomspaca " +"pako :file:`__init__.py`:" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" +"La kialo estis, ke en la malofta kazo kiam setuptools ne estas havebla, pako " +"povas funkcii kiel pkgutil-stila pako. Tio ne estas konsilinda, ĉar pkgutil " +"kaj pkg_resources-stilaj nomspacopakoj ne kongruas inter si. Se la ĉeesto de " +"setuptools estas problema, do la pako simple eksplicite dependu de " +"setuptools per ``install_requires``." + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" +"Fine, ĉiu distribuo devas provizi la argumenton ``namespace_packages`` al " +"to :func:`~setuptools.setup` en :file:`setup.py`. Ekzemple:" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" +"Eldoni pakajn distribuajn eldonoj per la laborfluoj por kontinuaj integrado " +"kaj disponigo ĉe GitHub Actions" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" +"Ĉi tiu gvidilo *supozas*, ke vi jam havas projekton, ke vi scias kiel " +"konstrui distribuojn, kaj ke *ĝi ekzistas sur GitHub*. Ĉi tiu gvidilo ankaŭ " +"ignoras detalojn pri konstruado de platformo-specifa projekto. Se vi havas " +"duuman komponanton, vidu la ekzemplojn de GitHub-Agoj " +"por :ref:`cibuildwheel`." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:25 +#, fuzzy +#| msgid "Configuring trusted publishing" +msgid "Configuring Trusted Publishing" +msgstr "Starigi fidatan eldonadon" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:27 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:51 +msgid "Let's begin! 🚀" +msgstr "Ek! 🚀" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:53 +msgid "Go to https://pypi.org/manage/account/publishing/." +msgstr "Iru al https://pypi.org/manage/account/publishing/." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" +"Nun iru al https://test.pypi.org/manage/account/publishing/ kaj ripetu la " +"duan paŝon, sed tajpante ``testpypi`` kiel la nomon de la GitHub-medio." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" +"Viaj «estontaj» eldonantoj nun pretas por unua uzo kaj kreos viajn " +"projektojn aŭtomate post unua uzo." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" +"Se vi ne havas konton ĉe Prova PyPI, vi devas krei ĝin. Ĝi ne estas sama " +"kiel konto ĉe ordinara PyPI." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:78 +#, fuzzy +#| msgid "" +#| "For security reasons, you must require `manual approval `_ on each " +#| "run for the ``pypi`` environment." +msgid "" +"For security reasons, you must require `manual approval `_ on each run for the ``pypi`` environment." +msgstr "" +"Pro sekureco, vi devas postuli `malaŭtomatan aprobon `_ je ĉiu rulo por " +"la medio ``pypi``." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "Krei laborfluan difinon" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" +"Laborfluoj por kontinuaj integrado kaj disponigo ĉe GitHub estas deklaritaj " +"en YAML-dosieroj en la dosiero ``.gitub/workflows/`` de via deponejo." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +#, fuzzy +#| msgid "Let's create a ``.github/workflows/publish-to-test-pypi.yml`` file." +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "Ni kreu dosieron ``.github/workflows/publish-to-test-pypi.yml``." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" +"Uzu signifan nomon, kaj difinu tiun eventon, kiu igos GitHub ruli la " +"laborfluon:" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:101 +msgid "Checking out the project and building distributions" +msgstr "Elpreni la projekton kaj konstrui distribuojn" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" +"Ni difinus du taskojn por eldoni al PyPI kaj Prova PyPI respektive kaj " +"ekstran taskon por konstrui la distribuajn pakojn." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" +"Unue, ni difinas la taskon por konstrui la distribuajn pakojn de via " +"projekto kaj konservi ilin por posta uzo:" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" +"Tio elŝutos vian deponejon al la kontinuintegrilo kaj instalos kaj aktivigos " +"la plej novan eldonon de Python 3." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" +"Nun ni povas konstrui la distribuojn el fonto kaj konservi ilin. En ĉi tiu " +"ekzemplo, ni uzos la pakon ``build``. Do aldonu la jenon al la listo de " +"paŝoj:" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "Difini laborfluan taskan medion" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:130 +#, fuzzy +#| 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." +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 "" +"Nun, ni aldonu komencan agordon por la tasko eldoni al PyPI. Ĝi estas " +"procezo, kiu rulos komandojn difinotajn. En ĉi tiu gvidilo, ni uzas la plej " +"novan stabilan longdaŭre subtenatan version de Ubuntu provizitan de GitHub-" +"Agoj. Tio ankaŭ difinas GitHub-Medio por ruli la taskon, kaj retadreson por " +"montrado en la grafika fasado de GitHub. Plie ĝi subtenas akiri ĵetonon de " +"OpenID Connect, kiun la ago ``pypi-publish`` bezonas por sensekreta fidata " +"eldonado al PyPI." + +#: ../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 "" +"Tio ankaŭ certigas, ke la PyPI-eldona laborfluo nur ekos, se la aktuala " +"enmeto havas etikedon." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "Eldoni la distribuon al PyPI" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:150 +msgid "Finally, add the following steps at the end:" +msgstr "Fine, postmetu la jenajn paŝojn:" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" +"Tiu paŝo uzas la GitHub-ago `pypa/gh-action-pypi-publish`_: post elŝuto de " +"la distribua pako per la ago `download-artifact`_, ĝi alŝutas la enhavon de " +"la dosierujo ``dist/`` al PyPI senkondiĉe." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "Aparta laborfluo por eldoni al TestPyPI" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" +"Nun ripetu tiujn paŝojn, kreante alian taskon por eldonado al la pakindekso " +"Prova PyPI sub la sekcio ``jobs``:" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" +"Postuli malaŭtomatan aprobadon en la GitHub-medio ``testpypi`` ordinare ne " +"necesas, ĉar ĝi laŭfasone ruliĝas post ĉiu enmeto en la ĉefbranĉon kaj ofte " +"indikas sanan eldonadan ĉenstablon." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "La plena laborfluo por kontinuaj integrado kaj disponigo" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "Jen alineo pri la plena laborfluo laŭ la ĉi-supra gvidilo." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "Jen fino!" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" +"Estas rekomendata teni la integritajn GitHub Actions ĉe la plej novaj " +"versioj, ĝisdatigante ofte." + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "Konstruado kaj Eldonado" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "Gastigado" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +msgid "Installation" +msgstr "Instalado" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "0; url=../../discussions/single-source-version/" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "Alidirektante malnovan hiperligon pri unufontigo de paka versio…" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "Se la paĝo ne reŝargiĝas aŭtomate, vidu :ref:`single-source-version`." + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "Subteni plurajn versiojn de Python" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "24 Decembro 2014" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" +"Malaŭtomata testado por certigi, ke la pako funkcias ĝuste sur ĉiuj celataj " +"versioj de Python (kaj mastrumaj sistemoj!), postulas multegon da tempo. " +"Feliĉe, ekzistas pluraj iloj por helpi pri tio, kiujn ni diskutos ĉi tie." + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "Aŭtomata testado kaj kontinua integrado" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" +"Ekzistas pluraj gastigaj servoj por aŭtomata testado. Tiaj servoj ordinare " +"observadas la fontkodan deponejon (ekz. ^©e `GitHub `_ " +"aŭ `Bitbucket `_) kaj rulas la testaron post ĉiu " +"modifo." + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" +"Tiaj servoj ankaŭ ofertas funkcion por ruli la testaron sur *multaj versioj " +"de Python*, rapide sciigante pri ĉu la kodo funkcias, sen malaŭtomata " +"testado far la aŭtoro." + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" +"Vikipedio havas detalan `komparon `_ inter pluraj sistemoj por " +"kontinua integrado. Ekzistas du gastigitajn servojn, kiuj kune provizas " +"aŭtomatan testadon por Linux, Mac kaj Windows:" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +#, fuzzy +#| 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." +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." +msgstr "" +"`Travis CI `_ provizas kaj Linux-an kaj macOS-an " +"mediojn. La medio Linux estis Ubuntu 12.04 LTS Servila Eldono 64-bita, dum " +"la medio macOS estis 10.9.2, kiam ĉi tiu dokumento estis verkita." + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" +"`Appveyor `_ provizas Windows-medion (Windows " +"Server 2012)." + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" +"Kaj `Travis CI`_ kaj Appveyor_ postulas `YAML `_-dosieron " +"specifantan la instrukciojn pri testado. Se iu testo malsukcesos, la eliga " +"protokolo pri tiu estas inspektebla." + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" +"Por Python-projekto disponigota sur kaj Python 2 kaj Python 3 per unufonta " +"strategio, ekzistas kelkaj opcioj." + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "Iloj por unufontaj Python-pakoj" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" +"'six '_ estas ilo verkita de Benjamin " +"Peterson por glatigi la diferencojn inter Python 2 kaj Python 3. La pako " +"six_ ĝuas vastan uzadon kaj estas rigardata kiel fidinda maniero verki unu-" +"fontan Python-modulon por kaj Python 2 kaj Python 3. La modulo six_ estas " +"uzebla ekde Python 2.5. Ilo nomita `modernize `_, verkita de Armin Ronacher, povas aŭtomate efektivigi la kodo-" +"modifojn per six_." + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" +"Simile al six_, `python-future `_ " +"estas pako por kongrueco inter Python 2 kaj Python 3. Malkiel six_, tiu pako " +"celas kunfunkciigi Python 2 kaj Python 3 per lingva sintakso de unu el la du " +"Python-versioj: oni povas uzi" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "modulon de sintakso Python 2 en projekto de Python 3." + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "modulon de sintakso Python 3 en projekto de *Python 2*." + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" +"Per la dudirekteco, python-future_ ofertas manieron konverti pakon de Python " +"2 al la sintakso de Python 3 modulon post modulo. Tamen, malkiel six_, " +"python_future_ nur subtenas Python 2.6+. Kiel six_, python_future_ provizas " +"du programetojn, ``futurize`` kaj ``pasteurize``, por modulo de Python 2 kaj " +"de Python 3 respektive." + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" +"Uzo de six_ aŭ python_future_ aldonas ekstran rultempan dependecon al la " +"pako: kun python-future_, oni rulu la programon ``futurize`` kun la flago " +"``--stage1`` por efektivigi nur tiajn ŝanĝojn, kiajn Python 2.6+ jam " +"provizas por kongrueco kun Python 3. Ajna restanta problemo pri kongrueco " +"postulas malaŭtomatan modifon." + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "Kio estas en kiu Python?" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" +"Ned Batchelder listigas la ŝanĝojn en ĉiu eldono de Python por `Python 2 " +"`__, " +"`Python 3.0–3.3 `__ kaj `Python 3.4-3.6 `__. Per tiuj " +"listoj oni povas kontroli, ĉu ŝanĝoj inter versioj de Python gravas pri onia " +"pako." + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "Subteni Windows per Appveyor" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "3 Decembro 2015" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" +"Tiu paragrafo temas pri kiel uzi la senkostan servon `Appveyor`_ de kontinua " +"integrado, por subteni Windows por via projekto. Tio inkluzivas testi la " +"kodon sur Windows, kaj konstrui Windows -duumaĵojn por projektoj uzantaj C-" +"etendaĵojn." + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" +"Multaj projektoj estas verkitaj sur Unikso, kaj subteni Windows povas esti " +"malfacile, ĉar starigado de taŭga Windows-testmedio estas malsimpla kaj " +"povas postuli aĉetadon de programaj licencoj." + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" +"La servo Appveyor estas servo por kontinua integrado simile al la pli bone " +"konata servo `Travis`_ ofte uzata por testado de projektoj sur `GitHub`_. " +"Tamen, malkiel Travis, la konstruaj procezoj sur Appveyor gastigas Windows " +"kaj havas taŭgajn tradukilojn por konstrui Python-etendaĵojn." + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" +"Uzantoj de Windows ofte ne havas C-tradukilon kaj tial dependas de la " +"distribuado de duumaj wheel-oj ĉe PyPI de projektoj uzantaj C-etendaĵojn por " +"instali la distribuon per ``python -m pip install ``. Uzante Appveyor " +"kiel konstruservon (eĉ se oni ne uzas ĝin por testado), oni povas disponigi " +"Windows-duumaĵojn sen dediĉita Windows-medio." + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +msgstr "Eki" + +#: ../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 "" +"Por uzi Appveyor por konstrui wheel por Windows por via projekto, oni devas " +"havi konton ĉe Appveyor. La `dokumentaro de Appveyor `__ priskribas instrukciojn por krei konton. La " +"senkosta konto sufiĉas por malfermitkoda projekto." + +#: ../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 integriĝas kun `GitHub`_ kaj `Bitbucket`_. Se via projekto estas " +"gastigata en unu el tiuj du servoj, ekstarigo de Appveyor facilas." + +#: ../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 "" +"Post starigo de konto ĉe Appveyor kaj agordado de la projekto, Appveyor " +"aŭtomate konstruos la projekton post ĉiu modifo. Tiu konduto similas al " +"Travis." + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "Aldoni subtenon por Appveyor al via projekto" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" +"Por difini la tielan manieron, kiel Appveyor konstruos vian projekton, oni " +"aldonu dosieron :file:`appveyor.yml` al via projekto. La plenaj detaloj pri " +"la dosiero troviĝas en la dokumentaro de Appveyor. Ĉi tiu gvidilo provizas " +"tiajn detalojn, kiaj necesas por konstrui wheel-on." + +#: ../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 "" +"Appveyor apriore inkluzivas ĉiujn tradulkilĉenojn necesajn por konstrui " +"etendaĵojn por Python. Por Python 2.7, 3.5+ kaj 32-bitaj versioj de 3.3 kaj " +"3.4, la iloj funkcias senmodife. Sed por 64-bitaj versioj de Python 3.3 kaj " +"3.4, oni devas iomete agordi por sciigi distutils pri la loko de la 64-bita " +"tradukilo. (Ekde versio 3.5, la uzata versio de Visual Studio inkluzivas 64-" +"bitan tradukilon sen plia agordo.)" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "appveyor.yml" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" +"Tiu dosiero estas elŝutebla `ĉi tie `__." + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" +"La dosiero :file:`appveyor.yml` devas situi en la radika dosiero de via " +"projekto. Ĝi estas en la dosierformo ``YAML`` kaj konsistas el kelkaj " +"sekcioj." + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" +"La sekcio ``environment`` gravas por difini tiujn versiojn de Python, por " +"kiuj wheel-oj kreiĝos. La Python-versioj 2.6, 2.7, 3.3, 3.4 kaj 3.5, en kaj " +"32-bitaj kaj 64-bitaj konstruoj, estas apriore instalitaj en Appveyor. La " +"ekzempla dosiero konstruas por ĉiuj el tiuj medioj krom Python 2.6. " +"Instalado por Python 2.6 estas pli komplika, ĉar pip ne estas apriore " +"inkluzivita. Ni ne subtenas 2.6 en ĉi tiu dokumento (uzanto de Windows " +"ankoraŭ uzanta Python 2 ordinare povas facile migri al Python 2.7)." + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" +"La sekcio ``build`` simple malŝaltas konstruadon – neniu konstrua paŝo " +"necesas por Python malkiel ekzemple ``C#``." + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" +"La ĉefaj sekcioj adaptendaj al via projekto estas ``test_script`` kaj " +"``after_test``." + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" +"La sekcio ``test_script`` estas la loko, kie oni rulas la testojn de la " +"projekto. La donita dosiero rulas la testaron per ``setup.py test``. Se oni " +"nur interesiĝas pri konstruado de wheel-oj kaj ne pri rulado de testoj sur " +"Windows, oni povas anstataŭigi tiun sekcion per neniaĵo kiel ``echo " +"Preterpasis Testojn``. Oni eble deziras uzi alian testilon kiel ``nose`` " +"aŭ :file:`py.test`. Aŭ oni deziras uzi testozorgilon kiel ``tox`` – tamen, " +"se oni uzas ``tox``, oni konsideru la ĉi-subajn pliajn ŝanĝojn pri agordoj." + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" +"La ``after_test`` ruliĝas post fino de la testoj; tial oni konstruas la " +"wheel tie. Supozante, ke via projekto uzas la rekomendatajn ilojn (specife " +"``setuptools``), do la komando ``setup.py bdist_wheel`` konstruos la wheel." + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" +"Notu, ke wheel konstruiĝos nur, se la testoj sukcesos. Se oni atendas " +"malsukceson de testoj sur Windows, oni povas preterpasi ilin laŭ la maniero " +"ĉi-supra." + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "Helpa programeto" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" +"La dosiero :file:`appveyor.yml` dependas de unu helpa programeto, kiu " +"agordas la medion por uzi la SDK-tradukilon por 64-bitaj konstruoj je Python " +"3.3 kaj 3.4. Tiuj projektoj, kiuj ne bezonas tradukilon aŭ ne subtenas 3.3 " +"aŭ 3.4 sur 64-bita Windows, nur bezonas la dosieron :file:`appveyor.yml`." + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" +"`build.cmd `__ estas programeto " +"por Windows rulanta unu komandon en medio kun la taŭga tradukilo por la " +"elektita versio de Python. Oni nur bezonas difini la median variablon " +"``DISTUTILS_USE_SDK`` kiel ``1``, kaj la programeto aŭtomatigas ĉion. Tio " +"starigas la SDK por 64-bita Python 3.3 or 3.4; tial ne difinu la median " +"variablon por alia konstruo." + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" +"Vi povas simple elŝuti la ``cmd``-dosieron kaj senŝanĝe inkluzivi ĝin en " +"vian projekton." + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "Aliro al la konstruitaj wheel-oj" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" +"Post fino de konstruado, la konstruitaj wheel-dosieroj estos haveblaj ĉe la " +"stirpanelo de Appveyor por via projekto. Ili troviĝas ĉe la konstruo-" +"statopaĝo por ĉiu konstruo. Ĉe la supro de la eligaĵo de la konstruo estas " +"hiperligoj, unu el kiuj estas «Artefaktoj». Tiu paĝo inkluzivas hiperligojn " +"al la wheel-oj por la Python-versio kaj arĥikteturo. Vi povas elŝuti tiujn " +"wheel-ojn kaj alŝuti ilin al PyPI dum via eldona procedo." + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "Testado per tox" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" +"Multaj projektoj uzas la ilon :doc:`Tox ` por testado. Tio " +"certigas, ke testoj ruliĝu en izolita medio uzante la ekzaktajn dosierojn " +"distribuotajn de la projekto." + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" +"Por uzi ``tox`` sur Appveyor, ekzistas kelkaj pliaj konsideroj (fakte tiaj " +"problemoj ne estas specifaj al Appveyor kaj povas ekzisti en aliaj sistemoj " +"de kontinua integrado)." + +#: ../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." +msgstr "" +"Apriore ``tox`` nur liveras subaron da mediaj variablojn al la testo-" +"procezoj. Ĉar ``distutils`` uzas mediajn variablojn por regi la tradukilon, " +"tia «testo-izolanta» funkcio kaŭzos miselektadon de tradukilo en testo." + +#: ../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 "" +"Por devigi ``tox`` pasi la necesajn mediajn variablojn al subprocezo, oni " +"devas agordi la opcion ``passenv`` de ``tox`` inkluzivante la necesajn " +"mediajn variablojn liverotajn al subprocezo. Por la SDK-tradukilo, oni uzas " +"la jenon:" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "``DISTUTILS_USE_SDK``" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "``MSSdk``" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "``INCLUDE``" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +msgstr "``LIB``" + +#: ../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." +msgstr "" +"La opcio ``passenv`` estas agordebla en :file:`tox.ini`, aŭ (se oni preferas " +"ne inkluzivi Windows-specifajn agordojn en ĝeneralaj projektaj dosieroj) per " +"la media variablo ``TOX_TESTENV_PASSENV``. La provizita " +"programeto :file:`build.cmd` faras tion implicite, se ``DISTUTILS_USE_SDK`` " +"ekzistas." + +#: ../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)." +msgstr "" +"Dum interaga uzado, `` tokso`` ebligas ruli testojn en pluraj medioj (ofte, " +"inkluzive de pluraj versioj de Python). Tiu funkcio ne tre utilas en medio " +"de kontinua integrado kiel Travis aŭ Appveyor, je kio ĉiuj testoj ruliĝas en " +"izolita medio por ĉiu agordo. Tial, projekto ofte donas argumenton ``-e " +"MEDIO`` al ``tox`` por specifi la uzotan medion (ekzistas aprioraj medioj " +"por la plejparto de versioj de Python)." + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" +"Tamen, tio *ne* funkcias bone kun sistemo de kontinua integrado por Windows, " +"kiel ekzemple Appveyor, en kiu ekzistas du instaloj de Python 3.4 (32-bita " +"kaj 64-bita), sed nur unu medio ``py34`` en ``tox``." + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" +"Por ruli testojn per ``tox``, tial, projekto uzu la aprioran medion ``py`` " +"en ``tox``, kiu uzas la Python-interpretilon interpretantan ``tox``. Tio " +"certigas, ke kiam Appveyor rulos testojn, ilin interpretos la agordita " +"interpretilo." + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" +"Por subteni ruladon en la medio ``py``, projekto de komplika agordo por " +"``tox`` eble devas modifi la dosieron :file:`tox.ini`. Tio, tamen, estas " +"ekster la temo de ĉi tiu dokumento." + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "Aŭtomate elŝuti wheel" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" +"Alternative, oni povas aldoni paŝon ``twine upload`` al la konstruo. La " +"donita dosiero :file:`appveyor.yml` ne faras tion, ĉar ne certas, ĉu oni " +"deziras alŝuti novan wheel post ĉiu enmeto (kvankam kelkaj projektoj fakte " +"deziras tion)." + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "Eksteraj dependecoj" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" +"La donitaj programetoj sukcese konstruos ĉian ajn distribuon ne dependantan " +"de triapartia ekstera biblioteko por la konstruado." + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "Helpaj programetoj" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "Por referenco, jen la SDK-stariga helpa programeto:" + +#: ../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 "Rekomendoj pri iloj" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" +"La Python-pakada pejzaĝo konsistas el multaj diversaj iloj. Por multaj " +"taskoj, la :term:`Python-Pakada Aŭtoritato ` (PyPA, la laborgrupo administranta multajn pakadajn ilojn kaj " +"mastrumas ĉi tiun gvidilon) intence ne faras ununuran rekomendon; ekzemple, " +"la kialo por pluraj konstruaj malfasadoj estas por malfermi la pejzaĝon, " +"ebligante la evoluadon de novaj malfasadoj por servi la bezonoj de kelkaj " +"uzantoj pli bone ol la unikinta malfasado setuptools. Ĉi tiu gvidilo ja " +"montras kelkajn ilojn vaste uzatajn kaj ankaŭ *mal*rekomendas kelkajn ilojn " +"evitindajn aŭ malsekurajn." + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "Virtualaj medioj" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" +"La normaj iloj por krei kaj uzi virtualan medion malaŭtomate " +"estas :ref:`virtualenv` (projekto de PyPA) kaj :doc:`venv ` (parto de la norma biblioteko de Python, sed sen kelkaj funkcioj de " +"virtualenv)." + +#: ../source/guides/tool-recommendations.rst:28 +msgid "Installing packages" +msgstr "Instali pakojn" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" +":ref:`Pip` estas la norma ilo por instali pakojn el :term:`PyPI `. Vi eble volas legi la rekomendojn de pip " +"pri :doc:`sekura instalado `. Pip estas havebla " +"apriore en multaj instaloj de Python per la norma biblioteka " +"pako :doc:`ensurepip `." + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" +"Alternative, konsideru :ref:`pipx` por la specifa uzkado de instalado de " +"Python-programo distribuata per PyPI kaj rulebla ĉe la komandlinio. Pipx " +"estas volvaĵo ĉirkaŭ pip kaj venv, kiu instalas programon en ĝian propran " +"virtualan medion. Tio avertas konfliktojn inter la dependecoj de diversaj " +"programoj kaj kun sistemaj programoj uzantaj la saman Python-interpretilon " +"(speciale sur Linux)." + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" +"Por sciencaj programoj specife, konsideru :ref:`Conda` aŭ :ref:`Spack`." + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "Verki komparon inter pip kaj Conda, ĉi tie aŭ en nova diskuto." + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" +"**Ne** uzu ``easy_install`` (parton de :ref:`setuptools`), kiun oni evitu, " +"preferante pip (vidu :ref:`pip kontraste al easy_install ` por detaloj). Simile, **ne** uzu ``python setup.py install`` " +"aŭ ``python setup.py develop``, kiuj estas ankaŭ evidintaj (vidu :ref:`setup-" +"py-deprecated` por fonaj informoj kaj :ref:`modernize-setup-py-project` por " +"konsiloj pri migrado)." + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "Serurdosieroj" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" +":ref:`pip-tools` kaj :ref:`Pipenv` estas du konataj iloj por krei " +"serurdosierojn, enhavantajn la ekzaktajn versiojn de ĉiuj pakoj instalitaj " +"en medion por reproduktebleco." + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "Konstruaj malfasadoj" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" +"Bonvolu konscii, ke ĉi tiu dokumento ne celas direkti la leganton al iu ilo; " +"ĝi nur celas listigi oftajn ilojn. Diversaj uzkazoj ofte bezonas specialajn " +"laborfluojn." + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" +"Jen popularaj :term:`konstruaj malfasadoj ` por pure Python-" +"aj pakoj, en alfabeta ordo:" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" +":doc:`Flit-core ` – evoluigata kun sed aparte " +"de :ref:`Flit`. Minimuma kaj opinihava konstrua malfasado. Ĝi ne subtenas " +"kromprogramon." + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" +"Hatchling_ – evoluigata kun sed aparte de :ref:`Hatch`. Subtenas " +"kromprogramojn." + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" +"PDM-backend_ – evoluigata kun sed aparte de :ref:`PDM`. Subtenas " +"kromprogramojn." + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" +"Poetry-core – evoluigata kun sed aparte de :ref:`Poetry`. Subtenas " +"kromprogramojn." + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" +"Malkiel aliaj malfasadoj en ĉi tiu listo, Poetry-core ne subtenas la " +"norman :ref:`tabelon [project] ` (ĝi uzas alian " +"formon, en la tabelo ``[tool.poetry]``)." + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" +":ref:`setuptools`, kiu iam estis la ununura konstrua malfasado. Subtenas " +"kromprogramojn." + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" +"Se vi uzas setuptools, atentu, ke kelkaj funkcioj estiĝintaj antaŭ normigado " +"estas nun evitindaj kaj nur *provizore ekzistantaj* pro kongrueco." + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" +"Specife, **ne** rekte uzu ``python setup.py``. Tamen, agordi setuptools per " +"dosiero :file:`setup.py` estas ankoraŭ plene subtenate, kvankam estas " +"rekomendate uzi la modernan :ref:`tabelon [project] en pyproject.toml " +"` (aŭ :file:`setup.cfg`) tiam ajn, kiam tio eblas, " +"kaj uzi :file:`setup.py` nur se oni bezonas programan agordadon. " +"Vidu :ref:`setup-py-deprecated`." + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" +"Jen aliaj evitindaj trajtoj, kiujn oni **ne** uzu: la argumento " +"``setup_requires`` de ``setup()`` (anstataŭe uzu :ref:`la tabelon [build-" +"system] ` en :file:`pyproject.toml`), " +"kaj la komando ``easy_install`` (vidu :ref:`pip vs easy_install`)." + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" +"**Ne** uzu :ref:`distutils`, kiu estas evitinda kaj forigita el la norma " +"biblioteko en Python 3.12, kvankam ĝi estas ankoraŭ disponebla per " +"setuptools." + +#: ../source/guides/tool-recommendations.rst:115 +#, fuzzy +#| msgid "Building binary extensions" +msgid "Build backends for extension modules" +msgstr "Konstrui duumajn etendaĵojn" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" +"Por pako kun :term:`etendaĵa modulo `, oni uzu " +"konstrusistemon subtenantan la lingvon de la etendaĵo. Ekzemple:" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" +":ref:`setuptools` -- indiĝene subtenas C kaj C++ (kun triapartiaj kromaĵoj " +"por Go kaj Rust)," + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" +":ref:`meson-python` -- C, C++, Fortrano, Rust, kaj aliaj lingvoj subtenataj " +"de Meson," + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" +":ref:`scikit-build-core` -- C, C++, Fortrano, kaj aliaj lingvoj subtenataj " +"de CMake," + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr ":ref:`maturin` -- Rust, per Cargo." + +#: ../source/guides/tool-recommendations.rst:128 +msgid "Building distributions" +msgstr "Konstrui distribuojn" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" +"La norma ilo por konstrui :term:`fontan distribuon ` kaj :term:`wheel ` alŝuteblajn al PyPI " +"estas :ref:`build`. Ĝi rulas la malfasadon :ref:`deklaritan ` en :file:`pyproject.toml`." + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" +"**Ne** uzu ``python setup.py sdist`` nek ``python setup.py bdist_wheel`` por " +"tiu tasko. Ĉia rekta alvoko de :file:`setup.py` estas :ref:`evitinda `." + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" +"Se vi havas :term:`etendaĵan modulo ` kaj volas distribui " +"wheel-ojn por pluraj platformoj, uzu :ref:`cibuildwheel` kiel parton de via " +"kontinua integrado por konstrui distribueblajn wheel-ojn." + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "Alŝuti al PyPI" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" +"Je la Novembro de 2024, PyPI subtenas la jenajn platformojn kiel " +"provizantojn de Fidata Eldonado:" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "GitHub Actions (ĉe ``https://github.com``)" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "GitLab CI/CD (ĉe ``https://gitlab.com``)" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "ActiveState" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "Google Cloud" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" +"La alia havebla metodo estas alŝuti la pakon malaŭtomate per :ref:`twine`." + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" +"**Neniam** uzu ``python setup.py upload`` por tiu tasko. Ĝi " +"estas :ref:`evitinda ` kaj malseksura." + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "Laborfluiloj" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr ":ref:`Flit`," + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr ":ref:`Hatch`," + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr ":doc:`nox `," + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr ":ref:`PDM`," + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr ":ref:`Pipenv`," + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr ":ref:`Poetry`," + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr ":doc:`tox `." + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "Inkluzivi dosierojn en fontajn distribuojn per ``MANIFEST.in``" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" +"La informoj sur ĉi tiu paĝo moviĝis al :doc:`setuptools:userguide/" +"miscellaneous` en la dokumentaro de setuptools." + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" +"Prova PyPI estasa aparta servilo de la :term:`Python-Pakindekso ` permesanta al vi elprovi la distribuadajn ilojn kaj " +"procezojn sen perturbado de la reala indekso. Prova PyPI troviĝas ĉe " +"`test.pypi.org `_" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "Registri vian konton" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" +"Ĉar Prova PyPI havas datenbankon apartan de la vera PyPI, oni bezonas " +"apartan konton specifan por Prova PyPI. Iru al https://test.pypi.org/account/" +"register/ por registri vin mem." + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" +"La datenbanko de la Prova PyPI estas periode reduktata; tial, konto de " +"uzanto ofte estas forigita." + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "Uzi TestPyPI kun Twine" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" +"Vi povas alŝuti viajn distribuojn al Prova PyPI per :ref:`twine` uzante la " +"flagon ``--repository``:" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" +"Vi povas kontroli, ĉu via pako estis sukcese alŝutita, vizitante la " +"retadreson ``https://test.pypi.org/project/``, en kiu " +"```` estas la nomo de via alŝutita projekto. Eblas, ke vi devas " +"atendi unu aŭ du minutojn." + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "Uzi TestPyPI kun pip" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" +"Vi povas igi :ref:`pip` elŝuti pakojn el Prova PyPI anstataŭ PyPI per la " +"flago ``--index-url``:" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" +"Se oni volas permesi al pip elŝuti pakojn el PyPI, oni specifas ``--extra-" +"index-url`` por montri PyPI. Tio utilas, se la testata pako havas " +"dependecojn:" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "Agordi TestPyPI en :file:`.pypirc`" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" +"Se vi volas eviti ĉiufoje tajpi viajn salutnomon kaj pasvorton, vi povas " +"agordi Provan PyPI en via :file:`$HOME/.pypirc`:" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "Verki vian ``pyproject.toml``" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" +"``pyproject.toml`` estas agorda dosiero uzata de iloj pri pakado kaj aliaj " +"iloj kiel sintakskontroliloj, tipkontroliloj ktp. Ekzistas tri eblaj TOML-" +"tabeloj en tiu dosiero." + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" +"La tabelo ``[build-system]`` estas **rekomendegata**. Ĝi permesas deklari " +"la :term:`konstruan malfasadon ` uzotan kaj la dependecojn " +"necesajn por konstrui la projekton." + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" +"La tabelo ``[project]`` estas la formo uzata de multaj konstruaj malfasadoj " +"por specifi la bazajn metadatenojn de la projekto, kiel la dependecojn, vian " +"nomon ktp." + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" +"La ilo ``[tool]`` havas ilo-specifajn subtabelojn kiel ``[tool.hatch]``, " +"``[tool.black]``, ``[tool.mypy]``. Ni nur mencias tiun tabelon, ĉar ĝiajn " +"enhavojn difinas iloj. Legu la dokumentaron de iu ilo por la enhavo de la " +"subtabelo." + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" +"La tabelo ``[build-system]`` ĉiam ĉeestu, por ĉia konstrua malfasado " +"(``[build-system]`` *difinas* la konstruilon uzatan)." + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" +"Aliflanke, la tabelo ``[project]`` estas konata de la *plejparto* de " +"konstruaj malfasadoj, sed kelkaj konstruaj malfasadoj uzas aliajn formojn." + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" +"Notinda escepto estas Poetry_, kiu antaŭ versio 2.0 (eldonita je la 5a de " +"Januaro 2025) ne uzis la tabelon ``[project]``. Anstataŭe ĝi uzis la tabelon " +"``[tool.poetry]``. Ekde versio 2.0, ĝi subtenas ambaŭ. Ankaŭ la konstrua " +"malfasado setuptools_ subtenas kaj la tabelon ``[project]`` kaj la malnovan " +"formon en ``setup.cfg`` aŭ ``setup.py``." + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" +"Por niva projekto, uzu la tabelo ``[project]``. Uzu ``setup.py`` nur se ia " +"programa agornado necesas (ekz. por konstrui C-etendaĵon). Tamen, la formoj " +"``setup.cfg`` kaj ``setup.py`` ankoraŭ validas. Vidu :ref:`setup-py-" +"deprecated`." + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "Deklari la konstruan malfasadon" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" +"La tabelo ``[build-system]`` enhavas ŝlosilon ``build-backend`` specifantan " +"la uzotan konstruan malfasadon. Ĝi ankaŭ enhavas ŝlosilon ``requires`` " +"listigantan dependecojn por konstrui la projekton – tio estas tipe nur la " +"pako de la konstrua malfasado,sed ĝi povas enhavi aliajn dependecojn. Vi " +"povas ankaŭ limigi la versiojn, ekzemple ``requires = [\"setuptools >= " +"61.0\"]``." + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" +"Ordinare oni simple kopias la sugestojn de la dokumentaro de la konstrua " +"malfasado (post after :ref:`elekto de la konstrua malfasado `). Jen la valoroj por oftaj konstruaj malfasadoj:" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "Statikaj kaj dinamikaj metadatenoj" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "La resto de ĉi tiu gvidilo temas pri la tabelo ``[project]``." + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" +"Plejparte, vi rekte skribas la valoron de kampo ``[project]``. Ekzemple: " +"``requires-python = \">= 3.8\"``, aŭ ``version = \"1.0\"``." + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" +"La konstrua malfasado respondecas por plenigi dinamikajn kampojn. Vidu la " +"dokumentaron de via konstrua malfasado por la preciza maniero de plenigado." + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "Bazaj informoj" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "``name``" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" +"Uzu la nomon de via projekto ĉe PyPI. Ĉi tiu kampo estas necesa kaj estas la " +"ununura kampo ne markebla kiel dinamika." + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" +"La projekta nomo devas konsisti el Askiaj literoj, ciferoj, substrekoj " +"«``_``», streketoj «``-``» kaj punktoj «``.``». Ĝi devas ne komenciĝi nek " +"finiĝi per substreko, streketo aŭ punkto." + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" +"Komparo de projektaj nomoj estas usklecblinda kaj ne distingas inter ajna " +"nombro da substrekoj, streketoj kaj/aŭ punktoj. Ekzemple, se vi registrus " +"projekton nomitan ``bonaj-ajhoj``, oni povus elŝuti ĝin aŭ deklari " +"dependecon sur ĝi per la jenaj nomoj: ``Bonaj-Ajhoj``, ``bonaj.ajhoj``, " +"``BONAJ_AJHOJ``, ``BoNaJ__-.-__aJhOJ``." + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "``version``" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "Enmetu la version de via projekto." + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" +"Eblas pli komplika versio-specifilo kiel ``2020.0.0a1`` (por alfa-eldono); " +"vidu la :ref:`specifon ` por plenaj detaloj." + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "Ĉi tiu kampo estas deviga, sed ĝi estas ofte markita dinamika per" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" +"Tio permesas uzkazon kiel generadon de version el atributo ``__version__`` " +"aŭ etikedo ĉe Git. Vidu la diskuton :ref:`single-source-version` por pliaj " +"detaloj." + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "Dependecoj kaj postuloj" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "``dependencies``/``optional-dependencies``" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "Se via projekto havas dependecojn, listigu ilin jene:" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" +"Vidu :ref:`Dependeco-specifilojn ` por la plena " +"sintakso por limigi versiojn." + +#: ../source/guides/writing-pyproject-toml.rst:161 +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 "" +"Oni eble volas laŭvoligi kelkajn dependecojn, se ili nur necesas por specifa " +"funkcio de la pako. Tiukaze, metu ilin en ``optional-dependencies``." + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" +"Ĉiu ŝlosilo difinas «pakan ekstraĵon». En la ĉi-supra ekzemplo, oni povus " +"uzi ekzemploe ``pip install nomo-de-via-projekto[gui]`` por instali vian " +"projekton kun subteno por grafika fasado, aldonante dependecon sur PyQt5." + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "``requires-python``" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" +"Tio ebligas deklari la minimuman version de Python subtenatan [#requires-" +"python-upper-bounds]_." + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "Krei ruleblajn komandojn" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" +"Por instali komandon kiel parton de via pako, deklaru ĝin en la tabelo " +"``[project.scripts]]``." + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" +"En ĉi tiu ekzemplo, instalado de la projekto disponigos la komandon ``spam-" +"cli``. Rulado de tiu komando ekvivalentas ``import sys; from spam import " +"main_cli; sys.exit(main_cli())``." + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" +"Sur Windows, programeto tiel pakita bezonus terminalon; tial, se oni lanĉus " +"ĝin el grafika programo, terminalo ŝprucus. Por malhelpi tion, uzu la " +"tabelon ``[project.gui-scripts]`` anstataŭ ``[project.scripts]``." + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" +"Tiukaze, lanĉado de via programo el la komandlinio tuj redonos regpovon al " +"vi, lastante la programon ruliĝi malfone." + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" +"La diferenco inter ``[project.scripts]`` kaj ``[project.gui-scripts]`` nur " +"gravas sur Windows." + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "Pri via projekto" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "``authors``/``maintainers``" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" +"Ambaŭ tiuj kampoj enhavas listojn de homoj identigitaj per nomoj kaj/aŭ " +"retpoŝtaj adresoj." + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "``description``" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" +"Tio estu unulinia priskribo de via projekto montrota kiel ka titolo de via " +"projekta paĝo ĉe PyPI (`jene `_), kaj interalie en listoj de " +"serĉrezultoj (`jene `_)." + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "``readme``" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" +"Tiu estas longa priskribo de via projekto montrota sur la projekta paĝo ĉe " +"PyPI. Ofte, oni simple metas la dosiernomon de dosiero ``README.md`` aŭ " +"``README.rst``." + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "La dosierformo de README estas aŭtomate divenita el la dosiersufikso:" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "``README.md`` → `GitHub-stila Markdown `_," + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "``README.rst`` → `reStructuredText `_ (sen etendaĵoj Sphinx)." + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "Vi povas ankaŭ eksplici la dosierformon jene:" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "``license`` kaj ``license-files``" + +#: ../source/guides/writing-pyproject-toml.rst:299 +#, fuzzy +#| msgid "As per :pep:`639` licenses should be declared with two fields:" +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "Laŭ :pep:`639`, oni deklaru licencon per du kampoj:" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" +"``license`` estas :term:`SPDX-licencesprimo ` " +"konsistanta el unu aŭ pluraj :term:`licencidentigiloj `." + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "``license-files`` estas listo de licencodosieraj ``glob``-patroneoj." + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" +"Antaŭa PEP specifis, ke ``license`` estu tabelo kun ŝlosilo ``file`` aŭ " +"``text``. Tiu formo estas nun evitinda. La plejparto de :term:`konstruaj " +"malfasadoj` nun subtenas la novan formon laŭ la jena tabelo." + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "versioj de konstruaj malfasadoj eksubtenantaj :pep:`639`" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "hatchling" + +#: ../source/guides/writing-pyproject-toml.rst:313 +msgid "setuptools" +msgstr "setuptools" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "flit-core [#flit-core-pep639]_" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "pdm-backend" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "poetry-core" + +#: ../source/guides/writing-pyproject-toml.rst:317 +#, fuzzy +#| msgid "build" +msgid "uv-build" +msgstr "build" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "1.27.0" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "77.0.3" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "3.12" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "2.4.0" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "``license``" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" +"La nova formo de ``licence`` estas valida :term:`SPDX-licenco-esprimo " +"` konstistanta el unu aŭ pluraj :term:`licenco-" +"identigiloj `. La plena listo de licencoj troviĝas ĉe " +"`la retejo de SPDX `_. La subtenataj versioj de la listo " +"estas 3.17 aŭ pli novaj." + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" +"Se oni ricevas konstrueraron, ke`license`` estu vortaro/tabelo, via konstrua " +"malfasado ankoraŭ ne subtenas la novan formon. Vidu la `ĉi-supran paragrafon " +"`_ por pli da kunteksto. La nun evitinda formo " +"estas `priskribita en PEP 621 `__." + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"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 "" +"Ĝenerale, estas bone uzi norman, bone konatan licencon, kaj por eviti " +"konfuziĝon, kaj ĉar kelkaj organizaĵoj evitas programon sen aprobita licenco." + +#: ../source/guides/writing-pyproject-toml.rst:353 +#, fuzzy +#| msgid "" +#| "If your project is licensed with a license that doesn't have an existing " +#| "SPDX identifier, you can create a custom one in format ``LicenseRef-" +#| "[idstring]``. The custom identifiers must follow the SPDX specification, " +#| "`clause 10.1 `_ of the version 2.2 or any later " +#| "compatible one." +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" +"Se via projekto havas licencon sen ekzistanta SPDX-identigilo, vi povas krei " +"propran identigilo de la formo ``LicenseRef-[identigilo]``. La propra " +"identigilo devas obei `paragrafon 10.1 `_ de la normo SPDX, " +"versio 2.2 aŭ ajna pli nova kongrua versio." + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "``license-files``" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" +"Tio estas listo de licenco-dosieroj kaj dosieroj enhavantaj aliajn jurajn " +"informojn, kiujn vi volas distribui kun via pako." + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "La patroneo devas observi la specifon:" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" +"Literoj, ciferoj, substrekoj (``_``), streketoj (``-``) kaj punktoj (``.``) " +"prezentas sin laŭlitere." + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "La metasignoj ``*``, ``?``, ``**`` kaj signintervaloj [] eblas." + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "Dosierloko-apartigilo devas esti la suprenstreko (``/``)." + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" +"Patroneo estas relativa al la dosierujo enhavanta :file:`pyproject.toml`, " +"kaj tial ne povas komenciĝi per suprenstreko." + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "Indikilo de patra dosierujo (``..``) devas esti ne uzita." + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "Ĉiu patroneo devas kongrui kun almenaŭ unu dosiero." + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" +"Eksplicita dosierloko estas valida patroneo. Ajna skribsigno aŭ signoĉeno ne " +"diskutita de ĉi tiu specifo estas nevalida." + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "``keywords``" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" +"Tio helpos la serĉilon de PyPI sugesti vian projekton, kiam oni serĉas tiujn " +"ŝlosilvortojn." + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "``classifiers``" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" +"Listo de PyPI-klasigiloj rilataj al via projekto. Jen la `plena listo de " +"klasigiloj `_." + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" +"Por malhelpi alŝuti pakon al PyPI, uzu la specialan klasigilon ``Private :: " +"Do Not Upload``. PyPI ĉiam malakceptas pakon de klasigilo komenciĝanta per " +"``Private ::``." + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "``urls``" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" +"Listo de retadresoj asociitaj al via projekto, montrotaj sur la maldekstra " +"flankpanelo de via projekta paĝo ĉe PyPI." + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" +"Vidu :ref:`well-known-labels` por listo de etikedoj bone konataj de PyPI kaj " +"aliaj pakiloj, kaj `la dokumentaron de PyPI pri projektaj metadatenoj " +"`_ por PyPI-specifa " +"pritraktado de retadresoj." + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" +"Notu, ke se la etikedo enhavas spacetojn, ĝi devas esti encitiligita, ekz. " +"``Website = \"https://example.com\"`` sed ``\"Official Website\" = \"https://" +"example.com\"``." + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" +"Uzanto uzu :ref:`bone konatajn etikedojn ` por projektaj " +"retadresoj taŭge, ĉar iloj pri metadatenoj (kiel pakindeksoj) povas pli bone " +"montri tiujn." + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" +"Ekzemple, en la jenaj metadatenoj, ne ``MyHomepage`` nek ``\"Download " +"Link\"`` estas bone konata etikedo kaj tial montriĝos laŭvorte:" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" +"Tamen en ĉi tiu metadateno, ambaŭ ``HomePage`` kaj ``DOWNLOAD`` ekvivalentas " +"bone konatajn etikedojn (``homepage`` kaj ``download``) kaj estas " +"prezenteblaj tiel (kiel la ĉefpaĝo kaj la elŝutejo de la projekto " +"respektive)." + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "Altnivelaj kromprogramoj" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" +"Kelkaj pakoj estas etendeblaj per kromprogramoj, ekzemple Pytest_ kaj " +"Pygments_. Por krei tian kromprogramon, oni devas deklari ĝin en subtabelo " +"de ``[project.entry-points]`` jene:" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" +"Vidu la :ref:`Gvidilon pri kromprogramoj ` por pliaj " +"informoj." + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "Plena ekzemplo" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" +"Estu singarda pri supraj limoj kiel ``requires-python = \"<= 3.10\"`` ĉi " +"tie. `Jen artikolo `_ pri eblaj problemoj." + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" +"flit-core `ankoraŭ ne `_ subtenas WITH en SPDX-" +"licencesprimoj." + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" +"La Manlibro por Python-Uzantoj pri Pakado (PyPUG) estas kolekto da lerniloj " +"kaj gvidiloj pri pakado de Python-programoj." + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "python, pakado, gvidilo, lernilo" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "Manlibro por Python-Uzantoj pri Pakado" + +#: ../source/index.rst:25 +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." +msgstr "" +"Bonvenon al *Manlibro por Python-Uzantoj pri Pakado*, kolekto de lerniloj " +"kaj gvidiloj por helpi vin distribui kaj instali Python-pakojn per modernaj " +"iloj." + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" +"Jen gvidilo mastrumata ĉe `GitHub`_ far :doc:`Python Packaging Authority " +"`. Ni dankeme akceptas :doc:`kontribuojn kaj komentojn " +"`. 😊" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "Superrigardo kaj Fluo" + +#: ../source/index.rst:40 +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." +msgstr "" +"Komprenado de pakado de Python estas vojaĝo. Pacienco kaj daŭra plibonigado " +"necesas por sukceso. La paragrafoj pri superrigardo kaj laborfluo estas " +"deirpunkto por kompreni la Python-pakadan ekosistemon." + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" +"Por superrigardo pri la laborfluo por eldoni kodon, vidu :doc:`pakadan fluon " +"`." + +#: ../source/index.rst:57 +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:" +msgstr "" +"Lernilo helpas vin paŝon post paŝo krei projekton kiel komencanto. Lerniloj " +"celas helpi vin sukcesi kaj provizi komencpunkton por plua esplorado. La " +"sekcio :doc:`tutorials/index` enhavas la jenon:" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr ":doc:`Lernilo pri instalado de pakoj `" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" +":doc:`Lernilo pri administrado de programaj dependecoj ` en versikontrolata projekto" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" +":doc:`Lernilo pri pakado kaj distribuado ` de " +"via projekto" + +#: ../source/index.rst:71 +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." +msgstr "" +"Gvidilo detalas paŝojn por iu tasko. Gvidilo estas por uzanto jam konanta " +"pakadon de Python kaj serĉas specifajn informojn." + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" +"La sekcio :doc:`guides/index` priskribas lernilajn instrukciojn pri tri " +"ĉeftemoj: instalado de pako; konstruado kaj distribuado de pako; aliaj temoj." + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "Klarigoj kaj Diskutoj" + +#: ../source/index.rst:82 +#, fuzzy +#| msgid "" +#| "The :doc:`discussions/index` section for in-depth explanations and " +#| "discussion about topics, such as:" +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" +"La sekcio :doc:`discussions/index` por detalaj klarigoj kaj diskutoj pri " +"temoj kiel:" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr ":doc:`discussions/deploying-python-applications`" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr ":doc:`discussions/pip-vs-easy-install`" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "Referenco" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" +"La paragrafo :doc:`specifications/index` por specifoj pri pakada " +"kunfunkcipovo." + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" +"La listo de :doc:`aliaj projektoj ` mastrumataj de anoj de la " +"Python-Pakada Aŭtoritato." + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" +"La :doc:`terminaro ` pri difinoj de terminoj pri pakado de Python." + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "Projektaj Resumoj" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" +"Resumoj kaj hiperligoj pri la plej gravaj projektoj rilataj al instalado kaj " +"pakado de Python." + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "Projektoj de PyPA" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "bandersnatch" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Dokumentaro `__ | `Cimoj `__ | `GitHub `__ | `PyPI `__" + +#: ../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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "build" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +":any:`Dokumentaro ` | `Cimoj `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" +"``build`` estas :pep:`517`-kongrua Python-pakokonstruilo. Ĝi provizas kaj " +"komandlinian fasadon kaj Python-API por konstrui pakojn." + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "cibuildwheel" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" +"`Dokumentaro `__ | `Cimoj `__ | `GitHub `__ | `PyPI `__ | " +"`Diskutoj `__ | `Discord " +"#cibuildwheel `__" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" +"``cibuildwheel`` estas Python-pako konstruanta :term:`wheel-ojn ` por " +"ĉiuj oftaj platformoj kaj versioj de Python sur multaj sistemoj de kontinua " +"integrado. Ankaŭ vidu :ref:`multibuild`." + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "distlib" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +":doc:`Dokumentaro ` | `Cimoj `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:73 +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." +msgstr "" +"``distlib`` estas biblioteko de malaltnivelaj funkcioj pri pakado kaj " +"distribuado de Python-programoj. ``distlib`` realigas plurajn rilatajn PEP-" +"ojn (normojn Python Enhancement Proposal) kaj utilas por verki triapartian " +"pakilon, kiu faras kaj alŝutas duumajn kaj fontajn :term:`distribuojn " +"` kunfunkcipove, solvas dependecojn, administras " +"pakajn resursojn, ktp." + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +msgstr "distutils" + +#: ../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 "" +"La origina Python-pakada sistemo, aldonita al la norma biblioteko en Python " +"2.0 kaj forigita en 3.12." + +#: ../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 "" + +#: ../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 "" +"Tial :ref:`distutils` iĝis evitinda ekde Python 3.10 per :pep:`632` kaj " +"estis :doc:`forigita ` el la norma biblioteko je " +"Python 3.12. Setuptools enhavas memstaran kopion de distutils kaj injektas " +"ĝin, eĉ por Python < 3.12, kiam oni unue importas setuptools aŭ uzas pip." + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "flit" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" +"`Dokumentaro `__ | `Cimoj `__ | `PyPI `__" + +#: ../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 estas simpla maniero por krei kaj alŝuti pakon aŭ modulon konsistantan " +"nur el Python al PyPI. Ĝi celas `faciligi facilaĵojn `_ pri " +"pakado. Flit povas generi agordan dosieron por rapide starigi simplan " +"projekton, konstrui fontajn distribuojn kaj wheel-ojn, kaj alŝuti ilin al " +"PyPI." + +#: ../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 uzas ``pyproject.toml`` por agordi projekton. Flit ne " +"uzas :ref:`setuptools` por konstrui distribuon, nek uzas :ref:`twine` por " +"alŝuti distribuojn al PyPI. Flit postulas Python 3, sed oni povas uzi ĝin " +"por distribui tiujn modulojn por Python 2, kiuj estas importeblaj en Python " +"3." + +#: ../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 "" +"La pako flit estas subtenata de `Matthias Bussonnier `__ ekde Oktobro 2023 sur la `platformo Tidelift `__, kun fonduso sendita al PSF kaj " +"markita por PyPA." + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "hatch" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Dokumentaro `__ | `GitHub `__ | `PyPI `__" + +#: ../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 estas unuigita komandlinia ilo por facile administri dependecojn kaj " +"izoli mediojn por Python-programistoj. Aŭtoroj de Python-pako uzas Hatch kaj " +"ĝian :term:`konstruan malfasadon ` por agordi pakojn, spuri " +"versiojn, specifi dependecojn, kaj eldoni pakojn al PyPI. La kromprograma " +"sistemo de Hatch faciligas etendado de ĝiaj funkcioj." + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "pakado" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +":doc:`Dokumentaro ` | `Cimoj `__ | `GitHub `__ | " +"`PyPI `__" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" +"Kernaj iloj por pakado de Python uzataj de :ref:`pip` kaj :ref:`setuptools`." + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "pip" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Dokumentaro `__ | `Cimoj `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" +"La plej populara ilo por instali Python-pakojn, inkluzivita en modernaj " +"versioj de Python." + +#: ../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 "" +"Ĝi provizas la necesajn ĉeffunkciojn por serĉi, elŝuti, kaj instali pakojn " +"el PyPI kaj aliaj Python-pakindeksoj kaj estas integrebla en multajn " +"evoluajn laborfluojn per la komandlinia fasado (CLI)." + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "Pipenv" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +msgstr "" +":doc:`Dokumentaro ` | `Fonto `__ | `Cimoj `__ | `PyPI " +"`__" + +#: ../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 estas projekto celanta provizi ĉiajn bonaĵojn al la mondo de Python. " +"Ĝi jungas :ref:`Pipfile`, :ref:`pip`, kaj :ref:`virtualenv` al unu ilĉenon. " +"Ĝi povas aŭtomate importi ``requirements.txt`` kaj kontroli vundeblecojn en " +"`Pipfile`_ per `safety `_." + +#: ../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 helpas uzantoj komandlinie administri mediojn, dependecojn kaj " +"importitajn pakojn. Ĝi ankaŭ funkcias bone sur Windows (malkiel kelkaj aliaj " +"iloj), faras kaj kontrolas haketaĵojn de dosieroj (por obei haketaĵe " +"ŝlositajn dependeco-specifilojn), kaj faciligas malinstaladon de pakoj kaj " +"dependaĵoj." + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "Pipfile" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "`Fonto `__" + +#: ../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` kaj ĝia frato :file:`Pipfile.lock` estas altnivela programo-" +"centra alternativo al la malaltnivela dosiero :file:`requirements.txt` " +"de :ref:`pip`." + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "pipx" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" +"`Dokumentaro `__ | `GitHub `__ | `PyPI `__" + +#: ../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 estas ilo por instali kaj ruli Python-an komandlinian programon sen " +"dependeca konflikto kun aliaj pakoj instalitaj sur la sistemo." + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" +":doc:`Dokumentaro ` | `Cimoj `__ | `GitHub `__" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "Jen ĉi tiu gividilo!" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "readme_renderer" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" +"`GitHub kaj dokumentaro `__ | " +"`PyPI `__" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "Setuptools" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Dokumentaro `__ | `Cimoj " +"`__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" +"Setuptools (kiu inkluzivas ``easy_install``) estas kolekto de plibonigaĵoj " +"por la modulo ``distutils`` de Python permesanta pli facile konstrui kaj " +"distribui :term:`distribuojn ` por Python, speciale " +"tiujn dependantajn de aliaj pakoj." + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "trove-classifiers" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" +"`Cimoj `__ | `GitHub " +"`__ | `PyPI `__" + +#: ../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 estas la norma fonto por `klasigiloj ĉe PyPI `_, kiujn mastrumantoj uzas por :ref:`sisteme " +"priskribi siajn projektojn `, helpante uzantojn " +"facile serĉi projektojn taŭgajn por siaj bezonoj ĉe PyPI." + +#: ../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 "" +"La pako ``trove-classifiers`` enhavas liston de validaj klasigiloj kaj " +"evitindaj klasigiloj (parigitaj kun la anstataŭantaj klasigiloj). Uzu tiun " +"pakon por konfirmi klasigilon en pako alŝutota al PyPI. Ĉar tiu listo de " +"klasigiloj estas kodo, oni povas instali kaj importi ĝin, por pli facila " +"laborfluo ol la `listo ĉe PyPI `_. La " +"`cimdatenbanko `_ de la " +"projekto gastigas diskutojn pri proponitaj klasigiloj kaj petoj por novaj " +"klasigiloj." + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "twine" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Dokumentaro `__ | `Cimoj `__ | `GitHub `__ | `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 estas la ĉefa ilo por alŝuti pakon al la Python-Pakindekso aŭ alia " +"pakindekso por Python. Ĝi estas komandlinia programo, kiu liveras " +"programdosierojn kaj metadatenojn al TTT-a API. Programistoj uzas ĝin, ĉar " +"ĝi estas la oficiala PyPI-alŝutilo, ĝi estas rapida kaj sekura, ĝi estas " +"mastrumata, kaj ĝi funkcias fidinde." + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "virtualenv" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Dokumentaro `__ | `Cimoj " +"`__ | `GitHub `__ | `PyPI `__" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "Warehouse" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" +"`Dokumentaro `__ | `Cimoj `__ | `GitHub `__" + +#: ../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 "" +"La aktuala programaro funkciiganta la :term:`Python-Pakindekson )`. Ĝi troviĝas ĉe `pypi.org `_. La " +"implicita fonto de elŝutado per :ref:`pip`." + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "wheel" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Dokumentaro `__ | `Cimoj `__ | `GitHub `__ | `PyPI `__" + +#: ../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 "" +"Precipe, la projekto wheel provizas la :ref:`setuptools`-etendaĵon " +"``bdist_wheel`` por krei :term:`wheel-distribuon `. Krome, ĝi " +"provizas komandlinian ilaĵon por krei kaj instali wheel-on." + +#: ../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 "" +"Vidu ankaŭ `auditwheel `__, kiu estas " +"ilo por kontroli kaj ripari Python-pakon en la duuma formo wheel. Ĝi povas " +"malkovri dependecojn, kontroli la observecon de metadatenoj, kaj ripari la " +"wheel kaj metadatenojn, ligante kaj inkluzivante eksterajn komunajn " +"bibliotekojn en pakon." + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "Projektoj ekster PyPA" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "buildout" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" +"`Dokumentaro `__ | `Cimoj `__ | `PyPI `__ | `GitHub `__" + +#: ../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 "" +"Buildout estas Python-baza konstrusistemo por krei, kombini kaj disponigi " +"programon el pluraj partoj, eble ne-Python-bazaj. Verkinte agordon por " +"buildout, oni povas reprodukti la saman programon poste." + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "conda" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr ":doc:`Dokumentaro `" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" +"Conda estas pako-, dependaĵo- kaj medio-administra sistemo por ajna lingvo – " +"Python, R, Ruby, C/C++, Fortrano ktp. Ĝi estas verkita en Python kaj vaste " +"uzata de la scienckomputa komunumo de Python, pro ĝia subteno de ne-Python-" +"aj tradukitaj bibliotekoj kaj etendaĵoj. Ĝi estas uzata kiel la bazo de la " +"Python-distribuo `Anaconda `__ de " +"Anaconda, Inc. Ĝi origine celis la sciencan komunumon, sed ankaŭ estas " +"uzebla memstare aŭ kun la sistemoj :doc:`miniconda `, " +"`miniforge `_ aŭ `pixi `_. Ĝi estas havebla por Windows, Mac kaj Linux." + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" +"Conda estas komplete aparta de :ref:`pip`, virtualenv kaj wheel, sed " +"provizas multajn el la funkcioj de tiuj, kiel administradon de pakoj, " +"administradon de virtualaj medioj kaj disponigadon de duumaj etendaĵoj kaj " +"alia duuma kodo." + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" +"Conda ne instalas pakojn el PyPI – ĝi povas nur administri pakojn specife " +"por conda, disponeblajn ĉe «conda-kanalo», kiel tiujn sur `anaconda.org " +"`__, aŭ ĉe loka (ekz. intrareta) pakservilo. Krom la " +"«aprioraj» kanaloj administrataj de `Anaconda, Inc. `__, ekzistas multaj pakoj en la komunume subtenata " +"`projekto conda-forge `__" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" +"Notu, ke oni povas instali :ref:`pip` en conda, funkciigante ĝin apud conda " +"por administri :term:`distribuojn ` el PyPI. Oni ankaŭ " +"povas konstrui conda-pakon el Python-fontpako per ilo kiel `conda skeleton " +"`__, kiu aŭtomate faras conda-pakon el Python-pako " +"ĉe PyPI." + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "devpi" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" +"`Dokumentaro `__ | :gh:`Issues ` | `PyPI `__" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "dumb-pypi" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" +"`GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:457 +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 estas simpla :term:`pakindeksa ` statikdosiera " +"retejogenerilo, kies generitaj dosieroj devas esti gastigitaj de servilo de " +"statikaj dosieroj por funkcii kiel pakindekso. Ĝi subtenas haketaĵojn, " +"kernajn metadatenojn, kaj fortiritecon." + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "enscons" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" +":gh:`Fonto ` | :gh:`Cimoj ` | `PyPI " +"`__" + +#: ../source/key_projects.rst:470 +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 estas pakilo por Python surbaze de `SCons`_. Ĝi konstruas fontajn " +"distribuojn kaj wheel-ojn kongruajn kun :ref:`pip` sen uzado de distutils aŭ " +"setuptools, eĉ por distribuoj kun C-etendaĵoj. La arĥitekturo kaj filozofio " +"de Enscons diferencas de :ref:`distutils`. Anstataŭ aldoni funkcion por " +"konstruado al Python-pakada sistemo, enscons aldonas Python-specifajn " +"funkciojn al ĝeneralcela konstrusistemo. Enscons helpas konstrui fontan " +"distribuon aŭtomate konstrueblan per :ref:`pip` kaj wheel-on sendependan de " +"enscons." + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "Flask-Pypi-Proxy" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" +"`Dokumentaro `__ | :gh:`GitHub " +"` | `PyPI `__" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "Ne mastrumata, projekto enarĥivigita" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" +"Flask-Pypi-Proxy estas :term:`pakindekso `, kiu estas " +"kaŝmemora perilo por PyPI." + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "Hashdist" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" +"`Dokumentaro `__ | `GitHub " +"`__" + +#: ../source/key_projects.rst:504 +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 estas biblioteko por konstrui neradikan programan distribuon. " +"Hashdist celas esti «la Debiano por tiuj kazoj, en kiuj Debiano ne taŭgas». " +"Python-uzanto pensu pri Hashdist kiel potenca hibrido de :ref:`virtualenv` " +"kaj :ref:`buildout`. Ĝi celas solvi la problemon de instalado de scienca " +"programo kaj igi distribuadon de pakoj senstata, enkaŝmemorigita kaj " +"branĉebla. Ĝi estas uzata de kelkaj esploristoj, sed ne estas prizorgata " +"ekde 2016." + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "Maturin" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" +"`Dokumentaro `__ | `GitHub `__" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" +"Maturin estas konstrua malfasado por etendaĵo-modulo verkita en Rust, kaj " +"estas mem verkita en Rust. Ĝi subtenas konstrui wheel por Python 3.7+ sur " +"Windows, Linux, macOS kaj FreeBSD. Ĝi povas alŝuti wheel al PyPI kaj ankaŭ " +"baze subtenas PyPY kaj GraalPy." + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "meson-python" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" +"`Dokumentaro `__ | `GitHub " +"`__" + +#: ../source/key_projects.rst:534 +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`` estas konstrua malfasado uzanta la konstrusistemon Meson_. " +"Ĝi permesas al aŭtoroj de Python-pakoj uzi Meson_ kiel la konstrusistemon de " +"sia pako. Ĝi subtenas diversajn lingvojn inkluzive de C kaj povas plenumi la " +"bezonojn de plej komplikaj konstruagordoj." + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "multibuild" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "`GitHub `__" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" +"Multibuild estas kontinuintegrada programaro por konstrui kaj testi " +"Python-:term:`wheel ` por Linux, macOS, kaj (malpli flekseble) " +"Windows. Ankaŭ vidu :ref:`cibuildwheel`." + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "nginx_pypi_cache" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr ":gh:`GitHub `" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" +"nginx_pypi_cache estas :term:`pakindeksa ` kaŝmemora perilo " +"per `nginx `_." + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "pdm" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Dokumentaro `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" +"PDM estas moderna Python-pakadministrilo. Ĝi uzas :term:`pyproject.toml` por " +"konservi projektajn metadatenojn laŭ :pep:`621`." + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Dokumentaro `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:582 +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 estas ilo por generi :file:`.pex` (Python EXecutable)-dosierojn, kiuj " +"estas memstaraj Python-medioj similaj al :ref:`virtualenv`. PEX-dosiero " +"estas :doc:`zipapp `, igante disponigon de Python-" +"programo tiel simpla kiel ``cp``. Unu PEX-dosiero povas subteni plurajn " +"celajn platformojn kaj estas kreebla el normaj :ref:`pip`-solveblaj " +"postuloj, lockfile generita per ``pex3 lock …`` aŭ eĉ alia PEX. PEX-dosiero " +"ankaŭ povas havi inkluzivitajn ilojn estigante la PEX-dosieron ordinara " +"virtuala medio, grafigi dependecojn, ktp." + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "pip-tools" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Dokumentaro `__ | `GitHub " +"`__ | `PyPI `__" + +#: ../source/key_projects.rst:600 +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." +msgstr "" +"pip-tools estas ilaro por tiuj sistemadministrantoj kaj eldonmastrumistoj de " +"Python, kiuj volas determinisman konstruadon kaj ĝisdatajn versiojn de " +"dependecoj. Uzanto povas specifi iun eldono de dependeco per haketaĵo, " +"facile fari liston de postuloj el informoj en aliaj partoj de la programo, " +"ĝisdatigi ĉiujn dependecojn (jen funkcio mankanta en :ref:`pip` aktuale), " +"kaj krei tavolojn da limigoj obeotaj de la programo." + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "pip2pi" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +":gh:`GitHub ` | `PyPI `__" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" +"pip2pi estas :term:`pakindeksa ` servilo, je kiu specifaj " +"pakoj estas malaŭtomate sinkronigitaj." + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "piwheels" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" +"`Retejo `__ | :doc:`Dokumentaro ` " +"| `GitHub `__" + +#: ../source/key_projects.rst:629 +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 "" +"piwheels estas retejo, kaj programo funkciiganta la retejon, kiu elŝutas " +"fontajn distribuajn pakojn el PyPI kaj tradukas ilin al duumaj wheel-oj " +"optimumigitaj por komputiloj Raspberry Pi. La mastruma sistemo Raspberry Pi " +"OS apriore agordas pip por uzi piwheels.org kiel ekstran indekson kune kun " +"PyPI." + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "poetry" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Dokumentaro `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:644 +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." +msgstr "" +"poezio estas komandlinia ilo por instali dependecojn kaj por izoli, kaj " +"ankaŭ por konstrui kaj paki Python-pakojn. Ĝi uzas ``pyproject.toml`` kaj " +"(ne uzante la solvilon de :ref:`pip`) provizas sian propran dependeco-" +"solvilon. Ĝi provas rapidigi la sperton de uzantoj pri instalado kaj solvado " +"de dependecoj, loke enkaŝmemorigante metadatenojn pri dependecoj." + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "proxpi" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +":gh:`GitHub ` | `PyPI `__" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" +"proxpi estas simpla :term:`pakindekso `, kiu peras PyPI kaj " +"aliajn indeksojn kun kaŝmemoro." + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "Pulp-python" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" +"`Dokumentaro `__ | :gh:`GitHub " +"` | `PyPI `__" + +#: ../source/key_projects.rst:671 +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." +msgstr "" +"Pulp-python estas la Python-a :term:`pakindeksa ` " +"kromprogramo por `Pulp `_. Pulp-python subtenas " +"spegulon bazitan sur lokaj dosieroj aŭ `AWS S3`_, alŝutadon de pakoj, kaj " +"peradon al pluraj pakindeksoj." + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "PyPI Cloud" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" +"`Dokumentaro `__ | :gh:`GitHub ` | `PyPI `__" + +#: ../source/key_projects.rst:687 +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." +msgstr "" +"PyPI Cloud estas :term:`pakindeksa ` servilo uzanta `AWS S3`_ " +"aŭ alian nubkonservejan servon aŭ lokajn dosierojn. PyPI Cloud subtenas " +"redirektadon kaj kaŝmemoran peradon al PyPI, aŭtentikigon kaj rajtigon." + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "pypiprivate" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +":gh:`GitHub ` | `PyPI `__" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" +"pypiprivate serves lokan (aŭ ĉe `AWS S3`_ gastigitan) dosierujon da pakoj " +"kiel :term:`pakindekso `." + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "pypiserver" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" +"`GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:711 +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." +msgstr "" +"pypiserver estas minimumisma programo servanta privantan :term:`Python-" +"pakindekson ` (el loka dosierujo) por organizaĵo, realiganta " +"simplan API kaj TTT-legilan fasadon. Oni povas alŝuti privatan pakon per " +"norma alŝutilo, uzanto povas elŝuti kaj instali pakon per :ref:`pip`, sen " +"publika eldonado. Organizaĵo uzanta pypiserver kutime elŝutas pakojn el kaj " +"pypiserver kaj PyPI." + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "PyScaffold" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Dokumentaro `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "pywharf" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +":gh:`GitHub ` | `PyPI `__" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" +"pywharf estas :term:`pakindeksa ` servilo, servanta dosierojn " +"loke aŭ el `GitHub `_." + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "scikit-build" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Dokumentaro `__ | `GitHub " +"`__ | `PyPI `__" + +#: ../source/key_projects.rst:758 +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 estas volvilo de :ref:`setuptools` por CPython konstruanta C/C+" +"+/Fortran/Cython-etendaĵojn. Ĝi uzas `cmake `__ (haveblan ĉe PyPI) por pli bone subteni pliajn tradukilojn, " +"konstrusistemojn, intertradukadon, kaj lokigado de dependecoj kaj rilataj " +"konstruo-postuloj. Por rapidigi kaj paraleligi konstruadon de granda " +"projekto, oni povas instali `ninja `__ " +"(ankaŭ haveblan ĉe PyPI)." + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "scikit-build-core" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" +"`Dokumentaro `__ | " +"`GitHub `__ | `PyPI " +"`__" + +#: ../source/key_projects.rst:775 +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." +msgstr "" +"Scikit-build-core estas konstrua malfasado por etendaĵoj por CPython en C/C+" +"+/Fortran/Cython. Ĝi permesas verki etendaĵojn per `cmake `__ (havebla ĉe PyPI) por pli bone subteni pliajn tradukilojn, " +"konstrusistemojn, intertradukadon, kaj serĉadon de dependecoj kaj asociitaj " +"konstruaj postuloj. Ĝi aŭtomate elŝutos CMake/Ninja el PyPI, se ili ne jam " +"ekzistas sur la sistemo." + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "shiv" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Dokumentaro `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:791 +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." +msgstr "" +"shiv estas komandlinia ilo por konstrui plene memsufiĉa Python-zip-aplikaĵo " +"laŭ :pep:`441`, sed inkluzivante ĉiajn dependaĵojn. Ĝi ĉefe celas rapidigi " +"kaj faciligi distribuadon de Python-programoj kaj komandliniaj iloj." + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "simpleindex" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +":gh:`GitHub ` | `PyPI `__" + +#: ../source/key_projects.rst:804 +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." +msgstr "" +"simpleindex estas :term:`pakindekso `, kiu enkursigas " +"retadresojn al pluaj pakindeksoj (inkluzive de PyPI), disponigas lokajn (aŭ " +"nube gastigitajn, ekzemple ĉe `AWS S3`_, per kromprogramo) dosierujojn de " +"pakoj, kaj subtenas kromprogramojn." + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" +":doc:`Dokumentaro ` | `GitHub `__ | `Artikolo `__ | `Lumbildoj `__" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" +"Spack ne estas en PyPI (ankoraŭ), sed ĝi postulas neniun instaladon kaj " +"estas uzebla tuj post klonado el GitHub." + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "zest.releaser" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Dokumentaro `__ | `GitHub " +"`__ | `PyPI `__" + +#: ../source/key_projects.rst:839 +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." +msgstr "" +"``zest.releaser`` estas Python-paka eldonilo, kiu estas abstrakta tavolo " +"sur :ref:`twine`. Python-programisto uzas ``zest.releaser`` por aŭtomatigi " +"alkrementadon de versiaj numeroj, ĝisdatigadon de ŝanĝoprotokolo, etikedigon " +"de eldonoj en versikontrola sistemo, kaj alŝutadon de nova pako al PyPI." + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "Projektoj pri la Norma Biblioteko" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "ensurepip" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" +"`Dokumentaro `__ | `Cimoj " +"`__" + +#: ../source/key_projects.rst:856 +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." +msgstr "" +"Pako en la Norma Biblioteko de Python, kiu ebligas instaladon de :ref:`pip` " +"al ekzistanta Python-instalo aŭ virtuala medio. Ordinare uzanto ne rekte " +"uzas tiun modulon; ĝi estas uzata dum la konstruado de la Python-distribuo." + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "http.server" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" +":doc:`Dokumentaro ` | :gh:`Cimoj `" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" +"Pako kaj komandlinia interfaco, kiu gastigas dosierujon al retejo, ekzemple " +"kiel :term:`pakindekson ` (vidu :ref:`Gastigi vian Propran " +"Simplan Deponejon `)." + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "venv" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" +"`Dokumentaro `__ | `Cimoj " +"`__" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" +"Pako en la Norma Biblioteko de Python (ekde Python 3.3) por " +"krei :term:`Virtualan Medion `. Por pli da informoj, " +"vidu la paragrafon :ref:`Krei kaj uzi virtualajn mediojn `." + +#: ../source/news.rst:2 +msgid "News" +msgstr "Novaĵoj" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" +"Ĉi tiu dokumento estas ne plu ĝisdatigata. Antaŭe, ĝi reliefigis ŝanĝojn pri " +"Python-pakado." + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "Septembro 2019" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" +"Aldonis gvidilon pri eldonado de distribuoj per GitHub Actions. (:pr:`647`)" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "Aŭgusto 2019" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "Ekuzis :file:`python3 -m` dum instalado de pipx. (:pr:`631`)" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "Julio 2019" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "Markis ĉiujn PEP-numerojn per la rolo :pep:. (:pr:`629`)" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" +"Ĝisdatigis version de Sphinx kaj forigis pypa.io intersphinx. (:pr:`625`)" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "Menciis :file:`find_namespace_packages`. (:pr:`622`)" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "Ĝisdatigis ekzemplojn de dosieruja aranĝo por unuformeco. (:pr:`611`)" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "Ĝisdatigis la hiperligon por Bandersnatch al GitHub. (:pr:`623`)" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "Junio 2019" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "Riparis tajperarojn. (:pr:`620`)" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "Majo 2019" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" +"Klarigis uzadon de :file:`python_requires` en lernilo pri pakado. (:pr:`613`)" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "Aldonis gvidan paĝon pri MANIFEST.in. (:pr:`609`)" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "Aprilo 2019" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "Menciis :file:`shiv` en la listo de ĉefprojektoj. (:pr:`608`)" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "Malemfazis virtualenv. (:pr:`606`)" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "Marto 2019" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" +"Ĝisdatigis opcion en gvidilo pri unufontigo de versio al Python 3. " +"(:pr:`605`)" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "Diskutis RTD-detalojn por kontribuado. (:pr:`600`)" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "Februaro 2019" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" +"Klarigis la diferencojn inter la lernilo kaj la reala pakada procezo. " +"(:pr:`602`)" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" +"Aldonis instrukciojn por instali komandlinian Python-programojn. (:pr:`594`)" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "Januaro 2019" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "Aldonis :file:`--no-deps` al la pakada lernilo. (:pr:`593`)" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "Ĝisdatigis Sphinx kaj Nox. (:pr:`591`)" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "Menciis Twine el Python3. (:pr:`581`)" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "Decembro 2018" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "Neniu programisto en la oficejo!" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "Novembro 2018" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "Forigis ĉefpaĝan hiperligon al migrada gvidilo por PyPI. (:pr:`575`)" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "Ŝanĝis bumpversion al bump2version. (:pr:`572`)" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "Aldonis ekzemplon pri unufontigo de la paka versio. (:pr:`573`)" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "Aldonis gvidilon por verki dokumentaron. (:pr:`568`)" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "Oktobro 2018" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "Ĝisdatigis paknomon de Nox. (:pr:`566`)" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "Menciis Sphinx-etendaĵojn en gvidiloj. (:pr:`562`)" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "Septembro 2018" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" +"Aldonis paragrafon pri kontrolado de reStructuredText-sintakso (:pr:`554`)" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "Ĝisdatigis paĝon pri instalado al la loko de la uzanto. (:pr:`558`)" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "Ĝisdatigis retadresojn de Google BigQuery. (:pr:`556`)" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "Anstataŭigis komandon tar per funkcianta komando. (:pr:`552`)" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "Ŝanĝis al duoblaj citiloj en pip install SomeProject==1.4. (:pr:`550`)" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "Aŭgusto 2018" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "Forigis la rekomendon konservi pasvortojn senĉifre. (:pr:`546`)" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" +"Provizis la Superrigardon kun taskobaza enkonduko simile al aliaj " +"dokumentoj. (:pr:`540`)" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "Ĝisdatigis Python-version subtenatan de virtualenv. (:pr:`538`)" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "Aldonis malneton de nova Superrigarda paĝo. (:pr:`519`)" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "Julio 2018" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "Plibonigis dokumentaron pri duumaj etendaĵoj. (:pr:`531`)" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "Aldonis scikit-build al ĉefprojektoj. (:pr:`530`)" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "Junio 2018" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "Riparis kategoriojn pri kunfunkcipova PEP por pypa.io. (:pr:`527`)" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "Ĝisdatigis klarigon pri priskriboj en Markdown. (:pr:`522`)" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "Majo 2018" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "Menciis problemojn pri Provides-Dist kaj Obsoletes-Dist. (:pr:`513`)" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" +"Forigis ne plu validan averton pri miksado de Python-versioj kun Pipenv. " +"(:pr:`501`)" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "Simpligis lernilon pri pakado. (:pr:`498`)" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "Pliklarigis instrukciojn por uzantoj de Windows. (:pr:`493`)" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "Ĝisdatigis la priskribon de la licenca sekcio por pleneco. (:pr:`492`)" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" +"Aldonis specifo-stilan dokumenton al la paragrafo pri kontribuado. " +"(:pr:`489`)" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" +"Aldonis specojn de dokumentoj al gvidilo por kontribuantoj. (:pr:`485`)" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "Aprilo 2018" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "Aldonis gvidilon pri README. (:pr:`461`)" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "Ĝisdatigis instrukciojn kaj staton por la lanĉo de PyPI. (:pr:`475`)" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "Aldonis instrukciojn pri Warehouse. (:pr:`471`)" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "Forigis referencojn al GPG el la lernilo pri eldonado. (:pr:`466`)" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "Aldonis «Kio estas en kiu Python 3.4–3.6?». (:pr:`468`)" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "Aldonis gvidilon pri ekmalsubtenado de versioj de Python. (:pr:`459`)" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "Implicitigi la varianton GFM por Description-Content-Type. (:pr:`462`)" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "Marto 2018" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "Ĝisdatigis «Instali sciencajn pakojn». (:pr:`455`)" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" +"Aldonis :file:`long_description_content_type` sekvante PEP 556. (:pr:`457`)" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "Klarigis longan priskriban klasigilon ĉe pypi.org. (:pr:`456`)" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" +"Ĝisdatigis la specifon de Kernaj Metadatenoj sekvante PEP 556. (:pr:`412`)" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "Februaro 2018" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" +"Aldonis python3-venv kaj python3-pip al instrukcioj pri instalado sur " +"Debian. (:pr:`445`)" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "Ĝisdatigis informojn pri migrado al PyPI. (:pr:`439`)" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" +"Aldonis averton pri administrado de pluraj versioj per pipenv. (:pr:`430`)" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" +"Aldonis ekzemplon de pluraj retpoŝtaj adresoj al Kernaj Metadatenoj. " +"(:pr:`429`)" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "Klarigis «legacy» en test.pypi.org/legacy. (:pr:`426`)" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "Januaro 2018" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "Aldonis hiperligon al la listo de klasigiloj ĉe PyPI. (:pr:`425`)" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "Plibonigis klarigon pri README.rst. (:pr:`419`)" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "Decembro 2017" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" +"Anstataŭigis :file:`~` per :file:`$HOME` en gvidiloj kaj lerniloj. " +"(:pr:`418`)" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" +"Notis tiujn kampojn, kiuj povas esti uzataj kun mediaj markoj. (:pr:`416`)" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "Plibonigis paragrafon pri Requres-Python. (:pr:`414`)" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "Aldonis paĝon pri novaĵoj. (:pr:`404`)" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "Novembro 2017" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" +"Enkondukis novan lernilon pri mastrumado de dependeco per Pipenv. (:pr:`402`)" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" +"Ĝisdatigis la lernilon *Unu-Fontigi la Pakan Version* laŭ la aktuala " +"strategio de pip. (:pr:`400`)" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" +"Aldonis klarigon pri la argumento ``py_modules`` al ``setup``. (:pr:`398`)" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "Simpligis la paragrafon pri :file:`manifest.in`. (:pr:`395`)" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "Oktobro 2017" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "Aldonis specifon pri la dosiero :file:`entry_points.txt`. (:pr:`398`)" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" +"Verkis novan gvidilon por administri pakojn per ``pip`` kaj ``virtualenv``. " +"(:pr:`385`)" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "Disdividis la paĝon de specifoj en plurajn paĝojn. (:pr:`386`)" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "Septembro 2017" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" +"Instigis uzi ``readme_renderer`` por kontroli la validecon " +"de :file:`README.rst`. (:pr:`379`)" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "Rekomendis uzi la opcion ``--user-base``. (:pr:`374`)" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "Aŭgusto 2017" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" +"Aldonis novan, eksperimentan lernilon pri instalado de pako per ``Pipenv``. " +"(:pr:`369`)" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "Aldonis novan gvidilo pri la uzado de ``TestPyPI``. (:pr:`366`)" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "Aldonis :file:`pypi.org` kiel terminon. (:pr:`365`)" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "Julio 2017" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "Inkluzivis ``flit`` en la liston de ĉefprojektojn. (:pr:`358`)" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "Inkluzivis ``enscons`` en la liston de ĉefprojektojn. (:pr:`357`)" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" +"Ĝisdatigis la ``readme`` de ĉi tiu gvidilo per instrukcioj pri kiel konstrui " +"la gvidilon loke. (:pr:`356`)" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" +"Reliefigis la novan retadreson ``TestPyPI``, aldonante noton pri pypi.org. " +"(:pr:`354`)" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" +"Aldonis noton pri la forigo de la API de eksplicita registrado. (:pr:`347`)" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "Junio 2017" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" +"Aldonis dokumenton pri migrado de alŝutoj al :file:`PyPI.org`. (:pr:`339`)" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "Aldonis dokumentaron pri ``python_requires``. (:pr:`338`)" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" +"Aldonis noton pri migrado de PyPI en la lernilo *Rekomendoj pri Iloj*. " +"(:pr:`335`)" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "Notis, ke :file:`manifest.in` ne rilatas al wheel. (:pr:`332`)" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" +"Aldonis paragrafon pri licencoj al la gvidilo pri distribuado. (:pr:`331`)" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "Pliigis la paragrafon pri la argumento ``name``. (:pr:`329`)" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "Plibonigis la ĉefpaĝon. (:pr:`327`, :pr:`326`, :pr:`324`)" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "Ĝisdatigis al Sphinx 1.6.2. (:pr:`323`)" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "Ŝanĝis al la etoso de PyPA. (:pr:`305`)" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "Reorganizis la dokumentaron laŭ la nova strukturo. (:pr:`318`)" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "Majo 2017" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "Klarigis la kampon ``Description-Content-Type``. (:pr:`258`)" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "Aldonis gvidilojn por kontribuantoj kaj pri stilo. (:pr:`307`)" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" +"Dokumentis la diferencojn inter ``pip`` kaj ``easy_install`` pri unu-" +"projektaj indeksoj. (:pr:`233`)" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "Aprilo 2017" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "Starigis agordojn pri travis por testi tirpetojn. (:pr:`300`)" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "Menciis la postulon de la pako ``wheel`` por krei wheel (:pr:`299`)" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" +"Forigis la mencion de ``twine register`` en la lernilo *Distribui Pakojn*. " +"(:pr:`271`)" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "Aldonis temon pri malkovrado de kromaĵoj. (:pr:`294`, :pr:`296`)" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "Aldonis temon pri nomspacaj pakoj. (:pr:`290`)" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" +"Aldonis dokumentaron reliefigante kiel instali ``pip`` en ``/usr/local``. " +"(:pr:`230`)" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" +"Ĝisdatigis la dokumentaron pri evoluada reĝimo menciante, ke la ordo de " +"lokaj pakoj gravas. (:pr:`208`)" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" +"Konverti ligilojn al readthedocs por la migrado ``.org`` → ``.io`` pri " +"gastigitaj projektoj (:pr:`239`)" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" +"Ŝanĝis la ordon de la argumentoj de :file:`setup.py` por la komando " +"«upload», ĉar la ordo gravas. (:pr:`260`)" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" +"Klarigis kiel instali el nesubtenata fonto per helpa programo. (:pr:`289`)" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "Marto 2017" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "Menciis ``manylinux1`` en *Platforma Wheel*. (:pr:`283`)" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "Februaro 2017" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "Aldonis :pep:`518`. (:pr:`281`)" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "Superrigardo pri Pakado de Python" + +#: ../source/overview.rst:7 +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." +msgstr "" +"Kiel ĝeneralcela programlingvo, Python estas uzebla por multaj celoj. Vi " +"povas verki retejon aŭ industrian roboton aŭ ludon por viaj amikoj, kaj " +"multe pli, uzante la saman kernan teĥnikon." + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" +"Jen superrigardo de ĝeneralcela decidarbo por elekti inter la abundo da " +"opcioj pri pakado de Python. Legu ĝin por elekti la plej bonan teĥnikon por " +"via projekto." + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "Pripensi disponigon" + +#: ../source/overview.rst:25 +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:" +msgstr "" +"Pako ekzistas por instalado (aŭ *disponigado*). Tial, antaŭ ol paki ion ajn, " +"oni havu respondojn al la jenaj demandoj pri disponigo:" + +#: ../source/overview.rst:29 +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?" +msgstr "" +"Kiuj estas la uzantoj de via programo? Ĉu via programo estos instalita de " +"alia programisto verkanta programon, operaciisto en datenejo, aŭ nespertulo?" + +#: ../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 "" +"Ĉu via programo estas por servilo, labortabla komputilo, portebla kliento " +"(telefono, tabulkomputilo ktp), aŭ enkonstruado en aparaton?" + +#: ../source/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "Ĉu via programo estas instalata unuope aŭ multope?" + +#: ../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 "" +"Pakado temas pri la cela medio kaj la sperto de disponigo. Ekzistas multaj " +"respondoj al la demandoj ĉi-supraj, kaj ĉiu kombinaĵo de cirkonstancoj havas " +"siajn proprajn solvojn. La sekva superrigardo gvidos vin al la pakada " +"teĥniko plej taŭga por via projekto." + +#: ../source/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "Paki Python-bibliotekojn kaj ilojn" + +#: ../source/overview.rst:45 +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`." +msgstr "" +"Eble vi konas PyPI, ``setup.py``, kaj ``wheel``-dosieroj. Jen kelkaj iloj de " +"la ekosistemo de Python por distribui Python-kodon al programistoj; vi povas " +"legi pri ili en :doc:`guides/distributing-packages-using-setuptools`." + +#: ../source/overview.rst:50 +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`." +msgstr "" +"La jenaj manieroj de pakado estas por bibliotekoj kaj iloj uzataj de fakuloj " +"dum programado. Por paki Python-programon por nefakuloj kaj/aŭ por " +"entreprena disponigo, vidu :ref:`packaging-applications`." + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "Python-moduloj" + +#: ../source/overview.rst:58 +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." +msgstr "" +"Python-dosiero dependanta nur de la norma biblioteko estas redistribuebla " +"kaj reuzebla. Oni ankaŭ devas certigi, ke ĝi estis verkita por la ĝusta " +"versio de Python kaj nur dependas de la norma biblioteko." + +#: ../source/overview.rst:63 +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 " +"`." +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 "" +"Tamen, tiu metodo ne funkcias bone por projekto konsistanta el multaj " +"dosieroj, bezonanta pliajn bibliotekojn, au postulanta specifan version de " +"Python; tial la ĉi-subaj opcioj." + +#: ../source/overview.rst:75 +msgid "Python source distributions" +msgstr "Python-fontaj distribuoj" + +#: ../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 "" +"Se via kodo konsistas el pluraj Python-dosieroj, ĝi estas kutime organizita " +"en dosierujan strukturon. Dosierujo enhavanta Python-dosierojn povas " +"esti :term:`Importa Pako `." + +#: ../source/overview.rst:81 +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." +msgstr "" +"Ĉar pako konsistas el pluraj dosieroj, distribui pakon estas pli malfacile. " +"Multaj protokoloj nur kapablas transdoni po unu dosieron por ĉi fojo. (Se " +"oni alklakas hiperligon, oni nur elŝutas unu dosieron.). Oftas neplena " +"transdono, kaj malfacilas garantii la integrecon de la kodo ĉe la celloko." + +#: ../source/overview.rst:87 +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." +msgstr "" +"Se la kodo enhavas nur Python-kodon kaj la disponiga medio subtenas vian " +"version de Ptyhon, oni povas uzi la indiĝenajn pakilojn de Python por krei " +"*fontan* :term:`Distribuan Pakon `, aŭ mallongigite " +"*sdist*." + +#: ../source/overview.rst:92 +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." +msgstr "" +"La *sdist* de Python estas densigita arĥivo (de dosiersufikso ``.tar.gz``) " +"enhavanta unu aŭ plurajn pakojn aŭ modulojn. Se via kodo konsistas nur el " +"Python kaj vi nur dependas de aliaj pakoj verkitaj en Python, vi povas lerni " +"plu ĉe la normo :ref:`source-distribution-format`." + +#: ../source/overview.rst:97 +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." +msgstr "" +"Se vi dependas de ne Python-a kodo aŭ ne-Python-a pako (kiel `libxml2 " +"`_ por `lxml `_ aŭ BLAS-bibliotekoj por `numpy `_), vi devas uzi la formon detalitan en la sekva paragrafo, kiu estas " +"ankaŭ utila eĉ por pure Python-a biblioteko." + +#: ../source/overview.rst:104 +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!" +msgstr "" +"Python kaj PyPI subtenas plurajn distribuojn de malsamaj realigoj de la sama " +"pako. Ekzemple, la ne plu mastrumata sed origina `distribuo PIL `_ provizas la pakon PIL, ankaŭ provizatan de `Pillow " +"`_, kiu estas aktive mastrumata forko de " +"PIL!" + +#: ../source/overview.rst:111 +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``." +msgstr "" +"Per ĉi tiu pakada kapablo de Python, Pillow povas esti plena anstataŭigaĵo " +"por PIL simple per ŝanĝo de la ``install_requires`` aŭ ``requirements.txt`` " +"de via projekto." + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "Python-duumaj distribuoj" + +#: ../source/overview.rst:118 +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." +msgstr "" +"Multo da praktika potenco de Python devenas de la kapablo integriĝi al la " +"programa ekosistemo, speciale bibliotekoj verkitaj en C, C++, Fortrano, Rust " +"kaj aliaj lingvoj." + +#: ../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." +msgstr "" + +#: ../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 "" +"Duuma distribuo plej taŭgas, kiam ĝi venas kun respondanta fonta distribuo. " +"Eĉ se vi ne alŝutas wheel de via kodo por ĉiu mastruma sistemo, se vi " +"alŝutas fontan distribuon, vi ebligas uzantojn de aliaj platformoj konstrui " +"wheel por si. Eldonu kaj fontan distribuon kaj wheel-arĥivon kune, *krom se* " +"vi kreas artefaktojn por tiu kliento, kiu specife nur bezonas unu el la duo." + +#: ../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." +msgstr "" +"Python kaj PyPI faciligas kune alŝuti kaj fontan distribuon kaj wheel. Sekvu " +"la lernilon :doc:`tutorials/packaging-projects`." + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "Resumo pri la pakaj kapabloj de Python por iloj kaj bibliotekoj." + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" +"La rekomendataj aprioraj biblioteko- kaj ilo-pakadaj teĥnikoj por Python. El " +"`The Packaging Gradient (2017) `_." + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "Paki Python-aplikprogramojn" + +#: ../source/overview.rst:154 +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." +msgstr "" +"Ĝis nun ni nur diskutis la indiĝenajn distribuilojn de Python. Tiuj " +"indiĝenaj manieroj nur celas mediojn jam havantajn Python kaj tiujn " +"uzantojn, kiuj scias kiel instali Python-pakon." + +#: ../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 "" +"Pro la diverseco de mastrumaj sistemoj, agordoj, kaj homoj, oni nur povas " +"supozi tion celante programistojn." + +#: ../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 "" +"La indiĝena pakada meĥanismo de Python estas plejparte por distribui " +"reuzeblan kodon (t.e. bibliotekon) inter programistoj. Oni povas ankaŭ " +"distribui **ilojn** (bazajn programojn por programistoj) per la pakada " +"meĥanismo por bibliotekoj uzante teĥnikojn kiel :doc:`entry_points de " +"setuptools `." + +#: ../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." +msgstr "" +"Biblioteko estas konstrua bloko, ne kompleta aplikprogramo. Por distribui " +"aplikprogramon, ekzistas mondo da teĥnikoj." + +#: ../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 "" +"La sekvaj paragrafoj organizas tiujn opciojn pri pakado de programo laŭ la " +"dependeco de la cela medio, por helpi vin elekti taŭgan opcion por via " +"projekto." + +#: ../source/overview.rst:178 +msgid "Depending on a framework" +msgstr "Dependi de kadro" + +#: ../source/overview.rst:180 +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." +msgstr "" +"Kelkaj specoj de Python-programoj, kiel reteja malfasado aŭ alia reta servo, " +"estas tiel oftaj, ke kadroj ebligas la verkadon kaj pakadon de tiaj " +"programoj. Aliaj specoj de programoj, kiel dinamika TTT-fasado aŭ poŝaparata " +"kliento, estas tiel komplikaj, ke kadro necesas." + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" +"Se vi scivolas, kiel tiuj platformoj kaj kadroj interne funkcias, legu la ĉi-" +"subajn paragrafojn." + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "Servaj platformoj" + +#: ../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 "" +"Se oni programas por «`Platformo-kiel-Servo `_» (mallongigite PaaS), oni sekvu la pakadan gvidilon " +"de la platformo. Tia platformo prizorgas pakadon kaj disponigon, se oni " +"sekvas la gvidnormojn. La plejmulto da programoj ne estas por tia platformo; " +"tial ekzistas la aliaj opcioj ĉi-subaj." + +#: ../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 "" +"Se vi evoluigas programon disponigotan al maŝinoj posedataj de vi, aŭ la " +"personaj komputiloj de uzantoj, aŭ alia loko, legu plu." + +#: ../source/overview.rst:209 +msgid "Web browsers and mobile applications" +msgstr "TTT-legiloj kaj poŝaparatoj" + +#: ../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 "" +"La progresado de Python gvidas ĝin en novajn spacojn. Nuntempe oni povas " +"verki poŝaparatan programon aŭ retprograman fasadon per Python. Dum la " +"lingvo estas konata, la praktiko pri pakado kaj disponigado estas nova." + +#: ../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 "" +"Se vi planas eldonadon al tiuj novaj limoj, vi volas esplori la jenajn " +"kadrojn kaj iliajn gvidilojn pri pakado:" + +#: ../source/overview.rst:220 +#, fuzzy +msgid "`Kivy `_" +msgstr "`Poetry `_" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "`Beeware `_" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "`Brython `_" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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 "" +"Se vi *ne* interesiĝas pri kadro aŭ platformo, aŭ simple scivolas pri la " +"teĥnikoj uzitaj de la ĉi-supraj kadroj, legu plu." + +#: ../source/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "Dependi de antaŭinstalita Python" + +#: ../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 "" +"Elektu iun ajn komputilo. Depende de la kunteksto, ekzistas bona ŝanco, ke " +"Python estas jam instalita. Ĝi estas apriore inkluzivita en la plejparto de " +"Linux kaj Mac mastrumaj sistemoj dum multaj jaroj, kaj oni povas racie " +"supozi, ke Python jam ekzistas en datencentro aŭ persona komputilo de " +"programisto aŭ datensciencisto." + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "Jen teĥnikoj subtenantaj tiun modelon:" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr ":gh:`PEX ` (Python EXecutable)" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" +":doc:`zipapp ` (ne helpas mastrumi dependecojn, " +"postulas Python 3.5+)" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr ":gh:`shiv ` (postulas Python 3)" + +#: ../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 "" +"El tiuj metodoj, dependado de antaŭinstalita Python-interpretilo plej " +"dependas de la cela medio. Tio ankaŭ signifas, ke tiu metodo rezultigas la " +"plej malgrandan pakon, de kelkaj megabajtoj aŭ eĉ kilobajtoj." + +#: ../source/overview.rst:249 +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 "" +"Ĝenerale, ju malpli la pako dependas de la cela sistemo, des pli granda " +"estas la pako. Tial, la opcioj estas ordigitaj proksimume laŭ kreskanta " +"grando de la eligaĵo." + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "Dependi de aparta programdistribua ekosistemo" + +#: ../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 "" +"Delonge je multaj mastrumaj sistemoj, inkluzive de macOS kaj Windows, mankis " +"enkonstruita pakadministrilo. Nur ĵus tiuj mastrumaj sistemoj ekhavas la " +"tiel nomitajn «programbutikojn», sed eĉ tiaj programbutikoj temas pri " +"programoj por ordinaraj uzantoj kaj ne por programistoj." + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "Instrukcioj pri konstruado kaj eldonado por la ekosistemo Anaconda:" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" +"`Kontrui bibliotekojn kaj aplikprogramojn per conda `_" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" +"`Migrigi indiĝenan Python-pakon al Anaconda `_" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" +"Simila modelo uzas instalado de alternativa Python-distribuo, sed ne " +"subtenas arbitrajn mastrumasistemo-nivelajn pakojn:" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" +"`ActiveState ActivePython `_" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "`WinPython `_" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "Alporti vian propran Python-ruleblaĵon" + +#: ../source/overview.rst:290 +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." +msgstr "" +"Komputadon difinas la kapablo ruli programojn. Ĉiu mastruma sistemo difinas " +"unu aŭ plurajn formojn de indiĝene ruleblaj programoj." + +#: ../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 "" +"Ekzistas multaj teĥnikoj por paki Python-programon en unu el tiuj formoj, " +"kiuj ofte enkorpigas la Python-interpretilon kaj aliajn dependaĵojn en unu " +"ruleblan dosieron." + +#: ../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 "" +"Tio, nomita «frostigo», provizas larĝan kongruecon kaj senjuntan sperton, " +"kvankam tio ofte postulas plurajn teĥnikojn kaj multon da klopodo." + +#: ../source/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "Jen kelkaj Python-frostigiloj:" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" +"`pyInstaller `_ - " +"Plurplatforma" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" +"`cx_Freeze `_ - Plurplatforma" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" +"`constructor `_ – Por komandliniaj " +"instaliloj" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "`py2exe `_ - nur Windows" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "`py2app `_ - nur Mac" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "`osnap `_ - Windows kaj Mac" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "`pynsist `_ - nur Windows" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" +"La ĉi-supraĵoj implicas disponigon por unu uzanto. Por plurkomponantaj " +"servilaj programoj, vidu :gh:`Chef Omnibus `." + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "Alporti vian propran uzantospacon" + +#: ../source/overview.rst:321 +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*." +msgstr "" +"Multaj mastrumaj sistemoj – inkluzive de Linux, macOS kaj Windows – povas " +"ruli programon pakitan kiel leĝeran diskokopion, uzante la relative modernan " +"manieron de `mastrumasistemo-nivela virgualigo `_, aŭ *ujigo*." + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" +"Tiaj teĥnikoj estas plejparte sendependaj de Python, ĉar ili pakas tutajn " +"mastrumsistemajn dosiersistemojn, ne sole Python aŭ Python-pakojn." + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" +"Tio estas plej ofta por Linux-servilo, por kiu tiaj teĥnikoj estis " +"inventitaj kaj por kiu tiaj teĥnikoj funkcias plej bone:" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "`AppImage `_" + +#: ../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 "Alporti vian propran kernon" + +#: ../source/overview.rst:342 +#, fuzzy +#| 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." +msgid "" +"Most desktop 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 "" +"La plejmulto da mastrumaj sistemoj subtenas ian klasikan virtualigon " +"rulantan programon pakitan kiel diskokopion kun propra plena mastruma " +"sistemo. Ruli tian virtualan maŝinon (VM) oftas, speciale en datencentro." + +#: ../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:" +msgstr "" +"Tiuj teĥnikoj estas plejparte por grandskalaj disponigoj en datencentroj, " +"kvankam iuj kompleksaj programoj povas profiti el tia pakado. La teĥnikoj ne " +"dependas de Python kaj inkluzivas la jenon:" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" +"`VHD `_, `AMI `_, kaj :doc:`aliaj dosierformoj " +"`" + +#: ../source/overview.rst:356 +#, fuzzy +#| msgid "" +#| "`OpenStack `_ - A cloud " +#| "management system in Python, with extensive VM support" +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" +"`OpenStack `_ – Nubadministra " +"sistemo en Python, kun multa subteno de virtuala maŝino" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "Alporti vian propran aparaton" + +#: ../source/overview.rst:362 +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." +msgstr "" +"La plej totala maniero disponigi vian programon estas sendi ĝin jam " +"instalita sur iu aparato. Tiel, la uzanto de via programo postulas nur " +"elektron." + +#: ../source/overview.rst:366 +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 "" +"Dum la ĉi-supraj virtualaj maŝinoj estas ĉefe uzataj de fakuloj, aparatoj " +"estas uzataj de ĉiuj, de la plej komplikaj datencentroj ĝis la plej junaj " +"infanoj." + +#: ../source/overview.rst:370 +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 "" +"Metu vian kodon sur :gh:`Adafruit `, `MicroPython " +"`_, aŭ pli potencan aparaton kapablan ruli Python, " +"kaj sendu ĝin al la datencentro aŭ la hejmo de viaj uzantoj. Ili povos " +"ekuzi, kaj vi povos ekmalstreĉi." + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "Resumo pri teĥnikoj por paki Python-programojn." + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "La simpligita gamo de teĥnikoj uzataj por paki Python-programojn." + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "Kio pri…" + +#: ../source/overview.rst:384 +msgid "" +"The sections above can only summarize so much, and you might be wondering " +"about some of the more conspicuous gaps." +msgstr "" +"La ĉi-supraj paragrafoj nur priskribas tiom, kiom eblas. Vi eble demandos " +"pri mankantaj temoj." + +#: ../source/overview.rst:388 +msgid "Operating system packages" +msgstr "Mastrumasistemaj pakoj" + +#: ../source/overview.rst:390 +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 "" +"Laŭ la ĉi-supra paragrafo :ref:`depending-on-a-separate-ecosystem`, kelkaj " +"mastrumaj sistemoj havas siajn proprajn pakadministrilojn. Se oni certegas " +"pri la celata mastruma sistemo, oni povas dependi rekte de formo kiel `deb " +"`_ (por Debian, Ubuntu " +"ktp.) aŭ `RPM `_ (por Red " +"Hat, Fedora ktp.), kaj uzi tiun indiĝenan pakadministrilon por instalado kaj " +"eĉ disponigo. Oni povas eĉ uzi `FPM `_ por generi kaj deb kaj RPM el la sama fonto." + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" +"En multaj disponigaj ĉenstabloj, la mastrumsistema pakadministrilo estas nur " +"unu ero en la puzlo." + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" +"Por grava disponigo, ne dependu de rulado de ``python - m pip install`` de " +"la Interreto al virtuala medio, simile al evoluada medio. La ĉi-supra " +"superrigardo priskribas multe pli bonajn solvojn." + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "Sekureco" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" +"Ju pli suben vi iras, des pli malfacile estas ĝisdatigi komponantojn de via " +"pako, ĉar ĉiuj estas des pli kunligitaj." + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "Konkludo" + +#: ../source/overview.rst:437 +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." +msgstr "" +"La publika reputacio estas, ke pakado en Python povas esti malglata. Tio " +"estas plejparte rezulto de la diversaj celoj de Python. Post kiam oni scias " +"la naturajn limojn inter la pakadaj manieroj, oni komprenos, ke la diversa " +"pejzaĝo estas malgranda prezo pagata de Python-programistoj por uzi unu el " +"la plej ekvilibraj, flekseblaj lingvoj haveblaj." + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "Duuma distribua formo" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" +"Jen paĝo specifanta la duuman distribuan dosierformon por Python-pako, " +"nomitan wheel." + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 estas ZIP-forma arĥivo kun speciale aranĝita dosiernomo kaj la " +"dosiersufikso ``.whl''. Ĝi enhavas unu distribuon preskaŭ ekzakte kiel la " +"instalon laŭ PEP 376 kun specifa instala skemo. Kvankam speciala instalilo " +"estas rekomendata, oni povas instali wheel-dosieron simple per maldensigado " +"al site-packages uzante la norman ilon ``unzip``, koonservante sufiĉon da " +"informoj por transloki la enhavojn al la finaj dosierlokoj poste." + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "Detaloj" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "Instali wheel «distribution-1.0-py32-none-any.whl»" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "Instalado de wheel consistas koncepte el du fazoj:" + +#: ../source/specifications/binary-distribution-format.rst:29 +msgid "Unpack." +msgstr "Malpaki." + +#: ../source/specifications/binary-distribution-format.rst:31 +msgid "Parse ``distribution-1.0.dist-info/WHEEL``." +msgstr "Sintaksanalizi ``distribution-1.0.dist-info/WHEEL``." + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" +"Kontroli, ĉu la instalilo kongruas kun Wheel-Version. Averti, se la minora " +"versio estas pli granda; ĉesi, se la maĵora versio estas pli granda." + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" +"Se Root-Is-Purelib == 'true', malpaki arĥivon al purelib (site-packages)." + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "Alikaze, malpaki arĥivon al platlib (site-packages)." + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "Disvastigi." + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" +"Malpakita arĥivo inkluzivas ``distribution-1.0.dist-info/`` kaj (se datenoj " +"ekzistas) ``distribution-1.0.data/``." + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" +"Movu ĉiun subarbon de ``distribution-1.0.data/`` al la cela dosierloko. Ĉiu " +"subdosierujo de ``distribution-1.0.data/`` estas ŝlosilo en vortaro da celaj " +"dosierujoj, kiel ``distribution-1.0.data/(purelib|platlib|headers|scripts|" +"data)``. Tiuj subdosierujoj estas :ref:`instalaj dosierlokoj difinitaj de " +"sysconfig `." + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" +"Ĝisdatigu tiujn programojn, kiuj komenciĝas per ``#!python``, igante ilin " +"montri la ĝustan interpretilon." + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" +"Ĝisdatigi ``distribution-1.0.dist-info/RECORD`` pri la instalitaj " +"dosierlokoj." + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "Forigi malplenan dosierujon ``distribution-1.0.data``." + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" +"Traduki ajnan instalitan .py al .pyc. (Malinstaliloj forigu .pyc, eĉ se ĝi " +"ne estas menciita en RECORD.)" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "Rekomendataj funkcioj de instaliloj" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "Reskribi ``#!python``." + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" +"En wheel, programeto troviĝas en ``{distribuo}-{versio}.data/scripts/``. Se " +"la unua linio de dosiero en ``scripts/`` komenciĝas precize per ``b'#!" +"python'``, modifu ĝin montrante la ĝustan interpretilon. Instalilo por " +"Unikso eble devas aldoni la biton +x al tiaj dosieroj, se la arĥivo estis " +"kreita sur Windows." + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" +"La konvencio ``b'#!pythonw'`` estas permesata. ``b'#!pythonw'`` indikas " +"grafikan programon anstataŭ konzolan programon." + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "Generi programvolvaĵoj." + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" +"En wheel, programeto pakita sur Uniksa sistemo ne havas ``.exe``-volvilon. " +"Instalilo por Windows povas provizi tiun dum instalado." + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "Rekomendataj funkcioj de arĥiviloj" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "Meti ``.dist-info`` ĉe la fino de la arĥivo." + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" +"Arĥivilo metu la dosierojn ``.dist-info`` fizike ĉe la fino de la arĥivo. " +"Tio ebligas utilajn teĥnikojn pri arĥivoj, inkluzive de la kapablo modifi la " +"metadatenojn sen reskribado de la tuta arĥivo." + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "Dosierformo" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "Dosiernoma konvencio" + +#: ../source/specifications/binary-distribution-format.rst:92 +msgid "" +"The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" +"{abi tag}-{platform tag}.whl``." +msgstr "" +"La dosiernomo de wheel estas ``{distribuo}-{version}(-{konstrua etikedo})?-" +"{lingva etikedo}-{abietikedo}-{platforma etikedo}.whl``." + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "distribution" +msgstr "distribuo" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "Nomo de distribuo, ekz. «django», «pyramid»." + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "Versio de la distribuo, ekz. 1.0." + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "konstrua etikedo" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" +"Nedeviga konstruo-numero. Devas komenciĝi per cifero. Oni uzas tiun por " +"komparo, se du wheel-dosiernomoj estas samaj ĉiel alie (ekz. laŭ nomo, " +"versio kaj aliaj etikedoj). Por ordigado, konsideru ĝin kiel malplenan " +"opon, se ĝi mankas; se ne, konsideru ĝin kiel duopo, kies unua ero estas la " +"komencaoj ciferoj kiel ``int``, kaj kies dua ero estas la restaĵo de la " +"etikedo kiel ``str``." + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" +"Ofta uzkazo por konstrunumero estas rekonstrui duuman distribuon pro ŝanĝo " +"en la konstrua medio, ekzemple por uzi la diskokopion manylinux por konstrui " +"distribuojn kun antaŭeldonaj versioj de CPython." + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" +"Pro tiu limigo, nova distribuo, kiun oni referencas ekstere, **ne uzu** " +"konstruo-numerojn dum konstruado de la nova distribuo. Por tiu bezono, oni " +"kreu **novan distribuo-version**." + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "lingva etikedo" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "Ekz. «py27», «py2», «py3»." + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "abietikedo" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "Ekz. «cp33m», «abi3», «none»." + +#: ../source/specifications/binary-distribution-format.rst:133 +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "platform tag" +msgstr "platforma etikedo" + +#: ../source/specifications/binary-distribution-format.rst:133 +msgid "E.g. 'linux_x86_64', 'any'." +msgstr "Ekz. «linux_x86_64», «any»." + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" +"Ekzemple, ``distribuo-1.0-1-py27-none-any.whl`` estas la unua konstruo de " +"pako nomita «distribuo» kaj kongruas kun Python 2.7 (ajna realigo de Python " +"2.7), sen aplika binara interfaco (pura Python), sur ajna ĉefprocesora " +"arĥitekturo." + +#: ../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 "" +"La lastaj tri komponantj de la dosiernomo antaŭ la sufikso nomiĝas " +"«kongruecaj etikedoj». Tiaj etikedoj esprimas la bazajn postulojn de la " +"pako pri interpretilo kaj estas difinitaj en PEP 425." + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "Eskapado kaj Unikodo" + +#: ../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 "" +"Ĉar la komponantoj de la dosiernomo estas apartigitaj per streketo (``-``, " +"HYPHEN-MINUS), tiu signo ne povas aperi ene de komponanto. Oni pritraktas " +"tion jene:" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" +"En nomo de distribuo, ajna sinsekvo de skribsignoj ``-_.`` (HYPHEN-MINUS, " +"LOW LINE kaj FULL STOP) estu anstataŭigita per ``_`` (LOW LINE), kaj " +"majuskloj estu anstataŭigitaj per la respondantaj minuskloj. Tio " +"ekvivalentas ordinaran :ref:`normigon de nomo ` sekvitan " +"de anstataŭigado de ``-`` per ``_``. Ilo konsumanta wheel devas akcepti " +"``.`` (FULL STOP) kaj majusklojn, ĉar tiuj estis permesataj de malnova " +"versio de ĉi tiu specifo." + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" +"Versia numero estu normigita laŭ :ref:`la specifo pri versio-specifilo " +"`. Normigita versia numero ne enhavas ``-``." + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" +"La ceteraj komponantoj ne povas enhavi la signon ``-``; tial nenia kodŝanĝo " +"necesas." + +#: ../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 "" +"Ilo generanta wheel konfirmu, ke la dosiernomo-komponantoj ne enhavas ``-``, " +"ĉar alie la rezulta dosiero eble ne estos ĝuste pritraktita." + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" +"La arĥiva dosiernomo estas Unikoda. Povas esti, ke iloj ankoraŭ ne estas " +"ĝisdatigitaj por ne-Askia dosiernomo, sed ĉi tiu specifo subtenas tian " +"dosiernomon." + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" +"La dosiernomoj *en* la arĥivo estas konditaj laŭ UTF-8. Kvantam kelkaj ofte " +"uzataj ZIP-klientoj ne ĝuste montras dosiernomon en UTF-8, tiu kodado estas " +"subtenata kaj de la normo ZIP kaj la modulo ``zipfile`` de Python." + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "Dosieraj enhavoj" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" +"La enhavo de wheel-dosiero, en kiu {distribution} estas anstataŭigita per " +"la :ref:`normigita ` de la pako, ekz. ``beaglevote``, " +"kaj {version} estas anstataŭigita per la :ref:`normigita versio `, ekz. ``1.0.0``, konsistas el la jeno:" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" +"``/``, la radiko de la arĥivo, enhavas ĉiujn dosierojn instalotajn al " +"``purelib`` aŭ ``platlib`` laŭ la specifo en ``WHEEL``. Kaj ``purelib`` kaj " +"``platlib`` estas ofte ``site-packages``." + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "``{distribuo}-{versio}.dist-info/`` enhavas metadatenojn." + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" +":file:`{distribution}-{version}.dist-info/licenses/` enhavas licenco-" +"dosierojn." + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" +"``{distribuo}-{versio}.data/`` enhavas po unu subdosierujo por ĉiu " +"nemalplena instalskema ŝlosilo ne jam pritraktita, je kio la nomo de " +"subdosierujo estas indico de vortaro de instalaj dosierlokoj (ekz. ``data``, " +"``scripts``, ``headers``, ``purelib``, ``platlib``)." + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" +"Python-programeto devas ekzisti en ``scripts`` kaj komenciĝi ekzakte per " +"``b'#!python'``, se oni deziras generi programeto-volvaĵon kaj reskribadon " +"de ``#!python`` dum instalado. Ĝi povas havi iun ajn aŭ neniun " +"dosiersufikson. La dosierujo ``scripts`` povas enhavi nur ordinarajn " +"dosierojn." + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" +"``{distribution}-{version}.dist-info/METADATA`` estas metadatenoj de la " +"formo Metadatenoj versio 1.1 aŭ pli nova." + +#: ../source/specifications/binary-distribution-format.rst:199 +msgid "" +"``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive " +"itself in the same basic key: value format::" +msgstr "" +"``{distribuo}-{versio}.dist-info/WHEEL`` estas metadatenoj pri la arĥivo mem " +"en la sama baza formo «ŝlosilo: valoro»::" + +#: ../source/specifications/binary-distribution-format.rst:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "``Wheel-Version`` estas la versia numero de la specifo pri Wheel." + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" +"``Generator`` estas la nomo kaj, nedevige, la versio de la programo " +"generinta la arĥivon." + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" +"``Root-Is-Purelib`` estas vera, se la supranivela dosierujo de la arĥivo " +"instaliĝu al purelib, se ne, la radiko instaliĝu al platlib." + +#: ../source/specifications/binary-distribution-format.rst:215 +msgid "" +"``Tag`` is the wheel's expanded compatibility tags; in the example the " +"filename would contain ``py2.py3-none-any``." +msgstr "" +"``Tag`` estas la pliigitaj kongruecaj etikedoj de la wheel; en la ekzemplo, " +"la dosiernomo enhavus ``py2.py3-none-any``." + +#: ../source/specifications/binary-distribution-format.rst:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" +"``Build`` estas la numero de la konstro; ĝi estas preterlasita, se mankas " +"numero de la konstruo." + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" +"Instalilo de wheel avertu, se ``Wheel-Version`` estas pli granda ol la " +"subtenata versio, kaj devas malsukcesi, se ``Wheel-Version`` havas pli " +"grandan maĵoran version ol la subtenatan version." + +#: ../source/specifications/binary-distribution-format.rst:221 +msgid "" +"Wheel, being an installation format that is intended to work across multiple " +"versions of Python, does not generally include .pyc files." +msgstr "" +"Wheel, estante instaleblaĵon por pluraj versioj de Python, ne ĝenerale " +"inkluzivas ``.pyc``-dosierojn." + +#: ../source/specifications/binary-distribution-format.rst:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "Wheel ne enhavas setup.py aŭ setup.cfg." + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" +"Ĉi tiu versio de la wheel-normo baziĝas sur la instalo-skemo de " +"``distutils`` kaj ne difinas kiel instali dosierojn al aliaj lokoj. La " +"aranĝo estas superaro de la funkcioj provizitaj de la ekzistantaj duumaj " +"formoj wininst kaj egg." + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "La dosierujo .dist-info" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" +"La dosierujoj .dist-info de Wheel inkluzivas, minimume, METADATA, WHEEL, kaj " +"RECORD." + +#: ../source/specifications/binary-distribution-format.rst:236 +msgid "" +"METADATA is the package metadata, the same format as PKG-INFO as found at " +"the root of sdists." +msgstr "" +"METADATA estas la pakaj metadatenoj, en la sama formo kiel PKG-INFO en la " +"radiko de fontaj distribuoj." + +#: ../source/specifications/binary-distribution-format.rst:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "WHEEL estas la wheel-metadatenoj specifaj al iu konstruo de la pako." + +#: ../source/specifications/binary-distribution-format.rst:239 +#, fuzzy +#| 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." +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." +msgstr "" +"RECORD estas listo de (preskaŭ) ĉiuj dosieroj en la wheel kaj iliaj sekuraj " +"haketaĵoj. Male al PEP 376, ĉiu dosiero krom RECORD, kiu ne povas enhavi " +"haketaĵon de si mem, devas inkluzivi sian haketaĵon. La haketaĵa algoritmo " +"devas esti sha256 aŭ pli fortika; specife, md5 kaj sha1 estas malpermesataj, " +"ĉar subskribita wheel-dosiero dependas de la fortikaj haketaĵoj en RECORD " +"por la integrecon de la arĥivo." + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" +"La INSTALLER kaj REQUESTED de PEP 376 ne estas inkluzivitaj en la arĥivo." + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +#, fuzzy +#| 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." +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" +"Dum maldensigado, instalilo de wheel kontrolas ĉiujn haketaĵojn en " +"``RECORD`` kaj la dosierajn enhavojn. Krom ``RECORD`` kaj subskriboj, " +"instalado malsukcesos, se ajna dosiero en la arĥivo ne estas menciita en " +"``RECORD`` aŭ ne kongruas kun sia haketaĵo." + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "Subdosierujoj en :file:`.dist-info/`" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "Subdirectory name" +msgstr "Nomo de subdosierujo" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "PEP / Normo" + +#: ../source/specifications/binary-distribution-format.rst:264 +msgid "``licenses``" +msgstr "``licenses``" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr ":pep:`639`" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "``license_files``" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "``LICENSES``" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "``sboms``" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr ":pep:`770`" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "La dosierujo :file:`.dist-info/licenses/`" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" +"Se la metadatena versio estas 2.4 aŭ pli nova kaj unu aŭ pli da kampoj " +"``License-File`` ekzistas, do la dosierujo :file:`.dist-info/` DEVAS enhavi " +"la subdosierujon :file:`licenses/`, kiu DEVAS enhavi la dosierojn en la " +"kampoj ``License-File`` en la dosiero :file:`METADATA` ĉe la respektivaj " +"dosierlokoj relativaj al la dosierujo :file:`licenses/`." + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "La dosierujo :file:`.dist-info/sboms/`" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "La dosierujo .data" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" +"Iu ajn dosiero ne ordinare instalita al site-packages iras en la " +"dosierujon .data, nomitan kiel la dosierujon .dist-info sed kun la " +"sufikso .data/::" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" +"La dosierujo ``.data`` enhavas subdosierujojn de la programetoj, ĉapoj, " +"dokumentoj ktp de la distribuo. Dum instalado, la enhavoj de tiuj " +"dosierujoj kopiiĝas al siaj celaj dosierlokoj." + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "Oftaj demandoj" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "Wheel difinas dosierujon .data. Ĉu mi metu ĉiom da miaj datenoj tien?" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" +"Ĉi tiu normo ne havas opinion pri kiel oni organizu sian kodon. La dosierujo " +"``.data`` estas nur loko por tiuj dosieroj, kiuj ordinare ne instaliĝas en " +"``site-packages`` aŭ en ``PYTHONPATH``. Alivorte, oni rajtas daŭre uzi " +"``pkgutil.get_data(pako, risurso)``, eĉ se *tiuj* dosieroj ordinare ne " +"distribuiĝas en la dosierujo ``.data`` de wheel." + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "Kio temas pri «purelib» kontraste kun «platlib»?" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" +"Wheel konservas la distingon inter «purelib» kaj «platlib», kio gravas sur " +"kelkaj platformoj. Ekzemple, Fedora instalas pure Python-ajn pakojn al «/usr/" +"lib/pythonX.Y/site-packages» kaj platformo-dependajn pakojn al «/usr/lib64/" +"pythonX.Y/site-packages»." + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" +"Wheel kun «``Root-Is-Purelib: false``», kies ĉiuj dosieroj troviĝas en " +"``{nomo}-{versio}.data/purelib``, ekvivalentas al wheel kun «``Root-Is-" +"Purelib: true``» kun la samaj dosieroj en la radiko. Estas valide havi " +"dosierojn en kaj «purelib» kaj «platlib»." + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" +"Praktike, wheel havu nur unu el ``purelib`` aŭ ``platlib``, depende de ĉu ĝi " +"estas pure Python-a aŭ ne, kaj tiaj dosieroj estu ĉe la radiko kun taŭgaj " +"agordoj pri ``Root-is-purelib``." + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "Ĉu eblas importi Python-kodon rekte el wheel-dosiero?" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" +"Unue, wheel *estas* fasonita ĉefe kiel distribua dosierformo; tial, " +"preterpasi la instaladon ankaŭ implicas intence eviti dependi de funkcioj " +"supozantaj plenan instalon (inkluzive de la kapablo uzi normajn ilojn kiel " +"``pip`` kaj ``virtualenv`` por registri kaj administri dependecojn spureble " +"por reviziado kaj sekurigo, aŭ plena integrado kun la norma konstrumeĥanismo " +"de C-etendaĵo per ĉapdosieroj en konvena loko)." + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" +"Due, dum iuj Python-programoj subtenas ruliĝante rekte el zip-arĥivoj, tamen " +"ofte kodo supozas, ke ĝi estis plene instalita. Kiam tiu supozo estas " +"rompita rulante programon el zip-arĥivo, la eraroj ofte estas obskuraj kaj " +"malfacilaj por diagnozi (speciale en triapartiaj bibliotekoj). La du plej " +"oftaj fontoj de problemoj pri tio estas la faktoj, ke importado de C-" +"etendaĵoj el zip-arĥivo estas *ne* subtenata de CPython (ĉar tion ne " +"subtenas la dinamika ŝargada meĥanismo sur ajna platformo), kaj ke dum " +"rulado el zip-arĥivo la atributo ``__file__`` ne estas ordinara " +"dosiersistema loko sed kombina vojo inkluzivanta kaj la lokon de la zip-" +"arĥivo kaj la relativan vojon al la modulo en la arĥivo. Eĉ kiam programo " +"ĝuste uzas la abstraktajn rimedajn API-ojn interne, interagado kun eksteraj " +"komponantoj povas postuli realan surdiskan dosieron." + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "Historio" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "Februaro 2013: Ĉi tiu specifo estis aprobita per :pep:`427`." + +#: ../source/specifications/binary-distribution-format.rst:383 +msgid "" +"February 2021: The rules on escaping in wheel filenames were revised, to " +"bring them into line with what popular tools actually do." +msgstr "" +"Februaro 2021: La reguloj pri kodŝanĝado en wheel-dosiernomoj estis " +"reviziitaj konforme al la fakta konduto de popularaj iloj." + +#: ../source/specifications/binary-distribution-format.rst:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" +"Decembro 2024: Klarigis, ke la dosierujo ``scripts`` nur enhavu ordinaraj " +"dosierojn (ne formale difiniĝas la atendata konduto de konsumanta ilo pri " +"simbola ligilo aŭ subdosierujo en tiu dosierujo; tial kondutoj povas " +"diferenci inter iloj)." + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" +"Decembro 2024: La dosierujo :file:`.dist-info/licenses/` estis specifita " +"per :pep:`639`." + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" +"Januaro 2025: Klarigis, ke nomo kaj versio devas esti normigitaj por la " +"dosierujoj ``.dist-info`` kaj ``.data``." + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "Apendico" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "Ekzempla realigo de urlsafe-base64-nopad::" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "v1.0" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr ":file:`build-details.json`" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" +"La dosiero ``build-detaloj.json`` estas norma formo pri konstruo-specifaj " +"informoj de instalo de Python – kiel ekzemple la versio, detaloj pri la ABI " +"de etendaĵo, kaj aliaj informoj specifaj al tiu konstruo de Python." + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" +"Ekde Python 3.14, dosiero ``build-details.json`` instaliĝas en la platformo-" +"sendependa dosierujo de la norma biblioteko (``stdlib``, ekz. ``/usr/lib/" +"python3.14/build-details.json``)." + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" +"Bonvolu vidi la :ref:`plej novan version ` por la " +"specifo." + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "Ekzemplo" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "Protokolo de ŝanĝoj" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "Specifado" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr ":ref:`build-details-v1.0`" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "Skemo" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "Unua versio, enkondukita de :pep:`739`." + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "``build-details.json`` v1.0" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" +"*build-details.json – statika priskriba dosiero kun konstruaj detaloj de " +"Python-instaloj*" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "tipo" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*object*" +msgstr "*object*" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "atributoj" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "**schema\\_version**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Schema version." +msgstr "Versio de skemo." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" +"Jen teksto en la formo ``.``, en kiu ```` kaj " +"```` estas numeroj sen komencaj nuloj, reprezentantajn la " +"komponantojn **major** kaj **minor** de la versio. Oni povas aritmetike " +"kompari versiojn, interpretante la versio-tekston kiel decimalan frakcion " +"kun decimala punkto." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" +"Por ĉi tiu versio de la normo, la valoro estas konstanta kaj **DEVAS** esti " +"``1.0``." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" +"Estontaj versioj de ĉi tiu skemo **DEVAS** uzi pli grandan versio-numeron. " +"Estontaj versioj de ĉi tiu skemo **DEVAS NE** uzi la saman versio-" +"komponanton **major** kiel alia skemo-versio, se la normo ne estas " +"retrokontrua kun la alia skemo-version — ĝi ne rajtas modifi aŭ atendi ajnan " +"parton de ĉi tiu normo tiel, ke la semantiko de la interpretitaj datenoj " +"diferencas, aŭ se dateno valida laŭ la nova normo ne validas laŭ mal malnova " +"normo, krom pliaj atributoj (eraroj kaŭzitaj de ``additionalProperties``)." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "*string*" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "const" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "1.0" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "**base\\_prefix**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "Baza prefikso de la Python-instalo." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" +"Aŭ absoluta dosierloko, aŭ dosierloko relativa al la dosierujo, en kiu " +"troviĝas ĉi tiu dosiero." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "examples" +msgstr "ekzemploj" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "/usr" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "../.." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "base\\_interpreter" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "La dosierloko de la Python-interpretilo de la baza instalo." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "Aŭ absoluta dosierloko aŭ dosierloko relativa al ``base_prefix``." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" +"Ĉi tiu kampo **DEVAS** ekzisti, se la instalo provizas interpretilan " +"ruleblaĵon." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "/usr/bin/python" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "bin/python" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "**platform**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "Teksto pri sistema platformo." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "Ĉi tiu kampo **EKVIVALENTU** ``sysconfig.get_platform()``." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "linux-x86\\_64" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "**language**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "Objekto enhavanta detalojn pri la normo de la programlingvo Python." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**version**" +msgstr "**version**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" +"Teksta prezento de la versio de la programlingvo Python – versio-signiĉeno " +"konsistanta nur el la komponantoj *major* kaj *minor*." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "Ĉi tiu kampo **EKVIVALENTU** ``sysconfig.get_python_version()``." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "3.14" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "version\\_info" +msgstr "version\\_info" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "Objekto en la formo de :py:data:`sys.version_info`." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "Ĉi tiu sekcio **EKVIVALENTU** :py:data:`sys.version_info`." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "major" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "3" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "minor" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "14" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "micro" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "1" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "releaselevel" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "final" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "serial" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "0" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "**major**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*number*" +msgstr "*number*" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "**minor**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "**micro**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "**releaselevel**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "enum" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "alpha, beta, candidate, final" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "**serial**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "additionalProperties" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "False" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**implementation**" +msgstr "**implementation**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "Objekto enhavanta detalojn pri la realigo de Python." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" +"Ĉi tiu sekcio **EKVIVALENTU** :py:data:`sys.implementation`. Ĝi obeas la " +"normon PEP 421: alivorte, krom la postulataj ŝlosiloj, ankaŭ realigo-" +"specifaj ŝlosiloj povas ekzisti, se ili havas prefikson de substreko." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "**name**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "Minuskla nomo de la realigo de Python." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "cpython" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "pypy" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" +"Objekto en la formo de :py:data:`sys.version_info`, enhavanta la version de " +"la realigo." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "7" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "16" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "True" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "abi" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "Objekto enhavanta detalojn pri la ABI." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**flags**" +msgstr "**flags**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "Konstruadaj agordaj flagoj, por determini la etendaĵan sufikson." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" +"La flagoj **DEVAS** difiniĝi laŭ la ordo de apero en la etendaĵa sufikso." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "*array*" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "t" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "d" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "extension\\_suffix" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "Sufikso por etendaĵo uzanta la aktualan version de la realigo." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" +"Ĉi tiu kampo **DEVAS** ekzisti, se la Python-realigo subtenas etendaĵon; se " +"ne, ĉi tiu ero mankas." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr ".cpython-314-x86\\_64-linux-gnu.so" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "stable\\_abi\\_suffix" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "Sufikso uzata por etendaĵoj uzantaj la stabilan ABI." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" +"Ĉi tiu sekcio **DEVAS** ekzisti, se la Python-instalo provizas " +"etendaĵosufikson por stabila ABI; se ne, ĉi tiu sekcio mankas." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr ".abi3.so" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "suffixes" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "Validaj modulaj sufiksoj grupigitaj laŭ tipo." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" +"Ĉi tiu sekcio **DEVAS** ekzisti, se la Python-instalo subtenas importado de " +"ektera dosiero, kaj ĝi **EKVIVALENTU** la atributojn " +"``importlib.machinery.*_SUFFIXES``." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" +"Plie, se Python-realigo subtenas specojn de etendaĵoj aliajn ol tiuj, kiuj " +"troviĝas en la modulo ``importlib.machinery``, do subsekcioj por tiuj specoj " +"**POVAS** ankaŭ ekzisti." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "source" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr ".py" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "bytecode" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr ".pyc" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "optimized_bytecode" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "debug_bytecode" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extensions" +msgstr "extensions" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr ".cpython-313-x86\\_64-linux-gnu.so" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr ".so" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "libpython" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "Objekto enhavanta detalojn pri la biblioteko ``libpython``." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" +"Ĉi tiu sekcio **DEVAS** ekzisti, se la Python-instalo provizas bibliotekon " +"``libpython``; se ne, ĉi tiu sekcio mankas." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "dynamic" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "La dosierloko de la dinamika biblioteko ``libpython``." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" +"Ĉi tiu sekcio **DEVAS** ekzisti, se la Python-instalo provizas dinamikan " +"bibliotekon ``libpython``; se ne, ĉi tiu sekcio mankas." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "/usr/lib/libpython3.14.so.1.0" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "lib/libpython3.14.so.1.0" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "dynamic\\_stableabi" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" +"La dosierloko de la dinamika biblioteko ``libpython`` por la stabila ABI." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" +"Ĉi tiu sekcio **DEVAS** ekzisti, se la Python-instalo provizas dinamikan " +"bibliotekon ``libpython`` por la Stabila ABI; se ne, ĉi tiu sekcio mankas." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "Se ĉi tiu ŝlosilo ekzistas, ``dynamic`` **DEVAS** ankaŭ ekzisti." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "/usr/lib/libpython3.so" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "lib/libpython3.so" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "static" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "La dosierloko de la statika biblioteko ``libpython``." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" +"Ĉi tiu sekcio **DEVAS** ekzisti, se la Python-instalo provizas statikan " +"bibliotekon ``libpython``; se ne, ĉi tiu sekcio mankas." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "link\\_extensions" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "Ĉu etendaĵo konstruita por dinamika ``libpython`` bindiĝi al ĝi?" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "*boolean*" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "c\\_api" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "Objekto enhavanta detalojn pri la C API de Python." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" +"Ĉi tiu sekcio **DEVAS** ekzisti, se la Python-instalo provizas C API; se ne, " +"ĉi tiu sekcio mankas." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**headers**" +msgstr "**headers**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "La dosierloko de la ĉapoj de la C API." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "/usr/include/python3.14" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "include/python3.14" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "pkgconfig\\_path" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "La dosierloko de la difinodosieroj pkg-config." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" +"Ĉi tiu sekcio **DEVAS** ekzisti, se la Python-instalo provizas " +"difinodosierojn pkg-config; se ne, ĉi tiu sekcio mankas." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "/usr/lib/pkgconfig" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "lib/pkgconfig" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "arbitrary\\_data" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "Objekto enhavantan ekstrajn arbitrajn datenojn." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" +"Oni uzu tion por inkluzivi ĉian ajn gravan datenon ne menciitan en ĉi tiu " +"nromo. Realigo povas elekti tiajn informojn, kiaj inkluziviĝos en ĉi tiu " +"sekcio." + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "Kernaj metadatenaj specifoj" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" +"La kampoj difinitaj en la jena specifo estu konsiderataj kiel validaj, " +"plenaj kaj ne ŝanĝotaj. Jen la postulataj kampoj:" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "``Name``" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "Ĉiuj aliaj kampoj estas nedevigaj." + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" +"Se metadatenoj seriiĝas al bajta fluo (ekzemple, por konservado sur " +"dosieron), signoĉenoj devas esti koditaj laŭ UTF-8." + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" +"Kvankam :pep:`566` difinis manieron transformi metadatenojn en JSON-kongruan " +"vortaron, ĝi ankoraŭ ne estas uzata kiel norma interŝanĝa dosierformo. Por " +"iloj, la bezono kunfunkcii kun jaroj da ekzistantaj pakoj malfaciligas " +"adoptadon de nova dosierformo." + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "Metadata-Version" + +#: ../source/specifications/core-metadata.rst:52 +#, fuzzy +#| msgid "" +#| "Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +#| "\"2.1\", \"2.2\", \"2.3\", and \"2.4\"." +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" +"Versio de la dosierformo; la validaj valoroj estas «1.0», «1.1», «1.2», " +"«2.1», «2.2», «2.3», kaj «2.4»." + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" +"Por pli larĝa kongrueco, konstruilo POVAS generi distribuajn metadatenojn " +"uzante la plej malnovan metadatenan version inkluzivantan ĉiujn necesajn " +"kampojn." + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "Ekzemple::" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "Nomo" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "Aldonis restriktojn pri formo el la :ref:`noma formo `." + +#: ../source/specifications/core-metadata.rst:80 +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 "" +"La nomo de la distribuo. La kampo ``name`` estas la ĉefa identigilo de " +"distribuo. Ĝi devas observi la :ref:`specifon pri nomformoj `." + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" +"Por komparado, la nomoj estu :ref:`normigitaj ` antaŭ " +"komparado." + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "Versio" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" +"Signoĉeno enhavanta la versian numero de la distribuo. Tiu kampo devas " +"esti en la formo specifita en la :ref:`specifo pri versio-specifiloj " +"`." + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "Dynamic (plurfoje uzebla)" + +#: ../source/specifications/core-metadata.rst:113 +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 "" +"Signoĉeno enhavanta la nomon de alia kerna metadatena kampo. La kamponomoj " +"``Name``, ``Version`` kaj ``Metadata-Version`` devas esti ne specifitaj en " +"ĉi tiu kampo." + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" +"Se ĝi troviĝas en la metadatenoj de fonta distribuo, efektivas la jenaj " +"reguloj:" + +#: ../source/specifications/core-metadata.rst:120 +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 "" +"Se kampo *ne* estas markita kiel ``Dynamic``, do la valoro de la kampo en " +"ajna wheel konstruita el la fonta distribuo DEVAS egali la valoron en la " +"fonta distribuo. Se la kampo mankas en la fonta distribuo kaj ne estas " +"markita kiel ``Dynamic``, do ĝi DEVAS NE ekzisti en la wheel." + +#: ../source/specifications/core-metadata.rst:124 +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 "" +"Se kampo estas markita kiel ``Dynamic``, ĝi povas enhavi iun ajn validan " +"valoron en wheel konstruita el la fonta distribuo (inkluzive de manko de " +"valoro)." + +#: ../source/specifications/core-metadata.rst:127 +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 "" +"Se la metadatenoj de la fonta distribuo havas version malpli novan ol 2.2, " +"do oni pritraktu ĉiujn kampojn, kvazaŭ ili estus markitaj per ``Dynamic`` " +"(alivorte, kvazaŭ ne ekzistus speciala limigo pri la metadatenoj de wheel " +"konstruita el la fonta distribuo)." + +#: ../source/specifications/core-metadata.rst:131 +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 "" +"En ĉiu kunteksto krom fonta distribuo, ``Dynamic`` estas nur informa kaj " +"indikas, ke la valoro de la kampo estis komputita dum konstruado de wheel " +"kaj eble ne egalas la valoron en la fonta distribuo en alia wheel por la " +"projekto." + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "Plenaj detaloj pri la semantiko de ``Dynamic`` troviĝas en :pep:`643`." + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "Platform (plurfoje uzebla)" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" +"Platforma specifo priskribanta mastruman sistemon subtenatan de la distribuo " +"kaj ne en la listo de la Trove-klasigilo «Operating System». Vidu " +"«Klasigilon» ĉi-sube." + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "Ekzemploj::" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "Supported-Platform (plurfoje uzebla)" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" +"Duuma distribuo enhavanta dosieron :file:`PKG-INFO` enhavos la kampon " +"``Supported-Platform`` en metadatenoj specifantan la mastruman sistemon kaj " +"ĉefprocesoron, por kiu la duuma distribuo estis tradukita. Ĉi tiu PEP ne " +"difinas la semantikon de la kampo ``Supported-Platform``." + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "Unulinia resumo pri la funkcioj de la distribuo." + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "Ĉi tiu kampo estas anstataŭe specifebla en la mesaĝa korpo." + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" +"Pli longa priskribo de la distribuo, kiu povas esti pluraj paragrafoj. " +"Programo uzanta metadatenojn ne supozu ajnan maksimumon por tiu kampo, " +"kvankam oni ne inkluzivu plenan manlibron kiel la priskribon." + +#: ../source/specifications/core-metadata.rst:217 +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 "" +"La enhavo de tiu kampo povas uzi la marklingvon reStructuredText [1]_. " +"Programo uzanta la metadatenojn ne devas kompreni la marklingvon kaj rajtas " +"anstataŭe montri la kampon krude. Tio signifas, ke aŭtoro estu konservativa " +"pri la uzata marklingvo." + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" +"Tiu kodado implicas, ke ajna okazo de CRLF sekvita de 7 spacetoj kaj " +"vertikalo devas esti anstataŭigita per unu CRLF, kiam la kampo estas " +"maldensigita per realigaĵo de RFC822." + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" +"Alternative, la priskribo de la distribuo povas esti en la enhavo de la " +"mesaĝo (t.e. post plene malplena linio post la ĉapoj, sen krommarĝeno aŭ " +"alia speciala aranĝado)." + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "Description-Content-Type" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" +"Signoĉeno pri la marklingva sintakso (se iu ekzistas) de la priskribo de la " +"distribuo, por inteligenta montrado de la priskribo far iloj." + +#: ../source/specifications/core-metadata.rst:260 +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 "" +"Historie, PyPI subtenis priskribojn en ordinara teksto kaj `reStructuredText " +"(reST) `_, kaj povis montri reST en HTML. Tamen, ofte aŭtoroj " +"de distribuoj verkas la priskribojn en `Markdown `_ (:rfc:`7763`), ĉar multaj kodgastigejoj montras README " +"en Markdown, kaj aŭtoroj reuzas la dosieron por la priskribo. PyPI ne " +"agnoskis tiun formon kaj tial ne povis montri la priskribon ĝuste. Tio " +"kaŭzis multajn pakojn ĉe PyPI kun malĝustaj priskriboj de Markdown montrita " +"kiel ordinara teksto aŭ, pli aĉe, kiel reST. Ĉi tiu kampo ebligas la aŭtoron " +"de la distribuo specifi la dosierformon de la priskribo, ebligante PyPI kaj " +"aliajn ilojn montri Markdown kaj aliajn dosierformojn." + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" +"La formo de tiu kampo estas sama kiel la ĉapo ``Content-Type`` de HTTP (laŭ " +"`RFC 1341 `_). " +"Resume, ĝi havas parton ``type/subtype`` kun nedeviga(j) parametro(j):" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "Formo::" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "La parto ``type/subtype`` nur havas kelkajn validajn valorojn:" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "``text/plain``" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "``text/x-rst``" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "``text/markdown``" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" +"La parametro ``charset`` povas specifi la signokodadon de la priskribo. La " +"ununura valida valoro estas ``UTF-8``. Se ĝi mankas, oni supozas la valoron " +"``UTF-8``." + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" +"Aliaj parametroj povas esti specifaj pri la subtipo. Ekzemple, por la " +"subtipo ``markdown``, ekzistas nedeviga parametro ``variant`` pri la uzita " +"varianto de Markdown (se ĝi mankas, tio implicas ``GFM``). Aktuale du " +"variantoj estas konataj:" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "``GFM`` por :rfc:`GitHub-stila Markdown <7764#section-3.2>`" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "``CommonMark`` por :rfc:`CommonMark <7764#section-3.5>`" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" +"Se ``Description-Content-Type`` mankas, programo provu montri la priskribon " +"kiel ``text/x-rst; charset=UTF-8`` kaj, se ĝi ne estas valida " +"reStructuredText, montri ĝin kiel ``text/plain``." + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" +"Se ``Description-Content-Type`` estas nekonata valoro, do la supozata " +"enhavtipo estas ``text/plain`` (kvankam PyPI verŝajne malakceptos ion ajn de " +"nekonata valoro)." + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" +"Se ``Description-Content-Type`` estas ``text/markdown`` kaj ``variant`` " +"estas nespecifita aŭ nekonata, do la implicita ``variant`` estas ``GFM``." + +#: ../source/specifications/core-metadata.rst:329 +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 "" +"Por la ĉi-supra ekzemplo, ``charset`` estas implicite ``UTF-8``, kaj " +"``varianto`` estas implicite ``GFM``. Tial, ĝi ekvivalentas la ekzemplon " +"antaŭ si." + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "Keywords" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" +"Listo de ekstraj ŝlosilvortoj, apartigitaj de komoj, por helpi serĉadon de " +"la distribuo en granda katalogo." + +#: ../source/specifications/core-metadata.rst:351 +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 "" +"Ĉi tiu normo antaŭe apartigis ŝlosilvortojn per spacetoj, sed distutils kaj " +"setuptools realigis ĝin per komoj. Tiuj iloj estas vaste uzata dum multaj " +"jaroj; tial pli facilas modifi la normon por kongrui kun la realo." + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "Author" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" +"Signoĉeno enhavanta la nomon de la aŭtoro minimume; kromaj kontaktaj " +"informoj povas esti disponigitaj." + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "Author-email" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" +"Signoĉeno enhavanta la retpoŝtan adreson de la aŭtoro. Ĝi povas enhavi " +"nomon kaj retpoŝtan adreson laŭ la formo de la ĉapo ``From:`` en RFC 822." + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" +"Laŭ RFC 822, ĉi tiu kampo povas enhavi pluajn kome disigitajn retpoŝtajn " +"adresojn::" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "Prizorganto" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" +"Signoĉeno enhavanta la nomon de la mastrumanto minimume; kromaj kontaktaj " +"informoj povas esti disponigitaj." + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" +"Notu, ke ĉi tiu kampo estas por tiam, kiam projekto estas mastrumata de iu " +"alia ol la origina aŭtoro. Ĝi malestu, se ĝi estus identa al ``Author``." + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "Maintainer-email" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" +"Signoĉeno enhavanta la retpoŝtan adreson de la mastrumanto. Ĝi povas enhavi " +"nomon kaj retpoŝtan adreson laŭ la formo de la ĉapo ``From:`` en RFC 822." + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" +"Notu, ke ĉi tiu kampo estas por tiam, kiam projekto estas mastrumata de iu " +"alia ol la origina aŭtoro. Ĝi malestu, se ĝi estus identa al ``Author-" +"email``." + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "License" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "Anstataŭe uzu ``License-Expression``." + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" +"Ekde Metadatenoj 2.4, ``License`` kaj ``License-Expression`` ne estas " +"samtempe specifeblaj. Se ambaŭ estas specifitaj, ilo pritraktanta " +"metadatenojn ignoros ``License``, kaj PyPI rifuzos alŝutojn. Vidu `PEP 639 " +"`__." + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "License-Expression" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" +"Signoĉeno, kiu estas valida :term:`SPDX-licencesprimo ` " +"laŭ :doc:`/specifications/license-expression`." + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "License-File (plurfoje uzebla)" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" +"Ĉiu ero estas signoĉena prezento de la dosierloko de licenco-rilata dosiero. " +"La dosierloko troviĝas en la projekta fontarbo relative al la projekta " +"radika dosierujo. Por detaloj, vidu :pep:`639`." + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "Classifier (plurfoje uzebla)" + +#: ../source/specifications/core-metadata.rst:532 +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 "" +"Ĉiu ero estas signoĉeno de unu klasigila valoro por la distribuo. Klasigiloj " +"estas priskribitaj en :pep:`301`, kaj la Python-Pakindekso eldonas dinamikan " +"liston de `aktuale difinitaj klasigiloj `__." + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" +"La uzo de la klasigiloj ``License ::`` estas evitinda ekde Metadatenoj 2.4. " +"Uzu ``License-Expression`` anstataŭe. Vidu `PEP 639 `_." + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "Tiu kampo povas esti sekvita per media marko post punktokomo." + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "Requires-Dist (plurfoje uzebla)" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" +"La specifo pri la kampa formo estis malstriktigita por akcepti la sintakson " +"uzatan de popularaj eldoniloj." + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" +"Ĉiu ero enhavas signoĉenon nomantan alian distutils-projekton postulatan de " +"tiu distribuo." + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" +"La formo de postulo-signoĉeno enhavas minimume unu, maksimume kvar partojn:" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" +"Projekta nomo en la sama formo kiel la kampo ``Name:``. La sola deviga parto." + +#: ../source/specifications/core-metadata.rst:567 +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 "" +"Kome disigita listo de nomoj de «ekstraĵoj». Tiuj estas difinitaj de la " +"postulata projekto, por specifaj funkcioj postulantaj ekstrajn dependecojn. " +"La nomoj DEVAS observi la limigojn de la kampo ``Provides-Extra:``." + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" +"Versio-specifilo. Ilo sintakse analizanta la formon akceptu nedevigajn " +"rondajn krampojn ĉirkaŭ tiu, sed ilo generanta ĝin ne uzu rondajn krampojn." + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" +"Media marko post punktokomo. Tio signifas, ke la postulo estas nur efektiva " +"sub la specifitaj kondiĉoj." + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "Vidu :pep:`508` por plenaj detaloj pri la permesataj formoj." + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" +"La projektaj nomoj respondu al nomoj ĉe la `Python-Pakindekso `_." + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "Versispecifilo devas observi la regulojn en :doc:`version-specifiers`." + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +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 "" +"Tiu kampo specifas tiu(j)n versio(j)n de Python, kun kiu(j) la distribuo " +"kongruas. Instalilo povas konsideri tion dum elektado de instalota versio de " +"projekto." + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" +"La valoro devas observi la formon specifitan en :doc:`version-specifiers`." + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" +"Ekzemple, se distribuo uzas :ref:`f-signoĉenon `, ĝi " +"povas malpermesi instaladon sur Python < 3.6 jene::" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "Ĉi tiu kampo ne povas esti sekvita de media marko." + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "Requires-External (plurfoje uzebla)" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" +"La formo de postulo-signoĉeno estas nomo de ekstera dependaĵo, nedevige " +"sekvita de versia deklaro ene de rondaj krampoj." + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" +"Ĉar tiu kampo temas pri ne-Python-a programa versio, la valoro de tiu kampo " +"*ne* devas observi la formon precizigita en la :ref:`Normo pri versio-" +"specifiloj `; ĝi sekvu la versian skemon de la ekstera " +"dependaĵo." + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "Notu, ke ekzistas neniu speciala regulo pri la uzota signoĉeno." + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "Project-URL (plurfoje uzebla)" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" +"Signoĉeno enhavanta alireblan retadreson de la projekto kaj etikedon, " +"apartigitajn de komo." + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "La etikedo estas arbitra teksto limigita al 32 skribsignoj." + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" +"Ekde :pep:`753`, konsumanto de projektaj metadatenoj (kiel la Python-" +"Pakindekso) povas uzi normigan procedon por trovi «bone konatajn» etikedojn, " +"kiujn oni povas prezenti speciale por homoj. Vidu :ref:`well-known-project-" +"urls`." + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "Provides-Extra (plurfoje uzebla)" + +#: ../source/specifications/core-metadata.rst:677 +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` limigis validajn valorojn al la malambiguaj valoroj (alivorte, " +"sen postulata normigo.Por malnovaj versioj de metadatenoj, limigoj de valoro " +"kongruiĝis kun ``Name:``, kaj reguloj pri normigado estis starigitaj." + +#: ../source/specifications/core-metadata.rst:682 +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 "" +"Signoĉeno enhavanta la nomon de nedeviga funkcio. Valida nomo konsistas nur " +"el minusklaj Askiaj literoj, Askiaj ciferoj, kaj streketo. Ĝi devas " +"komenciĝi kaj finiĝi per litero aŭ cifero. Streketo devas ne sekvi alian " +"streketon. Nomo devas konformi al la jena regula esprimo (garantiante " +"malambiguecon)::" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" +"La specifita nomo povas esti uzata por igi dependecon kondiĉa pri ĉu la " +"nedeviga funkcio estas petata." + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" +"Du funkcio-nomoj ``test`` kaj ``doc`` estas rezervataj por marki dependecojn " +"por aŭtomataj testoj kaj generado de dokumentaro respektive." + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" +"Validas specifi ``Provides-Extra:`` sen referencado de ĝi en ajna ``Requires-" +"Dist:``." + +#: ../source/specifications/core-metadata.rst:715 +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 "" +"Dum skribado de datenoj por pli malnovaj versioj de metadatenoj, oni DEVAS " +"normigi nomon laŭ la samajn regulojn por la kampo ``Name:`` dum komparado. " +"Iloj skribantaj metadatenojn DEVAS sciigi pri eraro, se du kampoj ``Provides-" +"Extra:`` konfliktus post normigo." + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +#, fuzzy +#| msgid "Supported-Platform (multiple use)" +msgid "Import-Name (multiple use)" +msgstr "Supported-Platform (plurfoje uzebla)" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +#, fuzzy +#| msgid "Supported-Platform (multiple use)" +msgid "Import-Namespace (multiple use)" +msgstr "Supported-Platform (plurfoje uzebla)" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "Malofte uzataj kampoj" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" +"La kampoj en ĉi tiu paragrafo estas nuntempe malofte uzataj, ĉar ili estis " +"fasonitaj simile al meĥanismoj en Linux-pakadministraj sistemoj, kaj ne " +"klasas, kiel ilo interpretu ilin por malfermita indeksoservilo kiel `PyPI " +"`__." + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "Provides-Dist (plurfoje uzebla)" + +#: ../source/specifications/core-metadata.rst:847 +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 "" +"Ĉiu ero enhavas signoĉenon nomantan projekton Distutils, kiun ĉi tiu " +"distribuo enhavas. Tiu kampo *devas* inkluzivi la projekton identigitan en " +"la kampo ``Name``, sekvita de la versio: Nomo (Versio)." + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" +"Oni povas provizi versio-deklaron, kiu devas observi la regulojn " +"en :doc:`version-specifiers`. Se nenio estas provizita, tio implicas la " +"versian numeron de la distribuo." + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "Obsoletes-Dist (plurfoje uzebla)" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" +"Ĉiu ero enhavas signiĉenon priskribantan distribuon de distutils-projekto, " +"kiun ĉi tiu distribuo evitindigas – alivorte, oni ne instalu ambaŭ " +"projektojn samtempe." + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" +"Versio-deklaroj povas esti provizitaj. Versia numero devas observi la " +"formon en :doc:`version-specifiers`." + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" +"La plej ofta uzo de tiu kampo estas por ŝanĝo de nomo de projekto. Ekzemple, " +"Gorgon 2.3 fariĝis Torqued Python 1.0. Kiam oni instalas Torqued Python, do " +"oni malinstalu la distribuon de Gorgon." + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "Evitindaj Kampoj" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" +"Oni evitu evitindajn kampojn, sed ili restas validaj metadateno-kampoj. Ili " +"povas esti forigitaj en estontaj versioj de la normo de kernaj metadatenoj " +"(post kiam ili nur estos validaj en dosieroj uzantaj metadateno-version " +"antaŭ la forigo). Ilo AVERTU uzanton, se troviĝas evitinda kampo." + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "Home-page" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "Laŭ :pep:`753`, uzu :ref:`core-metadata-project-url` anstataŭe." + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "Signoĉeno de la retadreso de la ĉefpaĝo de la distribuo." + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "Download-URL" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" +"Signoĉeno de tiu retadreso, el kiu la versio de la distribuo estas " +"elŝutebla. (Tio signifas, ke la retadreso ne povas esti «``.../BeagleVote-" +"latest.tgz``», sed devas esti «``.../BeagleVote-0.45.tgz``».)" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "Requires" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "anstataŭe uzu ``Requires-Dist``" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" +"Ĉiu ero enhavas signiĉenon priskribantan alian modulon aŭ pakon postulatan " +"de tiu pako." + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" +"La formo de postulo-signoĉeno estas identa al tiu de modulo aŭ paknomo " +"uzebla kun la ``import``-aserto, laŭvole sekvita de versio-deklaro en rondaj " +"krampoj." + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" +"Iom ajn da kondiĉaj operatoroj validas. Ekzemple, ``>1.0, !=1.3.4, <2.0`` " +"estas valida versio-deklaro." + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" +"Jen kelkaj eblaj postulo-signoĉenoj: «rfc822», «zlib (>=1.1.4)», «zope»." + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" +"Ne ekzistas listo de uzendaj signoĉenoj; la komunumo de Python elektu siajn " +"proprajn normojn." + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "Provides" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "anstataŭe uzu ``Provides-Dist``" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "Obsoletes" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "anstataŭe uzu ``Obsoletes-Dist``" + +#: ../source/specifications/core-metadata.rst:1021 +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 "" +"Ĉiu ero enhavas tekston priskribantan pakon aŭ modulon, kiun tiu pako " +"malnoviĝintigas, tiel ke la du pakaĵoj ne estu instalitaj kune. Oni povas " +"provizi versio-deklarojn." + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" +"La plej ofta uzo de tiu kampo estas por ŝanĝo de nomo de pako. Ekzemple, " +"Gorgon 2.3 fariĝis Torqued Python 1.0. Kiam oni instalas Torqued Python, do " +"oni malinstalu la pakon Gorgon." + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "Marto 2001: Kernaj metadatenoj 1.0 estis aprobitaj per :pep:`241`." + +#: ../source/specifications/core-metadata.rst:1039 +#, fuzzy +#| msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`:" +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "Aprilo 2003: Kernaj metadatenoj 1.1 estis aprobitaj per :pep:`314`:" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "Februaro 2010: Kernaj metadatenoj 1.2 estis aprobitaj per :pep:`345`." + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "Februaro 2018: Kernaj metadatenoj 2.1 estis aprobitaj per :pep:`566`." + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "Aldonis ``Description-Content-Type`` kaj ``Provides-Extra``." + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "Aldonis kanonan metodon por transformi metadatenojn al JSON." + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "Restriktis la gramatikon de la kampo ``Name``." + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "Oktobro 2020: Kernaj metadatenoj 2.2 estis aprobitaj per :pep:`643`." + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "Aldonis la kampon ``Dynamic``." + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "Marto 2022: Kernaj metadatenoj 2.3 estis aprobitaj per :pep:`685`." + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "Devigis normigon de nomoj de ekstraĵoj." + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "Aŭgusto 2024: Kernaj metadatenoj 2.4 estis aprobitaj per :pep:`639`." + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "Aldonis la kampon ``License-Expression``." + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "Aldonis la kampon ``License-File``." + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +#, fuzzy +#| msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "Oktobro 2020: Kernaj metadatenoj 2.2 estis aprobitaj per :pep:`643`." + +#: ../source/specifications/core-metadata.rst:1068 +#, fuzzy +#| msgid "Added the ``Dynamic`` field." +msgid "Added the ``Import-Name`` field." +msgstr "Aldonis la kampon ``Dynamic``." + +#: ../source/specifications/core-metadata.rst:1069 +#, fuzzy +#| msgid "Added the ``Dynamic`` field." +msgid "Added the ``Import-Namespace`` field." +msgstr "Aldonis la kampon ``Dynamic``." + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "Marklingvo reStructuredText: https://docutils.sourceforge.io/" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "RFC 822 Long-Ĉapaj Kampoj: :rfc:`822#section-3.1.1`" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "Dependecaj Grupoj" + +#: ../source/specifications/dependency-groups.rst:7 +#, fuzzy +#| msgid "" +#| "This specification defines Dependency Groups, a mechanism for storing " +#| "package requirements in ``pyproject.toml`` files such that they are not " +#| "included in project metadata when it is built." +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" +"Ĉi tiu specifo difinas Dependecan Grupon, kiu estas meĥanismo por konservi " +"pako-postulojn en ``pyproject.toml`` tiel, ke ili ne inkluziviĝas en " +"projektaj metadatenoj post konstruado." + +#: ../source/specifications/dependency-groups.rst:11 +#, fuzzy +#| msgid "" +#| "Dependency Groups are suitable for internal development use-cases like " +#| "linting and testing, as well as for projects which are not built for " +#| "distribution, like collections of related scripts." +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" +"Dependenca Grupo taŭgas por interna evoluada uzokazo kiel sintaksanalizado " +"kaj testado kaj ankaŭ por projekto ne konstruita por distribuado, kiel " +"kolekto de rilataj programetoj." + +#: ../source/specifications/dependency-groups.rst:15 +#, fuzzy +#| msgid "" +#| "Fundamentally, Dependency Groups should be thought of as being a " +#| "standardized subset of the capabilities of ``requirements.txt`` files " +#| "(which are ``pip``-specific)." +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" +"Fundamente, Dependeca Grupo estas normigita subaro de la kapabloj de dosiero " +"``requirements.txt`` (specifa al ``pip``)." + +#: ../source/specifications/dependency-groups.rst:25 +#, fuzzy +#| msgid "This is a simple table which shows a ``test`` group::" +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "Jen simpla tabelo montranta grupon ``test``::" + +#: ../source/specifications/dependency-groups.rst:31 +#, fuzzy +#| msgid "and a similar table which defines ``test`` and ``coverage`` groups::" +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "kaj simila tabelo difinanta la grupojn ``test`` kaj ``coverage``::" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "La Tabelo ``[dependency-groups]``" + +#: ../source/specifications/dependency-groups.rst:41 +#, fuzzy +#| msgid "" +#| "Dependency Groups are defined as a table in ``pyproject.toml`` named " +#| "``dependency-groups``. The ``dependency-groups`` table contains an " +#| "arbitrary number of user-defined keys, each of which has, as its value, a " +#| "list of requirements." +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" +"Dependeca Grupo estas difinita kiel tabelo en ``pyproject.toml`` nomita " +"``dependency-groups``. La tabelo ``dependency-groups`` enhavas nelimigitan " +"nombron de uzanto-dfinititaj ŝlosiloj, ĉiu el kiuj havas liston de postuloj " +"kiel valoron." + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" +"Ŝlosilo de ``[dependency-groups]``, ankaŭ nomita «grupo-nomo», devas " +"esti :ref:`valida nenormigita nomo `. Ilo pritraktanta " +"Dependecan Grupon DEVAS :ref:`normigi ` la nomon antaŭ " +"komparado." + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" +"Ilo PREFERU prezenti la originalan, nenormigitan nomon al uzanto. Se " +"duplikata nomo troviĝas post normigo, ilo MONTRU eraron." + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" +"Postulo-listoj, t.e. la valoroj en ``[dependency-groups]``, povas enhavi " +"signoĉenojn, tabelojn (``dict`` de Python), aŭ miksaĵo de signoĉenoj kaj " +"tabeloj. La signoĉenoj devas esti validaj :ref:`dependeco-specifiloj " +"`, kaj tabeloj devas esti validaj Dependeco-Grupo-" +"Inkluzivoj." + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "Inkluzivo de Dependeca Grupo" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" +"Dependecgrupa Inkluzivo inkluzivas alian Dependecan Grupon en la aktuala " +"grupo." + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" +"Inkluzivo estas tabelo kun ekzakte unu ŝlosilo, ``\"include-group\"``, kies " +"valoro estas signoĉeno, la nomo de alia Dependeca Grupo." + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" +"Inklzivo de Dependeca Grupo povas specifi la saman pakon plurfoje. Ilo NE " +"SENDUPLIKATIGU NEK alie MODIFU la enhavon de la enhavojn de listo generita " +"de la inkluzivo. Ekzemple, pri la jena tabelo:" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" +"La solvita valoro de ``all`` ESTU ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Ilo pritraktu tian liston precize same kiel en aliaj kazoj, " +"je kio ilo pritraktu la saman postulon plurfoje kun malsamaj versio-limigoj." + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" +"Dependecgrupa Inkluzivo povas inkluzivi grupojn enhavantajn Dependecgrupajn " +"Inkluzivojn; tiukaze, oni ankaŭ etendu tiujn inkluzivojn. Dependecgrupa " +"Inkluzivo DEVAS NE havi ciklon. Trovinte ciklon, ilo RAPORTU eraron." + +#: ../source/specifications/dependency-groups.rst:102 +msgid "Package Building" +msgstr "Konstruado de Pako" + +#: ../source/specifications/dependency-groups.rst:104 +#, fuzzy +#| msgid "" +#| "Build backends MUST NOT include Dependency Group data in built " +#| "distributions as package metadata. This means that sdist ``PKG-INFO`` and " +#| "wheel ``METADATA`` files should not include referenceable fields " +#| "containing Dependency Groups." +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" +"Konstrua malfasado DEVAS NE inkluzivi datenon pri Dependecaj Grupoj en " +"konstruita distribuo kiel pakan metadatenon. Tio signifas, ke la dosiero " +"``PKG-INFO`` de fonta distribuo kaj la dosiero ``METADATA`` de wheel ne " +"inkluzivu referenceblan kampon enhavantan Dependecan Grupon." + +#: ../source/specifications/dependency-groups.rst:108 +#, fuzzy +#| msgid "" +#| "It is, however, valid to use Dependency Groups in the evaluation of " +#| "dynamic metadata, and ``pyproject.toml`` files included in sdists will " +#| "still contain ``[dependency-groups]``. However, the table's contents are " +#| "not part of a built package's interfaces." +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" +"Tamen validas uzi Dependecan Grupo por solvi dinamikajn metadatenojn, kaj " +"dosiero ``pyproject.toml`` en fonta distribuo ankoraŭ enhavas ``[dependency-" +"groups]``. Tamen, la enhavo de la tabelo ne estas parto de la interfaco de " +"konstruita pako." + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "Instali Dependecajn Grupojn kaj Ekstraĵojn" + +#: ../source/specifications/dependency-groups.rst:116 +#, fuzzy +#| msgid "" +#| "There is no syntax or specification-defined interface for installing or " +#| "referring to Dependency Groups. Tools are expected to provide dedicated " +#| "interfaces for this purpose." +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" +"Ne ekzistas sintakso aŭ specifo-difinita interfaco por instalado aŭ menciado " +"de Dependeco-Grupo. Ilo provizu proprajn interfacojn por tiu celo." + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "Valideckontrolo kaj Kongrueco" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +#, fuzzy +#| msgid "" +#| "Tools SHOULD error when evaluating or processing unrecognized data in " +#| "Dependency Groups." +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" +"Ilo SCIIGU pri eraro, kiam ĝi renkontas aŭ pritraktas nerekonatan datenon en " +"Dependeca Grupo." + +#: ../source/specifications/dependency-groups.rst:138 +#, fuzzy +#| msgid "" +#| "Tools SHOULD NOT eagerly validate the contents of *all* Dependency Groups " +#| "unless they have a need to do so." +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" +"Ilo NE KONTROLU malprokraste la validecon de la enhavoj de *ĉiuj* Dependecaj " +"Grupoj, se ĝi ne bezonas tion." + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" +"Tiu signifas, ke por la jenaj datenoj, iloj ordinare permesos la uzadon de " +"la grupo ``foo``, kaj nur sciigos pri eraro se la grupo ``bar`` estas uzata:" + +#: ../source/specifications/dependency-groups.rst:152 +#, fuzzy +#| msgid "" +#| "There are several known cases of tools which have good cause to be " +#| "stricter. Linters and validators are an example, as their purpose is to " +#| "validate the contents of all Dependency Groups." +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" +"Kelkfoje, ilo tamen povas esti pli strikta. Ekzemple, erardetektilo kaj " +"valideckontrolilo celas kontroli, ĉu la enhavoj de ĉiuj Dependecaj Grupoj " +"validas." + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +msgid "Reference Implementation" +msgstr "Referenca Realigo" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" +"La jena Referenca Realigo eligas la enhavon de Dependeca Grupo al " +"``stdout``, apartigitan per novlinioj. La eligaĵo estas tial valida dateno " +"por ``requirements.txt``." + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "Oktobro 2024: Ĉi tiu specifo estis aprobita per :pep:`735`." + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "Dependeco-specifiloj" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" +"Jen dokumento priskribanta la formon de dependeco-specifiloj, laŭ la " +"originala normo :pep:`508`." + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:31 +msgid "All features of the language shown with a name based lookup::" +msgstr "Jen ekzemplo de ĉiuj funkcioj de la lingvo kun nombaza postulo::" + +#: ../source/specifications/dependency-specifiers.rst:35 +msgid "A minimal URL based lookup::" +msgstr "Minimuma URL-baza serĉo::" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "Konceptoj" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "Gramatiko" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" +"Ni unue maldetale diskutas la gramatikon kaj poste detalos la semantikon de " +"ĉiu sekcio." + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" +"La plena gramatiko kun komentoj por konstrui utilan sintaksarbon troviĝas ĉe " +"la fino de ĉi tiu dokumento." + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" +"Versio estas specifebla laŭ la reguloj de :ref:`la specifo pri versio-" +"specifiloj `. (Notu: URI estas difinita en :rfc:`std-66 " +"<3986>`)::" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "Media marko permesas efektivigi specifon nur en kelkaj medioj::" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" +"Nedeviga komponanto de distribuo estas specifebla per la kampo ``extras``::" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "Restriktoj pri nomoj de kromaĵoj estas difinitaj en :pep:`685`." + +#: ../source/specifications/dependency-specifiers.rst:113 +msgid "Giving us a rule for name based requirements::" +msgstr "Jen la regulo pri nomo-baza postulo::" + +#: ../source/specifications/dependency-specifiers.rst:117 +msgid "And a rule for direct reference specifications::" +msgstr "Kaj regulo pri rekta referenca specifo::" + +#: ../source/specifications/dependency-specifiers.rst:121 +msgid "Leading to the unified rule that can specify a dependency.::" +msgstr "Kaj la unuigita regulo pri specifo de dependeco::" + +#: ../source/specifications/dependency-specifiers.rst:126 +msgid "Whitespace" +msgstr "Blanka spaco" + +#: ../source/specifications/dependency-specifiers.rst:128 +msgid "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" +"Ne-linifina blanka spaco estas plejparte nedeviga sen semantiko. La sola " +"escepto estas trovi la finon de retadresa postulo." + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "Nomoj" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" +"Nomoj de Python-distribuo estas aktuale difinitaj en :pep:`345`. Nomo estas " +"la ĉefidentigilo de distribuo. Ĝi ekzistas en ĉiuj specifoj pri dependecoj " +"kaj sufiĉas por sia propra specifo. Tamen, PyPI restrikegas nomojn — nomo " +"devas kongrui kun usklecblinda regula esprimo; alie ĝi malakceptiĝos. Tial " +"ĉi tiu dokumento limigas la akcepteblajn identigilojn al tiu regula esprimo. " +"Plena redifino de nomo povas okazi en verkota metadatena PEP. Jen la regula " +"esprimo (rulu kun ``re.IGNORECASE``)::" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "Ekstraĵoj" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" +"Ekstraĵo estas nedeviga parto de distribuo. Distribuo povas specifi tiom da " +"ekstraĵoj kiom necesas, kaj ĉiu ekstraĵo kaŭzas la deklaron de pliaj " +"dependecoj de la distribuo **kiam** la ekstraĵo estas uzata en depenceco-" +"specifo. Ekzemple::" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "Se pluraj ekstraĵoj estas listigitaj, ĉiuj dependaĵoj estas kunigitaj." + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "Versioj" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "Mediaj Markoj" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" +"Medio-markilo permesas al dependeco-specifo provizi regulon pri tiam, kiam " +"la dependaĵo estu uzata. Ekzemple, konsideru pakon dependantan de " +"``argparse``. En Python 2.7, ``argparse`` ĉiam ekzistas. Sur pli malnova " +"versio de Python, ĝi devas esti instalita kiel dependeco. Oni esprimas tion " +"jene::" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" +"La valoro de marka esprimo estas aŭ ``True`` aŭ ``False``. Se la valoro " +"estas ``False``, oni ignoru la dependecan specifon." + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +#, fuzzy +#| msgid "" +#| "Comparisons in marker expressions are typed by the comparison operator. " +#| "The operators that are not in perform the same " +#| "as they do for strings in Python. The operators use the " +#| "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::" +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" +"Komparo en marko-esprimo dependas de la komparo-operatoro. La operatoroj " +" ne en funkcias same kiel la operatoroj por " +"signoĉenoj en Python. La operatoroj funkcias laŭ la reguloj " +"pri komparado de versioj en la :ref:`Specifo pri versio-specifiloj `, se tiuj estas difinitaj (t.e. se ambaŭ flankoj estas validaj " +"versio-specifiloj). Se mankas difinita konduto laŭ ĉi tiu specifo kaj la " +"operatoro ekzistas en Python, do la operatoro sekvas la konduton de Python. " +"Alikaze ilo sciigu pri eraro. Ekzemple, la jeno kaŭzos erarojn::" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" +"Nekonata variablo devas kaŭzi eraro, ne rezultigante komparon de valoro " +"``True`` aŭ ``False``." + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" +"Variablo ne komputebla sur iu realigo de Python estu ``0`` por versioj kaj " +"malplena signoĉeno por aliaj variabloj." + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "Marko" + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "Python-ekvivalentaĵo" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "Tipo" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "Ekzemplaj valoroj" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "``os_name``" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr ":py:data:`os.name`" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +#, fuzzy +#| msgid "*string*" +msgid "String" +msgstr "*string*" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "``posix``, ``java``" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "``sys_platform``" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr ":py:data:`sys.platform`" + +#: ../source/specifications/dependency-specifiers.rst:258 +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`` (notu, ke «linux» estas " +"de Python3 kaj «linux2» de Python2)" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "``platform_machine``" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr ":py:func:`platform.machine()`" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "``x86_64``" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "``platform_python_implementation``" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr ":py:func:`platform.python_implementation()`" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "``CPython``, ``Jython``" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "``platform_release``" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr ":py:func:`platform.release()`" + +#: ../source/specifications/dependency-specifiers.rst:271 +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/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "``platform_system``" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr ":py:func:`platform.system()`" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "``Linux``, ``Windows``, ``Java``" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "``platform_version``" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr ":py:func:`platform.version()`" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "``python_version``" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "``'.'.join(platform.python_version_tuple()[:2])``" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +#, fuzzy +#| msgid "Version specifiers" +msgid ":ref:`Version `" +msgstr "Versispecifiloj" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "``3.4``, ``2.7``" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "``python_full_version``" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr ":py:func:`platform.python_version()`" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "``3.4.0``, ``3.5.0b1``" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "``implementation_name``" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr ":py:data:`sys.implementation.name `" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "``cpython``" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "``implementation_version``" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "vidu la difinon ĉi-sube" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "``extra``" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "Eraro, se ne ekzistas kunteksto interpretanta la specifon." + +#: ../source/specifications/dependency-specifiers.rst:302 +msgid "``toml``" +msgstr "``toml``" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "``extras``" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "``{\"toml\"}``" + +#: ../source/specifications/dependency-specifiers.rst:308 +msgid "``dependency_groups``" +msgstr "``dependency_groups``" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "``{\"test\"}``" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" +"La marka variablo ``implementation_version`` devenas " +"de :py:data:`sys.implementation.version `:" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" +"Tiu paragrafo de media marko, origine difinita per :pep:`508`, eksvalidigas " +"la paragrafon pri media marko en :pep:`345`." + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "Kompleta Gramatiko" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "La kompleta gramatiko por parseley::" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "Testa programo – se la gramatiko estas en signoĉeno ``grammar``:" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "Novembro 2015: Ĉi tiu specifo estis aprobita per :pep:`508`." + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" +"Julio 2019: La difino de ``python_version`` `ŝanĝiĝis `_ de ``platform.python_version()[:3]`` al " +"``'.'.join(platform.python_version_tuple()[:2])``, por estontaj versioj de " +"Python kun du-ciferaj maĵoraj kaj minoraj versioj (ekz. 3.10). " +"[#future_versions]_" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" +"Junio 2024: La difino de ``version_many`` estis ŝanĝita por permesi lastan " +"komon, konforme al la Python-realigo uzata ekde malfrua 2022." + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" +"pip, la rekomendata instalilo por Python-pakoj (http://pip.readthedocs.org/" +"en/stable/)" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" +"La sintaksanaliza biblioteko parsley. (https://pypi.python.org/pypi/parsley/)" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" +"Estontaj versioj de Python povas esti problemaj pri la difino de la Media " +"Marka Variablo ``python_version`` (https://github.com/python/peps/issues/560)" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "Registri la Rektan Retadresan Originon de instalita distribuo" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" +"Ĉi tiu dokumento specifas dosieron :file:`direct_url.json` en la dosierujo " +"``*.dist-info`` de instalita distribuo por registri la rektan retadresan " +"originon de la distribuo. La ĝenerala strukturo kaj uzado de dosierujoj " +"``*.dist-info`` troviĝas en :ref:`recording-installed-packages`." + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" +"La dosiero :file:`direct_url.json` DEVAS esti kreita en la " +"dosierujo :file:`*.dist-info` far instalilo dum instalado de distribuo per " +"postulo specifanta rektan retadresan referencon (inkluzive de " +"versikontrolsistema retadreso)." + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" +"Tiu dosiero DEVAS NE kreiĝi dum instalado de distribuo el alia speco de " +"postulo (ekz. nomo plus versio-specifilo)." + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" +"Ĉi tiu JSON-dosiero DEVAS esti UTF-8-kodita seriigo de :doc:`direct-url-data-" +"structure` kongrua kun :rfc:`8259`." + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "Ekzemplaj komandoj de pip kaj ĝiaj efikoj sur direct_url.json" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "Komandoj generantaj ``direct_url.json``:" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (en kiu ``url`` estos la loka dosierujo, al " +"kiu la git-deponejo estas klonita, kaj ``dir_info`` ĉeestos kun " +"``\"editable\": true`` kaj sen ajna ``vcs_info``)" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "Komandoj *ne* generantaj ``direct_url.json``" + +#: ../source/specifications/direct-url.rst:62 +#, fuzzy +msgid "``pip install app``" +msgstr "Uzi ``pip`` por instali Pipenv:" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "Marto 2020: Ĉi tiu specifo estis aprobita per :pep:`610`." + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "Datenstrukturo de Rekta Retadreso" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" +"Jen dokumento specifanta JSON-seriigeblan abstraktan datenstrukturon, kiu " +"prezentas retadreson al Python-projekto aŭ distribuan artefakton kiel " +"versikontrolsistema fontarbo, loka fontarbo, fonta distribuo kaj wheel." + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" +"Je la tempo de verkado, ne ekzistas formala normo pri kunigado de la partoj " +"de ĉi tiu datenstrukturo en unu retadreson transdoneblan al ilo. Ofta " +"prezento estas la retadresa formo pip (`VCS Support `_); " +"aliaj ekzemploj troviĝas en la :ref:`Normo pri versio-specifiloj `." + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" +"La Datenstrukturo de Rekta Retadreso DEVAS esti vortaro seriigebla al JSON " +"laŭ :rfc:`8259`." + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +msgstr "" +"Ĝi DEVAS enhavi almenaŭ du kampoj. La unua estas ``url`` de tipo ``string``. " +"Ĝia enhavo devas esti valida URL laŭ la `normo de WHATWG pri URL `_." + +#: ../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 "" +"Depende de la celo de ``url``, la dua kampo DEVAS esti unu el ``vcs_info`` " +"(se ``url`` referencas versikontrolan sistemon), ``archive_info`` (se " +"``url`` estas fonta arĥivo aŭ wheel), aŭ ``dir_info`` (se ``url`` estas loka " +"dosierujo). La valoro de tia kampo estas (eble malplena) subvortaro, kies " +"eblaj ŝlosiloj difiniĝas ĉi-sube." + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "Konsideroj pri Sekureco" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" +"Se konservita, ``url`` DEVAS esti senigita je ajna grava aŭtentikiga " +"informo, por sekureco." + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" +"La parto «uzanto:pasvorto» de la URL POVAS tamen konsisti el medio-variabloj " +"laŭ la jena regula esprimo:" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" +"Krome, la parto «uzanto:pasvorto» de la URL POVAS esti bone konata, ne-" +"sekurece-grava signoĉeno. Tipa ekzemplo estas ``git`` en URL kiel ``ssh://" +"git@gitlab.com/uzanto/deponejo``." + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "Versikontrolsistemaj Retadresoj" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" +"Se ``url`` montras versikontrolsisteman deponejon, la ŝlosilo ``vcs_info`` " +"DEVAS ekzisti kiel vortaro kun la jenaj ŝlosiloj:" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" +"Ŝlosilo ``vcs`` (de tipo ``string``) DEVAS ĉeesti, enhavante la nomon de la " +"versikontrola sistemo (unu el ``git``, ``hg``, ``bzr``, ``svn``). Alia " +"versikontrola sistemo ESTU registrita per nova PEP amendanta ĉi tiun " +"specifon. La valoro de ``url`` DEVAS kongrui kun la respondanta " +"versikontrola sistemo tiel, ke instalilo povas facile krei komandon por " +"elŝutado el versikontrola sistemo." + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +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 "" +"Ŝlosilo ``commit_id`` (de tipo ``string``) DEVAS ekzisti, kies valoro estas " +"la ekzakta revizia numero intalota. Se la versikontrola sistemo subtenas " +"haketaĵo-baza revizio-identigilo, oni DEVAS uzi tian haketaĵon kiel " +"``commit_id`` por referenci nemodifeblan version de la fontokodo." + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "Arĥivaj Retadresoj" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" +"Se ``url`` montras fontan arĥivon aŭ wheel, la ŝlosilo ``archive_info`` " +"DEVAS ekzisti kiel vortaro kun la jenaj ŝlosiloj:" + +#: ../source/specifications/direct-url-data-structure.rst:85 +msgid "" +"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " +"hex encoded digest of the file." +msgstr "" +"Ŝlosilo ``hashes`` ĈEESTU kiel vortaro rilatanta haketaĵan nomon al " +"deksesume kodita haketaĵo de la dosiero." + +#: ../source/specifications/direct-url-data-structure.rst:88 +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 "" +"Oni povas inkluzivi plurajn haketaĵojn. La konsumanto decidas kion fari pri " +"pluraj haketaĵoj (ĝi povas kontroli ĉiujn, aŭ iujn, aŭ neniun)." + +#: ../source/specifications/direct-url-data-structure.rst:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "Tiuj haketaĵaj nomoj ESTU normigitaj minuskle." + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" +"Ajna haketaĵa algoritmo disponebla per :py:mod:`hashlib` (pli precize, " +"donebla al :py:func:`hashlib.new()` sen pliaj parametroj) estas uzebla kiel " +"ŝlosilo por la vortaro ``hashes``. Oni INKLUZIVU almenaŭ unu sekuran " +"algoritmon el :py:data:`hashlib.algorithms_guaranteed`. Aktuale, ni specife " +"rekomendas ``sha256``." + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" +"Evitinda ŝlosilo ``hash`` (de tipo ``string``) POVAS ĉeesti por " +"retrokongrueco, kies valoro estas ``=``." + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" +"Kiam ambaŭ ŝlosiloj ``hash`` kaj ``hashes`` ekzistas, la haketaĵo prezentita " +"de la ŝlosilo ``hash`` DEVAS ankaŭ ĉeestas en la vortaro de ``hashes``, por " +"ke uzanto povas nur uzi la ŝlosilon ``hashes``, se ĝi ekzistas, kaj nur uzi " +"``hash`` se ne." + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "Lokaj dosierujoj" + +#: ../source/specifications/direct-url-data-structure.rst:116 +msgid "" +"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " +"present as a dictionary with the following key:" +msgstr "" +"Se ``url`` montras lokan dosierujon, la ŝlosilo ``vcs_info`` DEVAS ekzisti " +"kiel vortaro kun la jenaj ŝlosiloj:" + +#: ../source/specifications/direct-url-data-structure.rst:119 +msgid "" +"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " +"installed in editable mode, ``false`` otherwise. If absent, default to " +"``false``." +msgstr "" +"``editable`` (tipo: ``boolean``): ``true`` se la distribuo estas/estis " +"instalita en modifebla reĝimo, ``false`` se ne. Se ĝi mankas, la implicita " +"valoro estas ``false``." + +#: ../source/specifications/direct-url-data-structure.rst:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" +"Se ``url`` referencas lokan dosierujon, ĝi DEVAS havi la skemon ``file`` kaj " +"observu :rfc:`8089`. Speciale, la dosierloka komponanto devas esti absoluta. " +"Simbola ligo ESTU konservata, dum absolutigo de relativa dosierloko." + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "Projektoj en subdosierujoj" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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 "" +"Supranivela kampo ``subdirectory`` POVAS ekzisti, enhavanta dosierujan lokon " +"relativan al la radiko de la versikontrolsistema deponejo, fonta arĥivo aŭ " +"loka dosierujo, por specifi la lokon de ``pyproject.toml`` aŭ ``setup.py``." + +#: ../source/specifications/direct-url-data-structure.rst:139 +msgid "Registered VCS" +msgstr "Registrita Versikontrola Sistemo" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" +"Jen listo de registritaj versikontrolsistemoj; versikontrolsistemo-specifaj " +"informoj pri kiel uzi la kampojn ``vcs``, ``requested_revision`` kaj aliajn " +"de ``vcs_info``; kaj en kelkaj kazoj suplementaj versikontrolsistemo-" +"specifaj kampoj. Ilo POVAS subteni alian versikontrolan sistemon, sed estas " +"REKOMENDATE registri ĝin per PEP modifanta ĉi tiun specifon. La kampo " +"``vcs`` ESTU la komanda nomo (minuskla). Suplementaj kampoj necesaj por tiu " +"versikontrola sistemo HAVU prefikson de la versikontrolsistema komanda nomo." + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "Git" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "Ĉefpaĝo" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "https://git-scm.com/" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "komando de versikontrola sistemo" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "git" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "kampo ``vcs``" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "kampo ``requested_revision``" + +#: ../source/specifications/direct-url-data-structure.rst:163 +msgid "" +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." +msgstr "" +"Nomo de etikedo, nomo de branĉo, referenco de Git, haketaĵo de enmeto, " +"mallongigita haketaĵo de enmeto, aŭ io simila." + +#: ../source/specifications/direct-url-data-structure.rst:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "kampo ``commit_id``" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "Haketaĵo de ŝanĝaro (40 deksesumaj signoj por SHA1)." + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" +"Ilo povas uzi la komandojn ``git show-ref`` kaj ``git symbolic-ref`` por " +"determini, ĉu ``requested_revision`` respondas al Git-referenco. Referenco " +"komenciĝanta per ``refs/tags/`` respondas al etikedo, kaj referenco " +"komenciĝanta per ``refs/remotes/origin/`` post klonado respondas al branĉo." + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "Mercurial" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "https://www.mercurial-scm.org/" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "hg" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" +"Nomo de etikedo, nomo de branĉo, identigilo de ŝanĝaro, mallongigita " +"identigilo de ŝanĝaro." + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "Identigilo de ŝanĝaro (40 deksesumaj signoj)." + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "Bazaar" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "https://www.breezy-vcs.org/" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "bzr" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "Nomo de etikedo, nomo de branĉo, identigilo de revizio." + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "Identigilo de revizio." + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "svn" + +#: ../source/specifications/direct-url-data-structure.rst:226 +msgid "" +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." +msgstr "" +"``requested_revision`` devas kongrui kun la opcio ``--revision`` de ``svn " +"checkout`` . Je Subversion, la branĉo aŭ etikedo estas parto de ``url``." + +#: ../source/specifications/direct-url-data-structure.rst:230 +msgid "" +"Since Subversion does not support globally unique identifiers, this field is " +"the Subversion revision number in the corresponding repository." +msgstr "" +"Ĉar Subversion ne subtenas malloke unikan identigilon, ĉi tiu kampo estas la " +"revizinumero de Subversion en la respondanta deponejo." + +#: ../source/specifications/direct-url-data-structure.rst:235 +msgid "JSON Schema" +msgstr "JSON-Skemo" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" +"Jen JSON-skemo usebla por kontroli la validecon de la enhavo de " +"``direct_url.json``:" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "Fonta arĥivo:" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "Git-retadreso kun etikedo kaj haketaĵo:" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "Loka dosierujo:" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "Loka dosierujo en modifebla reĝimo:" + +#: ../source/specifications/direct-url-data-structure.rst:294 +msgid "" +"March 2020: This specification was approved through :pep:`610`, defining the " +"``direct_url.json`` metadata file." +msgstr "" +"Marto 2020: Ĉi tiu specifo estis aprobita per :pep:`610`, difinante la " +"metadatenan dosieron ``direct_url.json``." + +#: ../source/specifications/direct-url-data-structure.rst:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" +"Januaro 2023: Aldonis la ŝlosilon ``archive_info.hashes`` (`diskuto `_)." + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "Specifo pri enirpunktoj" + +#: ../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 "" +"*Enirpunktoj* estas meĥanismo por instalita distribuo reklami komponantojn " +"provizitajn, igante ilin malkovreblaj kaj uzeblaj de alia kodo. Ekzemple:" + +#: ../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 "" +"Distribuo povas specifi enirpunktojn ``console scripts``, po unu por " +"funkcio. Kiam *pip* (aŭ alia instalilo konanta ``console_scripts``) instalos " +"la distribuon, ĝi kreos komandliniajn volvilojn po unu por enirpunkto." + +#: ../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 "" +"Programo povas uzi enirpunkton por ŝargi kromprogramojn. Ekzemple, la " +"sintaksreliefigilo Pygments povas uzi pliajn sintaksanalizilojn kaj stilojn " +"el aparte instalitaj pakoj. Por pli pri tio, legu :doc:`/guides/creating-and-" +"discovering-plugins`." + +#: ../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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "Datena modelo" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "Koncepte, enirpunkton difinas tri postulataj atributoj:" + +#: ../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 "" +"La **grupo**, al kiu enirpunkto apartenas, indikas tian objekton, kian ĝi " +"provizas. Ekzemple, la grupo ``console_scripts`` estas por enirpunkto al " +"funkcio uzebla kiel komando, dum ``pygments.styles`` estas la grupo por " +"klaso difinanta pygments-stilon. La konsumanto tipe difinas la atendatan " +"interfacon. Por eviti konflikton, konsumanto difinanta novan grupon komencu " +"nomon per nomo ĉe PyPI posedata de la konsumanta projekto sekvita de ``.``. " +"Nomo de grupo devas konsisti el unu aŭ pluraj grupoj de literoj, ciferoj kaj " +"substrekoj, apartigitaj de punktoj (laŭ la regula esprimo ``^\\w+(\\." +"\\w+)*$``)." + +#: ../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 "" +"La **nomo** identigas la enirpunkton en ĝia grupo. La preciza signifo " +"dependas de la uzanto de metadatenoj. Por konzola programeto, la nomo de la " +"enirpunkto estas la komando uzota por lanĉi ĝin. En distribuo, nomoj de " +"enirpunktoj estu unikaj. Se pluraj distribuoj provizas la saman nomon, la " +"uzanto de metadatenoj decidas kion fari. La nomo povas konsisti el ajna " +"skribsigno krom ``=``, sed ĝi povas ne komenciĝi nek finiĝi per blanka " +"spaco, kaj ĝi ne povas komenciĝi per ``[``. Nomo de nova enirpunkto konsistu " +"el literoj, ciferoj, substrekoj, punktoj kaj streketoj (laŭ la regula " +"esprimo ``[\\w.-]+``)." + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" +"La **objekta referenco** montras Python-objekton. Ĝi estas aŭ en la formo " +"``importebla.modulo`` aŭ en la formo ``importebla.modulo:objekto.atributo``. " +"Ĉiu parto inter punktoj kaj dupunktoj estas valida Python-identigilo. Oni " +"serĉas ĝin jene::" + +#: ../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 "" +"Kelkaj iloj nomas tian objektan referencon mem «enirpunkto», speciale kiam " +"ĝi montras funkcion por lanĉi programon." + +#: ../source/specifications/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "Dosierformo" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" +"Enirpunktoj difiniĝas en dosiero nomita :file:`entry_points.txt` en la " +"dosierujo :file:`*.dist-info` de la distribuo. Tiu estas la dosierujo " +"priskribita en :ref:`recording-installed-packages` por instaleblaj " +"distribuoj kaj en :ref:`binary-distribution-format` por wheel. La dosiero " +"estas kodita laŭ UTF-8." + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" +"La dosieraj enhavoj estas en la dosierformo INI, legata de la " +"modulo :mod:`configparser` de Python. Tamen, configparser apriore estas " +"usklecoblinda pri nomoj, sed enirpunktoj estas usklecdistinga. Oni povas " +"krei usklecdistingan ``ConfigParser`` jene::" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" +"La enirpunkta dosiero devas uzi ``=`` por apartigi nomon kaj valoron (dum " +"configparser ankaŭ permesas uzi ``:``)." + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" +"La sekcioj de la agorda dosiero respondas al enirpunktogrupoj: la sekciaj " +"nomoj estas la nomoj de la enirpunktogrupoj, kaj la valoroj kodas kaj la " +"objektan referencon kaj la nedevigajn ekstraĵojn. Se ekstraĵoj ekzistas, ili " +"estas kome disigita listo inter rektaj krampoj." + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" +"En valoro, legilo devas akcepti kaj ignori spacetojn (inkluzive de sinsekvo " +"de pluraj spacetoj) antaŭ aŭ post dupunkto, inter la objekta referenco kaj " +"la malferma rekta krampo, inter la ekstraĵaj nomoj kaj la apartigantaj " +"kvadrataj krampoj kaj dupunktoj, kaj post la ferma rekta krampo. La sintakso " +"de ekstraĵoj estas formale specifita kiel parto de :pep:`508` (kiel " +"``extras``), kaj restriktoj pri valoroj estas formale specifitaj " +"en :pep:`685`. Ilo skribanta la dosieron metu spaceton nur inter la objekta " +"referenco kaj la malferma rekta krampo." + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "Uzado por programetoj" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" +"Du grupoj de enirpunktoj havas specialan signifon je pakado: " +"``console_scripts`` kaj ``gui_scripts``. En ambaŭ grupoj, la nomo de la " +"enirpunkto estu uzebla kiel komando en sistema terminalo post instalo de la " +"pako. La objekta referenco montras funkcion alvokotan senargumente, kiam la " +"komando ruliĝos. La funkcio povas livero entjeron kiel procezan elirkodon. " +"Liveri ``None`` ekvivalentas liveri ``0``." + +#: ../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 "" +"Ekzemple, la enirpunkto ``mycmd = mymod:main`` kreus komandon ``mycmd`` " +"lanĉante jenan programon::" + +#: ../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 "" +"La diferenco inter ``console_scripts`` kaj ``gui_scripts`` nur gravas sur " +"Windows. ``console_scripts`` estas volvita en konzolan ruleblaĵon, alligitan " +"an konzolo, kiu povas uzi :py:data:`sys.stdin`, :py:data:`sys.stdout` " +"kaj :py:data:`sys.stderr` por enigo kaj eligo. ``gui_scripts`` estas volvita " +"en grafikan ruleblaĵon, uzeblan sen konzolo, kiu ne povas uzi la normajn " +"fluojn sen eksplicita redirektado. Aliaj platformoj ne havas tian distingon." + +#: ../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 "" +"Instalilo starigu volvilojn por kaj ``console_scripts`` kaj ``gui_scripts`` " +"en la dosierujo ``scripts`` de la instala skemo. Instalilo ne respondecas " +"pri metado de tiu dosierujo en la media variablo ``PATH`` difinanta la " +"lokojn de komandliniaj iloj." + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" +"Ĉar dosieroj kreiĝas de la nomoj, kaj kelkaj dosiersistemoj estas " +"usklecblidaj, pako ne uzu tiajn nomojn en tiuj grupoj, kiaj nur diferencas " +"usklece. La tiukaza konduto de instaliloj ne estas difinita." + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" +"Oktobro 2017: Tiu specifo estis verkita por formaligi la ekzistantan " +"enirpunktan funkcion de setuptools (`diskuto `_)." + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "Ekstere Mastrumataj Medioj" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" +"Dum kelkaj instalaĵoj de Python estas plene mastrumataj de tiu uzanto, kiu " +"instalis Python, aliaj instalaĵoj povas esti disponigitaj kaj mastrumataj " +"alimaniere (kiel ekzemple la mastrumsistema pakadministrilo en Linux-" +"distribuo, aŭ kiel faskigita Python-medio en programo kun propra instalilo)." + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" +"Provi uzi ordinaran Python-pakilon por administri tian medion estas konfuze " +"kaj povas eĉ malstabiligi la tutan mastruman sistemon. Dokumentaro kaj " +"gvidiloj pri kunfunkcipovo nur helpas iomete pri tiaj problemoj." + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" +"Ĉi tiu normo difinas markodosieron ``EXTERNALLY-MANAGED``, per kiu Python-" +"instalo indikas al Python-specifa ilo kiel ``pip``, malhelpante instaladon " +"al aŭ malinstaladon de la implicita instala medio de la interpretilo, kaj " +"sugestante al la uzanton :ref:`virtualan medion `." + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "Terminaro" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" +"Kelkaj terminoj uzitaj en tiu specifo havas plurajn signifojn tra " +"kuntekstoj. Por klareco, ĉi tiu specifo uzas la jenajn terminojn jene:" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "distribuo" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" +"Kolekto de diversaj specoj de programoj, ideale fasonitaj kohere, inkluzive " +"de (en kuntekstoj rilataj al ĉ tiu dokumento) la Python-interpretilo mem, " +"programoj verkitaj en Python, kaj programoj verkitaj en aliaj lingvoj. Tio " +"estas la senco en la terminoj «Linux-distribuo» aŭ «Berkeley-" +"Programdistribuo» (BSD)." + +#: ../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 "" +"Distribuo povas esti memstara mastruma sistemo (OS), kiel Debian, Fedora aŭ " +"FreeBSD. Ĝi ankaŭ povas esti plustavola distribuo instalita sur mastruman " +"sistemon, kiel Homebrew aŭ MacPorts." + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" +"La termino «distribuo» havas alian signifon en Python-pakada kunteksto: " +"fontan aŭ duuman distribuan pako de iu Python-lingva programo, en la senco " +"de ``setuptools.dist.Distribution`` aŭ «fonta distribuo». Por eviti " +"konfuzon, por la Python-pakada senco, ĉi tiu dokumento uzas la plenan " +"terminon «distribua pako» aŭ simple «pako» (vidu ĉi-sube)." + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" +"La provizanto de distribuo – la teamo aŭ firmao kolektanta, eldonanta, kaj " +"laŭbezone modifanta la programaron – estas ĝia **distribuanto**." + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "pako" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" +"Unuo de programo instalebla kaj uzebla en Python. Python-specifa pakilo ofte " +"nomas ĝin :term:`distribua pako ` aŭ simple " +"«distribuo»; la familiara mallongigo «pako» estas uzata laŭ la nomo Python-" +"Pakindekso." + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" +"Ĉi tiu dokumento ne uzas la terminon «pako» en la senco de importebla nomo " +"enhavanta Python-modulojn, kvankam ofte distribua pako ja konsistas el unu " +"samnoma importebla pako." + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "Python-specifa pakadministrilo" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" +"Ilo por instali, ĝisdatigi kaj/aŭ malinstali Python-pakojn konforme al " +"normoj pri pakado de Python. La plej populara Python-specifa pakadministrilo " +"estas pip_; jen aliaj ekzemploj: `la malnova komando Easy Install `_ kaj rekta uzo de la komando ``setup.py``." + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" +"(Notu, ke la komando ``easy_install`` estis forigita en versio 52 de " +"setuptools, eldonita je la 23a de Januaro 2021.)" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" +"(Conda_ estas speciala kazo, ĉar la komando ``conda`` povas instali multe " +"pli ol nur Python-pakojn, iel simile al distribuaj pakadministriloj. Ĉar la " +"komando ``conda`` nur funkcias en Conda-kreita medio, la plejparto de la " +"koncernoj en ĉi tiu dokumento ne validas por ``conda`` funkcianta kiel " +"Python-specifa pakadministrilo.)" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "distribupakadministrilo" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" +"Ilo por instali, ĝisdatigi, kaj/aŭ malinstali pakojn de distribuo en " +"instalita distribuo, kapabla instali Python-pakojn kaj ne-Python-ajn pakojn, " +"kun sia propra datenbanko de instalitaj programoj ne rilata al " +"la :ref:`datenbanko de instalitaj distribuoj `. Jen kelkaj ekzemploj: ``apt``, ``dpkg``, ``dnf``, ``rpm``, " +"``pacman`` kaj ``brew``. Grave, se iu pako estis instalita de la " +"pakadministrilo de la distribuo, do malinstalado aŭ ĝisdatigado de tiu pako " +"tiel, kiel Python-specifa pakadministrilo funkcius, kaŭzus malkoherecon je " +"la pakadministrilo de la distribuo." + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" +"Ĉi tiu dokumento ankaŭ uzas terminojn kiel «eksteran pakadministrilon» aŭ " +"«sistema pakadministrilon» signifante la pakadministrilon de la distribuo en " +"kelkaj kuntekstoj." + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "ombri" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "Jen duobla specifo." + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/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 "" +"Due, ĝi reguligas, ke dum instalado de pako al la malloka kunteksto de " +"interpretilo (aŭ al nemarkita interpretilo, aŭ se oni superregas la " +"markadon), **Python -specifa pakadministrilo modifu aŭ forviŝu dosierojn nur " +"en la dosierujoj de la sysconfig-skemo, en kiu ĝi kreus la dosierojn**. Tio " +"permesas al distribuanto de Python-interpretilo starigi du dosierujojn – unu " +"por siaj propre mastrumataj pakoj, la alia por nemastrumataj pakoj " +"instalitaj de la uzanto –, certigante, ke instalado de nemastrumata pako ne " +"forviŝos (nek superskribos) dosierojn mastrumatajn de la ekstera " +"pakadministrilo." + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "Marki interpretilon kiel uzantan eksteran pakadministrilon" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" +"Antaŭ ol Python-specifa instalilo (kiel pip – ne ekstera ilo kiel apt) " +"instalas pakon en Python-kuntekston, ĝi implicite kontrolu la jenon:" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" +"Ĉu ĝi ruliĝas ekster virtuala medio? Ĝi povas determini tion per " +"``sys.prefix == sys.base_prefix``." + +#: ../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 "" +"Ĉu ekzistas dosiero ``EXTERNALLY-MANAGED`` en la dosierujo identigita de " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" +"Se ambaŭ kondiĉoj veras, la instalilo ĉesu, sciigante pri la eraro, ke " +"instalado de pako en la dosierujon de ĉi tiu Python-interpretilo ne eblas " +"ekster virtuala medio." + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" +"La instalilo provizu meĥanismon por superregi tiajn regulojn, ekzemple per " +"flago ``--break-system-packages``. Tia opcio ne estu apriora kaj indiku, ke " +"ĝia uzo estas danĝera." + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" +"La dosiero ``EXTERNALLY-MANAGED`` estas INI-stila metadatena dosiero, kiu " +"estu analizebla de la norma biblioteka modulo configparser_. Se la dosiero " +"estas analizebla per ``configparser.ConfigParser(interpolation=None)`` " +"uzante UTF-8, kaj ĝi enhavas sekcion ``[externally-managed]``, do la " +"instalilo serĉu erarmesaĝon specifitan en la dosiero kaj eligu ĝin kiel " +"parton de la eraro. Se la unua elemento de la opo " +"``locale.getlocale(locale.LC_MESSAGES)``, t.e. la lingvokodo, ne estas " +"``None``, ĝi serĉu la erarmesaĝon kiel la valoron de ŝlosilo nomita `Error-" +"`` sekvita de la lingvokodo. Se tiu ŝlosilo ne ekzistas, kaj se la " +"lingvokodo enhavas substrekon aŭ streketon, ĝi serĉu ŝlosilon nomitan " +"``Error-`` sekvita de la parto de la lingvokodo antaŭ la substreko aŭ " +"streketo. Se ĝi ne povas trovi ambaŭ, aŭ se la lingvokodo estas ``None``, ĝi " +"serĉu ŝlosilon simple nomitan ``Error``." + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" +"kio provizas utilajn kaj distribuo-rilatajn informojn al uzanto provanta " +"instali pakon. Oni ankaŭ povas provizi tradukaĵojn en la sama dosiero:" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" +"En kelkaj kazoj, kiel ekzemple unuprograma ujo-diskokopio ne ĝisdatigota " +"post kreo, distribuanto povas elekti ne inkluzivi dosieron ``EXTERNALY-" +"MANAGED``, por ke uzanto povas instali tion ajn, kion oni ŝatas (same kiel " +"la hodiaŭa sperto) sen malaŭtomate malaktivigi tiun regulon." + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "Skribi al nur la cela skemo ``sysconfig``" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" +"Ordinare Python-pakinstalo instalas al dosierujo en skemo liverita de la " +"norma biblioteka pako ``sysconfig``. Ofte tio estas la skemo " +"``sysconfig.get_default_scheme()``, sed oni povas alimaniere agordi tion " +"(ekz. per ``pip install --user``)." + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" +"Se la instalilo ombras ekzistantan instalon dum ĝisdatigado, ni rekomendas, " +"ke ĝi montru averton post la rulo." + +#: ../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 "" +"Se la instalilo instalas al loko ekster ``sysconfig``-skemo (ekz. ``pip " +"install --target``), do ĉi tiu subsekcio ne estas efektiva." + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "Rekomendoj pri distribuoj" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" +"Jen nedeviga paragrafo priskribanta la bonan praktikon, kiu niaopinie " +"distribuoj observu, se specifa kialo mankas." + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "Marku la instalaĵon kiel ekstere mastrumatan" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" +"Distribuo kreu dosieron ``EXTERNALLY-MANAGED`` en sia dosierujo ``stdlib``." + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "Gvidu uzantojn al virtualaj medioj" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" +"Konsideru disponigi pipx_, ilon por instali Python-programojn, kaj sugesti " +"ĝin en la eraro. pipx aŭtomate kreas virtualan medion por unu solan " +"programon, kio estas multe pli bona port tiuj uzantoj, kiuj deziras instali " +"iun Python-programon (kiun la distribuo ne disponigas) sed ne estas Python-" +"uzantoj mem. Pakado de pipx en la distribuo evitas la ironion instrui " +"uzantojn ruli ``pip install --user --break-system-packages pipx`` por " +"*eviti* rompi sistemajn pakojn. Konsideru dependigi de pipx la Python-pakon/" +"medion de via distribuo por ordinaraj uzantoj (ekz. ``python3`` ĉe Fedora aŭ " +"``python3-full`` ĉe Debian)." + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "Retenu la markan dosieron en uja bildo" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" +"Distribuo, kiu provizas oficialan bildon por unuprograma ujo (ekz., Docker-" +"bildo) retenu la dosieron ``EXTERNALLY-MANAGED``, prefere tiel, ke ĝisdatigo " +"de la bildo (kiel ``RUN apt-get dist-upgrade``) ne forigos la dosieron." + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "Kreu apartajn distribuan kaj lokan dosierujojn" + +#: ../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/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" +"Ekzemple, Fedora kaj Debian (kaj iliaj idoj) realigas tiun disigon uzante ``/" +"usr/local`` por loke instalitaj pakoj kaj ``/usr`` por distribuo-instalitaj " +"pakoj. Fedora uzas ``/usr/local/lib/python3.x/site-packages`` kontraste al " +"``/usr/lib/python3.x/site-packages``. (Debian uzas ``/usr/local/lib/python3/" +"dist-packages`` kontraste al ``/usr/lib/python3/dist-packages`` kiel ekstra " +"apartiga tavolo el loke tradukita Python-interpretilo: se oni konstruus kaj " +"instalus CPython en ``/usr/local/bin``, ĝi serĉus ``/usr/local/lib/python3/" +"site-packages``, kaj Debian volas certigi, ke pakoj instalitaj per la loke " +"konstruita interpretilo ne ĉeestos en ``sys.path`` por la interpretilo de la " +"distribuo.)" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" +"Notu, ke la distingo inter ``/usr/local`` kaj ``/usr`` similas al la " +"maniero, kiel la media variablo ``PATH`` tipe inkluzivas ``/usr/local/bin:/" +"usr/bin``, kaj ekster-distribua programo tipe apriore instaliĝas al ``/usr/" +"local``. Tiun distingon `rekomendas la Dosiersistema Hierarĥia Normo " +"`__." + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" +"La alia estas aranĝi ŝanĝadon de la implicita skemo ``sysconfig`` dum " +"konstruado de pako, kompare al rulado en instalita sistemo. La adapta " +"meĥanismo de ``sysconfig`` el bpo-43976_ faciligos tion (kiam ĝi estas " +"akceptita kaj realigita): via pakilo agordu median variablon aŭ alian " +"detekteblaĵon, kaj difiun funkcion ``get_preferred_schemes`` liverantan " +"alian skemon dum konstruado de pako. Poste oni povas simple uzi ``pip " +"install`` kiel parto de la pakado de via distribuo." + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" +"Ni proponas aldoni flagon ``--scheme=…`` por ruli pip kontraŭ iu specifa " +"skemo. (Vidu `Notojn pri Realigo `_ ĉi-subajn por " +"priskribo pri kiel pip aktuale determinas skemon.) Post la disponigo de tiu " +"flago, por loka testado kaj eble for reala pakado, oni povos ruli ion " +"similan al ``pip install --scheme=posix_distro`` por ekspliciti instali " +"pakon al la loko de la distribuo (ignorante ``get_preferred_schemes``). Oni " +"povos ankaŭ, se tio absolute necesas, uzi ``pip uninstall --" +"scheme=posix_distro`` por uzante pip malistali pakon el la sisteme " +"mastrumata dosierujo." + +#: ../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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" +"La avantaĝo de aŭtomatigo de tio (ignorante la markodosieron en la konstrua " +"medio kaj igante``get_preferred_schemes`` aŭtomate liveri la skemon de via " +"distribuo) estas, ke ordinara ``pip install`` funkcios dum konstruado de " +"pako, tiel ke nemodifita konstruprogrameto far la originalaj aŭtoroj, kiu " +"interne alvokas ``pip install``, ĝenerale taŭgos. Kompreneble, vi povus " +"alternative simple certigi, ke via pakada procezo ĉiam alvoku ``pip install " +"--scheme=posix_distro --break-system-packages``, kio ankaŭ sufiĉus." + +#: ../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 "" +"La plej bona maniero dependas multe de la konvencioj kaj meĥanismoj de via " +"distribuo pri pakado." + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" +"Simile, la ``sysconfig``-dosierlokoj ne por importebla Python-kodo – t.e. " +"``include``, ``platinclude``, ``scripts`` kaj ``data`` – ankaŭ havu du " +"variantojn, unu por programoj pakitaj de la distribuo, la alia por loke " +"instalitaj programoj. La distribuo estu agordita tiel, ke ambaŭ estas " +"uzeblaj. Ekzemple, ordinara distribuo observanta la Dosiersistemo-Hierarĥian " +"Normon (FHS) uzas ``/usr/local/include`` por la ``include`` de la implicita " +"skemo kaj ``/usr/include`` por ĉapoj pakitaj de la distribuo, kaj ambaŭ " +"troviĝas en la serĉlisto de la tradukilo. Ĝi uzas ``/usr/local/bin`` por la " +"``scripts`` de la implicita skemo kaj ``/usr/bin`` por enirpunktoj pakitaj " +"de la distribuo, kaj ambaŭ troviĝas en ``$PATH``." + +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" +msgstr "Notoj pri Realigo" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" +"Jen nedeviga paragrafo enhavanta notojn pri la specifo kaj eblaj realigoj." + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" +"Aktuale (je Majo 2021), pip ne rekte eblias elektadon de cela ``sysconfig``-" +"skemo, sed ĝi havas tri manierojn serĉi skemon dum instalado:" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "``pip install``" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" +"Alvokas ``sysconfig.get_default_scheme()``, kiu estas normale (en la apriora " +"CPython kaj en la plejparto de distribuoj) sama kiel " +"``get_preferred_scheme('prefix')``." + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "``pip install --prefix=/iu/loko``" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "Alvokas ``sysconfig.get_preferred_scheme('prefix')``." + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "``pip install --user``" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "Alvokas ``sysconfig.get_preferred_scheme('user')``." + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" +"Fine, ``pip install --target=/iu/loko`` skribas rekte al ``/iu/loko`` sen " +"serĉado de ajna skemo." + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" +"Fedora nuntempe havas `flikaĵon por ŝanĝi la aprioran instalan lokon dum " +"rulado ekster rpmbuild `__ , kio realigas du-tutsistem-dosierujan " +"meĥanismon. Tio estas koncepte tia hoko, kian celis bpo-43976_, krom ke ĝi " +"estas flikaĵo sur ``distutils``, ne ŝanĝita ``sysconfig``-skemo." + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "Kopirajtoj" + +#: ../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 "" +"Jen dokumento, kiu estas publika havaĵo aŭ sub la licenco CC0-1.0-Universal, " +"laŭ via prefero." + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "Junio 2022: Ĉi tiu specifo estis aprobita per :pep:`668`." + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +#, fuzzy +#| msgid "This specification was originally defined in :pep:`753`." +msgid "This specification was originally defined in :pep:`592`." +msgstr "Ĉi tiu specifo estis originale difinita en :pep:`753`." + +#: ../source/specifications/file-yanking.rst:14 +#, fuzzy +#| msgid "" +#| ":pep:`740` includes changes to the HTML and JSON index APIs. These " +#| "changes are documented in the :ref:`simple-repository-api` " +#| "under :ref:`simple-repository-api-base` and :ref:`json-serialization`." +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" +":pep:`740` inkluzivas ŝanĝojn pri la indeksaj API-oj en HTML kaj JSON. Tiuj " +"ŝanĝoj estas priskribitaj en :ref:`simple-repository-api` sub :ref:`simple-" +"repository-api-base` kaj :ref:`json-serialization`." + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" +"Hiperligo en la simpla deponejo **POVAS** havi atributon ``data-yanked``, " +"kies valoro povas esti malplena aŭ esti ajna signoĉeno. La ĉeesto de " +"atributo ``data-yanked`` **ESTU** interpretata kiel indiko, ke la dosiero " +"montrata de la hiperligo estas fortirita kaj ĝenerale ne elektata de " +"instalilo krom specifaj kondiĉoj." + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" +"La valoro de la atributo ``data-yanked``, se ĝi ekzistas, estas arbitra " +"teksto pri la kialo de la fortiro. Ilo uzanta la simplan deponejan API " +"**POVAS** montri tiun tekston al uzanto." + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" +"La atributo ``yanked`` ne estas senŝanĝebla kaj povas malestiĝi (aŭ " +"reestiĝi). Tial, uzanto de API **DEVAS** povi pritrakti malfortiritan (aŭ eĉ " +"refortiritan) dosieron." + +#: ../source/specifications/file-yanking.rst:40 +msgid "Installers" +msgstr "Instaliloj" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" +"La dezirinda sperto por uzanto estas, ke post fortiro de dosiero, kiam homo " +"rekte provas instali fortiritan dosieron, tio malsukcesas kvazaŭ la dosiero " +"estus forviŝita. Tamen, kiam homo faris tion antaŭtempe, kaj nun komputilo " +"meĥanike sekvas la originalan ordon instalante la nun fortiritan dosieron, " +"do tio funkcios kvazaŭ la dosiero ne estus fortirita." + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" +"Instalilo **DEVAS** ignori fortiritan eldonon, se iu nefortirita eldono " +"plenumas la limigojn de elektado. Instalilo **POVAS** rifuzi uzi fortiritan " +"eldonon, eĉ se tio signifas, ke la limigoj ne estas plenumeblaj. Realigo " +"**ELEKTU** regulojn observantajn la ĉi-supran intencon malhelpantan «novan» " +"dependecon al foritira eldono aŭ dosiero." + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" +"La instalilo determinu sian precizan konduton laŭ sia fasonado. Tamen, jen " +"du sugestataj manieroj:" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "Speguloj" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" +"Spegulo povas ĝenerale pritrakti fortiritajn dosierojn laŭ unu el la jenaj " +"du manieroj:" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" +"Ĝi povas simple plene ignori ilin en la simpla deponeja API, provizante " +"vidon de la deponejo nur de «aktivaj», nefortiritaj dosieroj." + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" +"Ĝi povas inkluzivi fortiritajn dosierojn kaj ankaŭ speguli la atributon " +"``data-yanked``." + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" +"Speguloj **DEVAS NE** speguli fortiritan dosieron sen spegulado de la " +"atributo ``data-yanked`` pri ĝi." + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "Patroneo ``glob``" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" +"Kelkaj normoj de PyPA, ekz. :ref:`license-files en pyproject.toml `, akceptas *``glob``-patroneojn* – signoĉenojn " +"enhavantan ĵokerojn kaj signo-intervalojn, kiujn oni povas kompari kun " +"dosiernomoj kaj dosierlokoj. Ĉi tiu normo difinas la validecon de patroneoj " +"kaj kiel oni pritraktu ilin." + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "Validaj patroneoj ``glob``" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" +"Por la celoj de PyPA, *valida ``glob``-patroneo* DEVAS esti signoĉeno, kiun " +"oni povas kompari kun eroj en dosiersistemo, laŭ la jena difino:" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" +"Literoj, ciferoj, substrekoj (``_``), streketoj (``-``) kaj punktoj (``.``) " +"DEVAS prezenti sin laŭlitere." + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "Dosierloko-apartigilo DEVAS esti la suprenstreko (``/``)." + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" +"Patroneoj ankaŭ temas pri *relativaj dosierlokoj*. Ekzemple, " +"en :file:`pyproject.toml`, patroneo estas relativa al la dosierujo enhavanta " +"tiun dosieron. Tial, la komenca suprenstreko DEVAS NE ekzisti." + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "Indikilo de patra dosierujo (``..``) DEVAS esti NE uzita." + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" +"Ajna skribsigno aŭ sinsekvo de skribsignoj ne diskutataj de ĉi tiu specif ne " +"validas. Projekto DEVAS NE uzi tian valoron. Ilo uzanta ``glob``-patroneojn " +"MALAKCEPTU nevalidan valoron, sciigante pri eraro." + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" +"Eksplicita dosierloko (ekz. :file:`LICENSE`) estas valida patroneo, kio " +"signifas ke ĝi estas difinebla." + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "Iloj uzantaj ``glob``-patroneoj:" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" +"DEVAS pritrakti ĉiun valoron kiel patroneon kaj DEVAS sciigi eraron, se la " +"patroneo enhavas nevalidan patronean sintakson." + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" +"DEVAS sciigi eraron, se iu uzanto-specifita patroneo ne kongruas kun " +"minimume unu dosiero." + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "Ekzemploj de validaj ``glob``-patroneoj:" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "Ekzemploj de nevalidaj ``glob``-patroneoj:" + +#: ../source/specifications/glob-patterns.rst:74 +msgid "Reference implementation in Python" +msgstr "Referenca realigo en Python" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" +"Oni povas uzi la modulon :mod:`glob` en la norma biblioteko de Python por la " +"plejparto de kontrolado de kongrueco de patroneo kun ero en dosiersistemo. " +"Tamen, necesas plu kontroli validecon." + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "Jen simpla referenca realigo:" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "PyPA-specifoj" + +#: ../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 "" +"Jen listo de aktuale aktivaj specifoj pri kunfunkcipovo mastrumataj de la " +"Python-Pakada Aŭtoritato. La procedo pri ĝisdatigado de tiujn normoj kaj " +"proponado de novaj normoj priskribiĝas ĉe `pypa.io `__." + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "Indekse gastigitaj atestoj" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "Ĉi tiu specifo estis originale difinita en :pep:`740`." + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" +":pep:`740` inkluzivas ŝanĝojn pri la indeksaj API-oj en HTML kaj JSON. Tiuj " +"ŝanĝoj estas priskribitaj en :ref:`simple-repository-api` sub :ref:`simple-" +"repository-api-base` kaj :ref:`json-serialization`." + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "Ŝanĝoj pri alŝuta finpunkto" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" +"La «malnova» alŝuta API ne estas normigita. Vidu `la dokumentaron de la " +"Alŝuta API de PyPI `_ pri alŝutado de " +"atestoj." + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "Atestaj objektoj" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" +"Atesta objekto estas JSON-objekto kun pluraj postulataj ŝlosiloj. Programo " +"aŭ subskribanto povas inkluzivi ekstrajn ŝlosilojn, se ĉiuj eksplicite " +"menciitaj ŝlosiloj ekzistas. Jen pseŭdokodo pri la postulata aranĝo de " +"atesta objekto." + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" +"Plena datenmodelo de ĉiu objekto en ``transparency_entries`` troviĝas en " +"la :ref:`apendico `. Atesta objekto **INKLUZIVU** unu aŭ plurajn " +"travidebleco-protokolerojn kaj **POVAS** inkluzivi pliajn ŝlosilojn pri " +"aliaj fontoj de tempo de subskribo (kiel Tempindika-Aŭtoritato " +"laŭ :rfc:`3161` aŭ servilo `Roughtime `__)." + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" +"Atesta objekto havas version; ĉi tiu PEP specifas version 1. Ĉiu versio " +"estas ligita al unu ĉifraro por minimumigi nenecesan ĉifran facilmovecon. " +"Jen la ĉifraro de versio 1:" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" +"Atestiloj specifiĝas kiel atestiloj X.509, kaj observas la profilon " +"en :rfc:`5280`." + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" +"La mesaĝa subskriba algoritmo estas ECDSA, kun la kurbo P-256 por publikaj " +"ŝlosiloj kaj SHA-256 kiel la ĉifra haketaĵa funkcio." + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" +"Estonta PEP povos ŝanĝi tiun ĉifraron (kaj la formon de la atesta objekto) " +"elektante novan versian numeron." + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "Atesta aserto kaj generado de subskribo" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" +"La *atesta aserto* estas la fakta aserto ĉifre subskribita per la atesta " +"objekto (``envelope.statement``)." + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" +"La atesta aserto estas kodita kiel `entuta aserta objekto de versio 1 " +"`__, en formo JSON. Dum seriigo, la aserto estas pritraktata " +"kiel opaka duumaĵo, sen bezono de kanonigo." + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" +"Aldone al la limigoj pri entuta aserto de versio 1, la atesta aserto estas " +"limigita jene:" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "La entuta ``subject`` **DEVAS** enhavi nur unu temon." + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" +"``subject[0].name`` estas la dosiernomo de la distribuo, kiu **DEVAS** esti " +"valida dosiernomo por :ref:`fonta distribuo ` " +"or :ref:`wheel-distribuo `." + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" +"``subject[0].digest`` **DEVAS** enhavi SHA-256-haketaĵon. Aliaj haketaĵoj " +"**POVAS** ankaŭ ĉeesti. La haketaĵoj **DEVAS** esti deksesumaj signoĉenoj." + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "La jenaj valoroj de ``predicateType`` estas subtenataj:" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" +"La signaturo pri tiu aserto estas konstruita per `la subskriba protokolo " +"DSSE v1 `__, kun ``PAYLOAD_TYPE`` de ``application/vnd.in-toto+json`` " +"kaj ``PAYLOAD_BODY`` de la JSON-kodita aserto ĉi-supra. Nenia " +"alia``PAYLOAD_TYPE`` estas permesata." + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "Originpruvaj objektoj" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" +"La indekso provizos alŝutitajn atestojn kune kun metdatenoj por konfirmi " +"ilin en la formo de JSON-seriigitaj objektoj." + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" +"Tiuj *originpruvaj objektoj* disponiĝas per kaj la Simpla Indeksa API kaj " +"JSON-baza Simpla API ĉi -supraj, kaj havas la jenan aranĝon:" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "aŭ, kiel pseŭdokodo:" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" +"``version`` estas ``1``. Kiel atestaj objektoj, originpruvaj objektoj havas " +"versiojn, kaj ĉi tiu PEP nur difinas la version ``1``." + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" +"``attestation_bundles`` estas **deviga** JSON-listo, enhavanta unu aŭ pluraj " +"«faskoj» da atestoj. Ĉiu fasko respondas al subskriba identeco (kiel Fidata " +"Eldona Identeco) kaj enhavas unu aŭ plurajn atestajn objektojn." + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" +"Kiel notite en la modelo ``Publisher``, ĉiu objekto " +"``AttestationBundle.publisher`` estas specifa al sia Fidata Eldonanto, sed " +"devas inkluzivi minimume la jenon:" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" +"Ŝlosilo ``kind``, kiu **DEVAS** esti JSON-signoĉeno unike identigantan la " +"specon de Fidata Eldonanto." + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" +"Ŝlosilo ``claims``, kiu **DEVAS** esti JSON-objekto enhavanta ajnajn " +"kunteksto-specifajn asertojn retenatajn de la indekso dum aŭtentikigo per " +"Fidata Eldonanto." + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" +"Ĉiuj aliaj ŝlosiloj en la objekto publisher estas specifaj al la eldonanto." + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" +"Ĉiu listo de atestaj objektoj estas superaro de la listo ``attestation`` " +"donita de la alŝutinto per la kampo ``attestations`` dum alŝutado, " +"laŭ :ref:`upload-endpoint` kaj :ref:`changes-to-provenance-objects`." + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "Ŝanĝoj al originpruvaj objektoj" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" +"Originpruvaj objektoj *ne* estas neŝanĝeblaj kaj povas ŝanĝiĝi dum tempo. " +"Jen neplena listo de kialoj por ŝanĝi originpruvajn objektojn:" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" +"Aldono de novaj atestoj far jam ekzistanta subskriba identeco: la indekso " +"**POVAS** permesi plian ateston far jam ekzistanta subsigriba identeco, " +"ekzemple novan atestan version por jam alŝutinta dosiero." + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "Konfirmado de atestado" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" +"Konfirmi atestan objekton pri distribua dosiero postulas konfirmadon de ĉiuj " +"el la jeno:" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" +"``version`` estas ``1``. La konfirmilo **DEVAS** malakcepti ajnan alian " +"version." + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" +"``verification_material.certificate`` estas valida subskriba atestilo " +"eldonita de *apriore* fidata aŭtoritato (kiel fidradiko jam ekzistanta en la " +"kliento)." + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" +"``verification_material.certificate`` identigas taŭgan subskriban temon kiel " +"la maŝinan identecon de la Fidata Eldonanto eldoninta la pakon." + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" +"``envelope.signature`` estas valida subskribo por ``envelope.statement`` " +"respondanta al ``verification_material.certificate`` laŭ la `subskriba " +"protokolo v1 DSSE `__." + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "Apendico: Datenmodeloj por Eroj en Travidebleco-Protokolo" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" +"Jen apendico enhavanta pseŭdokodajn datenmodelojn por protokoleroj de " +"travidebleco-protokolo en atesta objekto. Ĉiu protokolero estas fonto de " +"subskribita inkluziva tempo kaj estas konfirmebla konektite aŭ senkonekte." + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "Enkorpigitaj programetaj metadatenoj" + +#: ../source/specifications/inline-script-metadata.rst:7 +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 "" +"Jen specifo difinanta metadatenan formon enkorpigeblan en unudosiera Python-" +"programo por helpi lanĉilojn, programadajn mediojn kaj aliajn eksterajn " +"ilojn, kiuj interagas kun tiaj programoj." + +#: ../source/specifications/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" +"Jen specifo difinanta metadatenan komentan blokan formon (parte inspirita de " +"`direktivo de reStructuredText `__)." + +#: ../source/specifications/inline-script-metadata.rst:20 +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 "" +"Ajna Python-programo povas havi supranivelajn komentajn blokojn, kiuj DEVAS " +"komenciĝi per la linio ``# /// TIPO``, en kiu ``TIPO`` determinas kiel " +"pritrakti la enhavon. Alivore: unu ``#``, sekvita de unu spaceto, sekvita de " +"tri suprenstrekoj, sekvita de unu spaceto, sekvita de la tipo de " +"metadatenoj. Bloko DEVAS finiĝi per la linio ``# ///``. Alivorte: unu ``#``, " +"sekvita de unu spaceto, sekvita de tri suprenstrekoj. La ``TIPO`` DEVAS nur " +"konsisti el Askiaj literoj, ciferoj kaj streketoj." + +#: ../source/specifications/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" +"Ĉiu linio inter tiuj du linioj (``# /// TYPE`` kaj ``# ///``) DEVAS esti " +"komento komenciĝanta per ``#``. Se ekzistas signoj post la ``#``, do la unua " +"signo DEVAS esti spaceto. La enkorpigita enhavo konsistas el la linio sen la " +"unuaj du signoj (se la dua signo estas spaceto) aŭ el nur la unua signo (se " +"ne, kio implicas, ke la linio konsistas el nur unu ``#``)." + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" +"Oni preferu la finan lineon ``# ///``, kiam la sekva linio ne estas valida " +"linio de enkorpigita enhavo laŭ la ĉi-supra priskribo. Ekzemple, la jeno " +"estas unu plene valida bloko:" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" +"Komenca linio DEVAS NE ĉeesti inter alia komenca linio kaj ĝia fina linio. " +"Tiukaze ilo POVAS sciigi pri eraro. Nefermita bloko DEVAS esti ignorita." + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" +"Se ekzistas pluraj komentaj blokoj de la sama ``TYPE``, ilo DEVAS sciigi pri " +"eraro." + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" +"Ilo leganta enmetitajn metadatenojn POVAS respekti la norman signokodo-" +"deklaron de Python. Se ilo ne faras tion, ĝi DEVAS pritrakti la dosieron " +"kiel UTF-8." + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" +"Jen la kanona regula esprimo, kiun oni POVAS uzi por sintakse analizi la " +"metadatenojn:" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" +"En cirkonstancoj kie ekzistas diferenco inter la teksta specifo kaj la " +"regula esprimo, la teksta specifo havas prioritaton." + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" +"Ilo DEVAS NE legi el metadatena bloko de tipo ne normigita de ĉi tiu specifo." + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "Tipo ``script``" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" +"La unua tipo de metadatena bloko nomiĝas ``script``, kiu enhavas la " +"programetajn metadatenojn (datenojn pri dependeco kaj agordoj de iloj)." + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" +"Tiu dokumento POVAS inkluzivi la supranivelajn kampojn ``dependencies`` kaj " +"``requires-python``, kaj POVAS nedevige inkluzivi tabelon ``[tool]``." + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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 "" +"La tabelo ``[tool]`` POVAS esti uzata de ajna ilo, programrulilo aŭ ne, por " +"agordi konduton. Ĝia semantiko estas sama kiel :ref:`la tabelo [tool] en " +"pyproject.toml `." + +#: ../source/specifications/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "Jen la supranivelaj kampoj:" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" +"``dependencies`` : Listo de signoĉenoj specifantaj la rultempajn dependecojn " +"de la programo. Ĉiu ero DEVAS esti valida :ref:`dependeco-specifilo " +"`." + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" +"``requires-python``: Signoĉeno specifanta la Python-versio(j)n kun kiu(j) la " +"programo kongruas. La valoro de tiu kampo devas esti :ref:`versio-specifilo " +"`." + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" +"Programeto-rulilo DEVAS sciigi pri eraro, se la specifita ``dependencies`` " +"ne estas plenumebla. Programeto-rulilo SCIIGU pri eraro, se troviĝas neniu " +"versio de Python plenumanta la specifitan ``requires-python``." + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "Jen ekzemplo de programeto kun enkorpigitaj metadatenoj:" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "Jen ekzemplo de kiel legi la metadatenojn sur Python 3.11 aŭ pli nova." + +#: ../source/specifications/inline-script-metadata.rst:151 +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 "" +"Ofte ilo modifas dependecojn kiel padadministrilo aŭ aŭtomata ĝisdatigilo de " +"dependecoj en kontinua integrado. Jen malneta ekzemplo de modifado de la " +"enhavo per la `biblioteko `__ ``tomlkit``." + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" +"Notu, ke tiu ekzemplo uzis bibliotekon konservantan TOML-aranĝon. Tio ne " +"estas postulata por modifado, sed utilas." + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "Jen ekzemplo de kiel legi fluon da arbitraj metadatenaj blokoj." + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "Rekomendoj" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" +"Ilo, kiu administras diversajn versiojn de Python, uzu la plej novan version " +"de Python kongruan kun la metadateno ``requires-python`` de la programeto, " +"se ĝi ekzistas." + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "Oktobro 2023: Ĉi tiu specifo estis kondiĉe aprobita per :pep:`723`." + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" +"Januaro 2024: Per ŝanĝoj al :pep:`723`, la nomo de la metadatena bloko " +"``pyproject `` ŝanĝiĝis al ``script``, kaj la tabelo ``[run]`` estis " +"forigita, estigante la ŝlosilojn ``dependencies`` kaj ``requires-python`` " +"supranivelaj. Cetere, la specifo ne plu estas provizora." + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" +":pep:`639` difinis novan valoron al :ref:`la ŝlosilo license en " +"pyproject.toml `, kaj aldonis " +"respondantan :ref:`kampon License-Expression en kernaj metadatenoj `. Ĉi tiu normo difinas la validajn " +"licencesprimojn." + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" +"Licenco povas esti difinita kiel teksto, kiu estas valida " +"SPDX-:term:`licencesprimo `, laŭ la `normo SPDX " +"`__, aŭ Versio 2.2 aŭ pli nova kongrua versio." + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "Licencesprimo povas uzi la jenajn licenco-identigilojn:" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" +"Ajna mallongforma licenca identigilo en la `SPDX License List " +"`__, versio 3.17 aŭ ajna pli nova kongrua versio." + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" +"La propra(j) signoĉeno(j) ``LicenseRef-[identigilo]``en kiu ``[identigilo]`` " +"estas unika signoĉeno konsistanta el literoj, ciferoj, ``.`` kaj/aŭ ``-``, " +"identiganta(j) licencojn ne inkluzivitajn en la licencolisto de SPDX. La " +"propraj identigiloj devas observi `paragrafon 10.1 `__ de la " +"normo SPDX de la donita versio de la normo." + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "Ekzemploj de validaj licenco-esprimoj:" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "Ekzemploj de nevalidaj licenco-esprimoj:" + +#: ../source/specifications/name-normalization.rst:3 +msgid "Names and normalization" +msgstr "Nomoj kaj normigo" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" +"Ĉi tiu specifo difinas la formon de nomoj de pakoj kaj ekstraĵoj. Ĝi ankaŭ " +"priskribas normigon de nomoj, kiun oni faru antaŭ serĉado kaj komparado." + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "Nomformo" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" +"Valida nomo konsistas nur el Askiaj literoj, ciferoj, punkto, substreko kaj " +"streketo. Ĝi devas komenciĝi kaj finiĝi per litero aŭ cifero. Alivorte, " +"valida projekta nomo devas konformi al la jena regula esprimo (rulu " +"kun :py:data:`re.IGNORECASE`)::" + +#: ../source/specifications/name-normalization.rst:26 +msgid "Name normalization" +msgstr "Normigo de nomo" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" +"Oni minuskligu la nomon kaj anstataŭigu sinsekvon de la signoj ``.``, ``-``, " +"aŭ ``_`` per unu signo ``-``. Oni povas fari tion en Python per la modulo " +"``re``:" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "Tio signifas, ke la jenajn nomoj estas ĉiuj ekvivalentaj:" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "``afabla-bardo`` (normigita formo)" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "``Afabla-Bardo``" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "``AFABLA-BARDO``" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "``afabla.bardo``" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "``afabla_bardo``" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "``afabla--bardo``" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "``AfAbLa-._.-bArDo`` (*aĉa* maniero skribi nomon, sed valida)" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" +"Septembro 2015: La specifo de normigo de nomoj estis aprobita per :pep:`503 " +"<503#normalized-names>`." + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" +"Novembro 2015: La specifo de validaj nomoj estis aprobita per :pep:`508 " +"<508#names>`." + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "Platformo-kongruecaj etikedoj" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" +"Per etikedoj pri platforma kongrueco, konstruilo povas marki distribuon " +"kongrua kun specifitaj platformoj, kaj instalilo povas scii, kiuj distribuoj " +"kongruas kun la aktuala sistemo." + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "La etikeda formo estas ``{python tag}-{abi tag}-{platform tag}``." + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "python etikedo" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "«py27», «cp33»" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "«cp32dmu», «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 "" +"Ekzemple, la etikedo ``py27-none-any`` signifas kongruecon kun Python 2.7 " +"(ajna realigo de Python 2.7) sen postuloj pri ABI, sur ajna platformo." + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" +"La konstruita pakformo ``wheel`` inkluzivas tiujn etikedojn en dosiernomoj " +"laŭ la formo ``{distribuo}-{versio}(-{konstruetikedo})?-{pythonetikedo}-" +"{abietikedo}-{platformetikedo}.whl``. Alia pakformo povas havi sian propran " +"konvencion." + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "Ajna ebla spaco en ajna etikedo estu anstataŭigita per ``_``." + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "Python-Etikedo" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" +"La Python-etikedo indikas la realigon kaj version postulatajn de distribuo. " +"Ĉefaj realigoj havas mallongajn kodojn, komence:" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "py: Ĝenerala Python (ne postulas funkciojn de specifaj realigoj)" + +#: ../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/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "jy: Jython" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" +"Aliaj realigoj de Python uzu :py:data:`sys.implementation.name " +"`." + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" +"La versio estas ``py_version_nodot``. CPython povas uzi senpunktan version, " +"sed se disigilo necesas, oni uzas ``_`` anstataŭe. PyPy uzu siajn proprajn " +"versiojn kiel ``pp18``, ``pp19``." + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" +"La versio povas esti simple la maĵoran version ``2`` aŭ ``3`` ``py2``, " +"``py3`` por multaj pure Python-aj distribuoj." + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" +"Grave, etikedo nur pri la maĵora versio kiel ``py2`` kaj ``py3`` ne estas " +"mallongigoj de ``py20`` kaj ``py30``. Tiuj signifas, ke la pakinto intence " +"eldonis plurversie kongruan distribuon." + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" +"Unufonta distribuo kongrua kun Python 2 kaj 3 povas uzi la kombinitan " +"etikedon ``py2.py3``. Vidu `Densigitajn Etikedarojn `_ " +"ĉi-sube." + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "ABI-Etikedo" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" +"La ABI-etikedo indikas la ABI-on de Python subtenatan de inkluzivita " +"etendaĵo-modulo. Por realigo-specifa ABI, la realigo estas mallongigita same " +"kiel la Python-etikedo; ekz. ``cp33d`` estas la ABI de CPython 3.3 kun " +"sencimigpovo." + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" +"La stabila ABI de CPython estas ``abi3`` kiel la sufikso de la komuna " +"biblioteko." + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" +"Python-realigo kun tre malstabila ABI povas uzi la unuajn 6 bajtojn (kiel ok " +"base64-koditajn signojn) de la haketaĵo SHA-256 de la fontkoda revizio kaj " +"tradukilaj flagoj ktp, sed ties komunumo verŝajne ne tre bezonas distribui " +"duumajn distribuojn. La komunumo de ĉiu realigo povas decidi la uzadon de la " +"ABI-etikedo." + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "Platformo-Etikedo" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "Bazaj platformaj etikedoj" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" +"En ĝia plej simpla formo, la platformo-etikedo " +"estas :py:func:`sysconfig.get_platform()` kun ĉiuj streketoj ``-`` kaj " +"punktoj ``.`` anstataŭigitaj per substrekoj ``_``. Ĝis la forigo " +"de :ref:`distutils` en Python 3.12, tiu estis " +"``distutils.util.get_platform()``. Ekzemple:" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "win32" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "linux_i386" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "linux_x86_64" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "``manylinux``" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" +"La ĉi-supra simpla skemo ne sufiĉas por publika distribuado de wheel-" +"dosieroj al Linux-platformoj pro la diverseco de la granda ekosistemo de " +"Linux-platformoj." + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" +"Anstataŭe, por tiuj platformoj, la normo ``manylinux`` estas komuna subaro " +"de Linux-platformoj kaj permesas konstrui wheel kun la etikedo ``manylinux`` " +"uzeblan tra oftaj Linux-distribuoj." + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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 "" +"La aktuala normo estas la estontece sekura normo :file:`manylinux_{x}_{y}`. " +"Ĝi difinas etikedojn de la formo :file:`manylinux_{x}_{y}_{arch}`, en kiu " +"``x`` kaj ``y`` estas la subtenataj maĵoraj kaj minoraj versioj de glibc " +"(ekzemple ``manylinux_2_24_xxx`` funkciu sur ajna distribuo uzanta glibc " +"2.24+), kaj ``arch`` estas la arĥitekturo, egalante la valoron " +"de :py:func:`sysconfig.get_platform()` sur la sistemo laŭ la ĉi-supra " +"«simpla» formo." + +#: ../source/specifications/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "Jen malnovaj etikedoj ankoraŭ subtenataj por retrokongrueco:" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" +"``manylinux1`` subtenas glibc 2.5 ĉe la arĥitekturoj ``x86_64`` kaj ``i686``." + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "``manylinux2010`` subtenas glibc 2.12 ĉe ``x86_64`` kaj ``i686``." + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" +"``manylinux2014`` subtenas glibc 2.17 ĉe ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, kaj ``s390x``." + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" +"Ĝenerale, distribuo konstruita por pli malnova versio de la specifo estas " +"antaŭenkongrua (alivorte, distribuo ``manylinux1`` funkcias sur modernaj " +"sistemoj) sed ne retrokongrua (alivorte, distribuo ``manylinux2010`` ne " +"funkcias sur distribuo ekzistinta antaŭ 2010)." + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" +"Mastrumanto de pako provu celi la plej kongruan specifon laŭeble, krom ke la " +"provizitaj konstruo-medioj por ``manylinux1`` kaj ``manylinux2010`` estas " +"eksvalidiĝintaj kaj ne plu ricevos ĝisdatigojn pri sekureco." + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" +"Jen tabelo pri la minimumaj versioj de rilataj projektoj subtenantaj la " +"diversajn normojn ``manylinux``:" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "Ilo" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "``manylinux1``" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "``manylinux2010``" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "``manylinux2014``" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "``manylinux_x_y``" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "``>=8.1.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "``>=19.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "``>=19.3``" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "``>=20.3``" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "auditwheel" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "``>=1.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "``>=2.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "``>=3.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "``>=3.3.0`` [#]_" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "Nur subteno pri ``manylinux_2_24`` estis aldonita al auditwheel 3.3.0" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "``musllinux``" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +#, fuzzy +#| 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 :file:`musllinux_{x}_{y}_{arch}" +#| "``, supporting musl ``x.y`` and higher on the architecture ``arch``." +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" +"La familio ``musllinux`` de etikedoj similas al ``manylinux``, sed temas pri " +"Linux-platformoj uzantan la C-bibliotekon musl_ anstataŭ glibc (unu ekzemplo " +"estas Alpine Linux). La skemo estas :file:`musllinux_x_y_arch`, subtenanta " +"musl ``x.y`` kaj pli novajn sur la arĥitekturo ``arch``." + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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 "" +"Oni eltrovas la versian valoron de ``musl`` rulante la komunan C-bibliotekon " +"de ``musl`` uzatan de la Python-interpretilo kaj analizante la eligaĵon:" + +#: ../source/specifications/platform-compatibility-tags.rst:193 +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 "" +"Aktuale ekzistas du manieroj por trovi la lokon de la biblioteko musl sur " +"kiu Python-interpretilo ruliĝas: aŭ per la sistema komando ldd_, aŭ per " +"analizado de la valoro de la sekcio ``PT_INTERP`` en la ELF_-ĉapo de la " +"ruleblaĵo." + +#: ../source/specifications/platform-compatibility-tags.rst:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" +"macOS uzas la etikedo-familion ``macosx`` (la sufikso ``x`` estas pro la " +"oficiala nomskemo de Apple). La skemo de etikedoj pri kongrueco " +"estas :file:`macosx_{x}_{y}_{arch}`, indikante, ke la wheel kongruas kun " +"macOS de versio ``x.y`` aŭ pli nova sur la arĥitekturo ``arch``." + +#: ../source/specifications/platform-compatibility-tags.rst:207 +#, fuzzy +#| msgid "" +#| "The values of ``x`` and ``y`` correspond to the major and minor version " +#| "number of the macOS release, respectively. They must both be positive " +#| "integers, with the ``x`` value being ``>= 10``. The version number always " +#| "includes a major *and* minor version, even if Apple's official version " +#| "numbering only refers to the major value. For example, " +#| "``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" +"La valoroj de ``x`` kaj ``y`` respondas al la maĵora kaj minora versio-" +"numeroj de macOS respektive. Ili ambaŭ devas esti pozitivaj entjeroj, kaj " +"``x`` devas esti ne malpli granda ol ``10``. La versio-numero ĉiam " +"inkluzivas *kaj* maĵoran *kaj* minoran versiojn, eĉ se oficiala versio de " +"Apple nur uzas la maĵoran numeron. Ekzemple, ``macosx_11_0_arm64`` indikas " +"kongruecon kun macOS 11 aŭ pli nova." + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" +"Duumaĵo por macOS povas subteni aŭ nur unu arĥitekturon aŭ plurajn " +"arĥitekturojn (per «grasa» duumaĵo). Por indiki subtenon de unu arĥitekturo, " +"la valoro de ``arch`` devas egali la valoron " +"de :py:func:`platform.machine()` sur la sistemo. Por indiki subtenon de " +"pluraj arĥitekturoj, la etikedo ``arch`` estu identigilo el la jena listo de " +"aroj de subtenataj arĥitekturoj:" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "``arch``" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "Subtenataj arĥitekturoj" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "``universal2``" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "``arm64``, ``x86_64``" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "``universal``" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "``i386``, ``ppc``, ``ppc64``, ``x86_64``" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "``intel``" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "``i386``, ``x86_64``" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "``fat``" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "``i386``, ``ppc``" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "``fat3``" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "``i386``, ``ppc``, ``x86_64``" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "``fat64``" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "``ppc64``, ``x86_64``" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" +"La minimuma subtenata versio de macOS ankaŭ povas esti limigita de la " +"arĥitekturo. Ekzemple, macOS 11 (Big Sur) estis la unua versio subtenanta " +"arm64. Tiaj limigoj estas aŭtomate devigitaj de la macOS-tradukilaro dum " +"konstruado de duumaĵoj por pluraj arĥitekturoj." + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "Android" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" +"Android uzas la skemon :file:`android_{apilevel}_{abi}`, indikantan " +"kongruecon kun la donita API-nivelo de Android aŭ pli nova nivelo, sur la " +"donita ABI. Ekzemple, ``android_27_arm64_v8a`` indikas subtenon por API-" +"nivelo 27 aŭ pli nova, sur aparato ``arm64_v8a``. Android ne distingas inter " +"reala aparato kaj imitilo." + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" +"La API-nivelo estu pozitiva entjero. Tio *ne* egalas la version de Android " +"konata de la uzanto. Ekzemple, la eldono Android 12 (kodnome «Snow Cone») " +"uzas la API-nivelon 31 aŭ 32, depende de la specifa versio de Android. La " +"dokumentaro pri eldonoj de Android inkluzivas la `plenan liston de versioj " +"de Android kaj la respondantaj API-niveloj `__." + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" +"Ekzistas kvar `subtenataj ABI-oj `__. Jen la ABI-oj normigitaj laŭ la ĉi-supraj reguloj:" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "``armeabi_v7a``" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "``arm64_v8a``" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "``x86``" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" +"Preskaŭ ĉiuj realaj aparatoj uzas unu el la ARM-arĥitekturoj. ``x86`` kaj " +"``x86_64`` estas subtenataj por uzado en imitilo. ``x86`` ne plu estas " +"subtenata kiel evoluada platformo ekde 2020, kaj nova imitilo ne eldoniĝis " +"post 2020." + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "iOS" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" +"iOS uzas la skemon :file:`ios_{x}_{y}_{arch}_{sdk}`, por kongrueco kun " +"versio ``x.y`` (aŭ pli nova) de iOS, sur la arĥitekturo ``arch``, uzante la " +"SDK ``sdk``." + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" +"La valoroj de ``x`` kaj ``y`` respondas al la maĵora kaj minora versio-" +"numeroj de iOS respektive. Ili ambaŭ devas esti pozitivaj entjeroj. La " +"versio-numero ĉiam inkluzivas *kaj* maĵoran *kaj* minoran versiojn, eĉ se " +"oficiala versio de Apple nur uzas la maĵoran numeron. Ekzemple, " +"``ios_13_0_arm64_iphonesimulator`` indikas kongruecon kun iOS 13 aŭ pli nova." + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" +"La valoro de ``arch`` devas egali la valoron " +"de :py:func:`platform.machine()` sur la sistemo." + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" +"La valoro de ``sdk`` devas esti aŭ ``iphoneos`` (por reala aparato), aŭ " +"``iphonesimulator`` (por imitilo de aparato). La SDK-oj havas la saman API-" +"surfacon sed ne kongruas inter si je la duumaĵa nivelo, eĉ se ili uzas la " +"saman ĉefprocesoran arĥitekturon. Kodo tradukita por arm64-imitilo ne " +"ruliĝas sur arm64-aparato." + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" +"La kombinaĵo de :file:`{arch}_{sdk}` nomiĝas la «multarĥitekturo». Ekzistas " +"tri eblaj valoroj de la multarĥitekturo:" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" +"``arm64_iphoneos``, por fizikaj aparatoj iPhone/iPad. Tiuj inkluzivas ĉiajn " +"iOS-aparatojn produktitajn post ~2015;" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" +"``arm64_iphonesimulator``, por imitilo sur aparato Apple Silicon kun macOS; " +"kaj" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "``x86_64_iphonesimulator``, por imitilo sur aparato x86_64." + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "Uzado" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" +"Alia dezirinda funkcio de instalilo eble estas igi «retraduki el fonto se " +"tio eblas» pli preferata ol la kongruaj sed malnovaj antaŭkonstruitaj opcioj." + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" +"Jen ekzempla listo por instalilo sub CPython 3.3 sur sistemo linux_x86_64, " +"ordigita ekde la plej preferata (distribuo kun tradukita etendaĵa modulo por " +"la aktuala versio de Python) ĝis la malplej preferata (pure Python-a " +"distribuo konstruita per malnova versio de Python):" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "cp33-cp33m-linux_x86_64" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "cp33-abi3-linux_x86_64" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "cp3-abi3-linux_x86_64" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "cp33-none-linux_x86_64*" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "cp3-none-linux_x86_64*" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "py33-none-linux_x86_64*" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "py3-none-linux_x86_64*" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "cp33-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "cp3-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "py33-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "py3-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "py32-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "py31-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "py30-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" +"Konstruita distribuo povas esti platformo-specifa pro kialo alia ol C-" +"etendaĵo, kiel uzo de indiĝena ruleblaĵo alvokita kiel subprocezo." + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" +"Kelkfoje ekzistas pluraj subtenataj konstruitaj distribuoj por iu versio de " +"pako. Ekzemple, aŭtoro povus eldoni pakon kun etikedo ``cp33-abi3-" +"linux_x86_64`` enhavantan laŭvolan C-etendaĵon kaj la saman distribuon kun " +"etikedo ``py3-none-any`` sen C-etendaĵo. La indico de la etikedo en la listo " +"de subtenataj etikedoj decidas la instalotan pakon: la pako kun la C-" +"etendaĵo estas instalota prefere al la pako sen ĝi, ĉar tiu etikedo ĉeestas " +"unue en la listo." + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "Densigitaj Etikedaroj" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +#, fuzzy +#| 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::" +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, collection 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 "" +"Por kompakta dosiernomo de duuma distribuo kongrua kun pluraj kongrueco-" +"etikedaj triopoj, ĉiu etikedo en dosiernomo povas esti anstataŭe «.»-" +"disigita ordigita aro da etikedoj. Ekzemple, pip, kiu estas pure Python-a " +"pako kongrua kun kaj Python 2 kaj 3 kun la sama fontkodo, povus distribui " +"duuman distrubon kun la etikedo ``py2.py3-none-any``. Jen la plena listo de " +"simplaj etikedoj::" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "Kiuj etikedoj uziĝas implicite?" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +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 "" +"Ilo apriore uzu la plej preferata arĥitekturo-dependa etikedo, ekz. ``cp33-" +"cp33m-win32``, aŭ la plej preferata pure Python-a etikedo, ekz. ``py33-none-" +"any``. Se la pakanto modifis la aprioron, tio signifas, ke inter-Python-a " +"kongrueco estas intencita." + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" +"Kiun etikedon mi uzu, se mia distribuo uzas funkcion nur en la nova versio " +"de Python?" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" +"Etikedoj pri kongrueco helpas instalilojn elekti la *plej kongruan* " +"konstruon de *unu versio* de distribuo. Ekzemple, se ne ekzistas Python-3.3-" +"kongruan konstruon de ``beaglevote-1.2.0`` (ĉar ĝi uzas funkcion nur en " +"3.4), ĝi tamen povas uzi la etikedon ``py3-none-any`` anstataŭ la etikedo " +"``py34-none-any``. Uzanto de Python 3.3 devas kombini aliajn kvalifikilojn " +"kiel postulon por la malnova eldono ``beaglevote-1.1.0`` ne uzanta la novan " +"funkcion, por akiri kongruan konstruon." + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "Kial mankas ``.`` en la versia numero de Python?" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" +"CPython daŭris pli ol 20 jarojn sen tricifera maĵora eldono. Tio daŭros " +"longe. Alia realigo povas uzi ``_`` kiel apartigilon, ĉar kaj ``-`` kaj " +"``.`` apartigas la ĉirkaŭan dosiernomon." + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" +"Kial normigi streketojn kaj aliajn ne literciferajn signojn al substrekoj?" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" +"Por averti konfliktojn kun la signoj ``.`` kaj ``-`` apartigantaj " +"komponantojn de la dosiernomo, kaj por kongrueco kun tiom da dosiersistemaj " +"limigoj kiom eblas (inkluzive de uzebleco en retadreso sen kodŝanĝado)." + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "Kial ne uzi iun specialan signon alian ol ``.`` aŭ ``-``?" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "Kiu mastrumas la registron de mallongigitaj realigoj?" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" +"Oni povas peti novan duliteran mallongigon ĉe la dissendolisto ``python-" +"dev``. Ordinare, mallongigoj estas rezervataj por la aktuale plej famaj " +"kvar realigoj." + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "Ĉu la kongrueca etikedo troviĝas en METADATA aŭ PKG-INFO?" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" +"Ne. La etikedo pri kongrueco estas larto de la metadatenoj de la konstruita " +"distribuo. METADATA kaj PKG-INFO estu validaj por la tuta distribuo, ne nur " +"unu konstruo de tiu distribuo." + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "Kial vi ne menciis mian preferatan realigon de Python?" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +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 "" +"La mallongigitaj etikedoj faciligas kunhavigadon de tradukita Python-kodo ĉe " +"publika indekso. Via Python-realigo povas uzi ĉi tiun specifon ankaŭ, sed " +"kun pli longaj etikedoj. Rememoru, ke ĉiu «pure Python-a» konstruita " +"distribuo simple uzas ``py``." + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" +"Kial la ABI-etikedo (la dua etikedo) estas kelkfoje «none» en la referenca " +"realigo?" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" +"Ĉar Python 2 ne faciligas akiri la SOABI (la koncepto nur ekekzistis en " +"novaj versioj de Python 3), la nuntempa referenca realigo divenas ``none``. " +"Ideale ĝi detektus ``py27(d|m|u)`` simile al novaj versioj de Python, sed " +"``none`` sufiĉas por indiki nekonatecon." + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" +"Februaro 2013: La originala versio de ĉi tiu specifo estis aprobita " +"per :pep:`425`." + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "Januaro 2016: La etikedo ``manylinux1`` estis aprobita per :pep:`513`." + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" +"Aprilo 2018: La etikedo ``manylinux2010`` estis aprobita per :pep:`571`." + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" +"Julio 2019: La etikedo ``manylinux2014`` estis aprobita per :pep:`599`." + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" +"Novembro 2019: La ĉiama etikedo ``manylinux_x_y`` estis aprobita " +"per :pep:`600`." + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" +"Aprilo 2021: La etikedo ``musllinux_x_y`` estis aprobita per :pep:`656`." + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "Decembro 2023: La etikedoj pri iOS estis aprobitaj per :pep:`730`." + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "Marto 2024: La etikedoj pri Android estis aprobitaj per :pep:`738`." + +#: ../source/specifications/project-status-markers.rst:5 +#, fuzzy +#| msgid "Project Summaries" +msgid "Project Status Markers" +msgstr "Projektaj Resumoj" + +#: ../source/specifications/project-status-markers.rst:9 +#, fuzzy +#| msgid "This specification was originally defined in :pep:`740`." +msgid "This specification was originally defined in :pep:`792`." +msgstr "Ĉi tiu specifo estis originale difinita en :pep:`740`." + +#: ../source/specifications/project-status-markers.rst:14 +#, fuzzy +#| msgid "" +#| ":pep:`740` includes changes to the HTML and JSON index APIs. These " +#| "changes are documented in the :ref:`simple-repository-api` " +#| "under :ref:`simple-repository-api-base` and :ref:`json-serialization`." +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" +":pep:`740` inkluzivas ŝanĝojn pri la indeksaj API-oj en HTML kaj JSON. Tiuj " +"ŝanĝoj estas priskribitaj en :ref:`simple-repository-api` sub :ref:`simple-" +"repository-api-base` kaj :ref:`json-serialization`." + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +#, fuzzy +#| msgid "Installation" +msgid "Installer semantics: none." +msgstr "Instalado" + +#: ../source/specifications/project-status-markers.rst:45 +#, fuzzy +#| msgid "``arch``" +msgid "``archived``" +msgstr "``arch``" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +#, fuzzy +#| msgid "Installers" +msgid "Installer semantics:" +msgstr "Instaliloj" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +#, fuzzy +#| msgid "Deprecated" +msgid "``deprecated``" +msgstr "Evitindaj" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +msgid "``pylock.toml`` Specification" +msgstr "La normo pri ``pyproject.toml``" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +#, fuzzy +#| msgid "This specification was originally defined in :pep:`753`." +msgid "This specification was originally defined in :pep:`751`." +msgstr "Ĉi tiu specifo estis originale difinita en :pep:`753`." + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "Dosiernomo" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "La dosierformo de la dosiero estas TOML_." + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +msgid "``lock-version``" +msgstr "``lock-version``" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +msgid "**Required?**: yes" +msgstr "**Postulata?**: jes" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +msgid "``environments``" +msgstr "``environments``" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +#, fuzzy +#| msgid "TOML_ type: array of strings" +msgid "**Type**: Array of strings" +msgstr "Tipo de TOML_: listo de signoĉenoj" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "**Postulata?**: ne" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +#, fuzzy +#| msgid "TOML_ type: string" +msgid "**Type**: string" +msgstr "Tipo de TOML_: signoĉeno" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "**Postulata?** ne, apriore ``[]``" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +msgid "``dependency-groups``" +msgstr "``dependency-groups``" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +#, fuzzy +#| msgid ":ref:`pyproject-toml-spec`" +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr ":ref:`pyproject-toml-spec`" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "``default-groups``" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "``created-by``" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +#, fuzzy +#| msgid "" +#| "``INSTALLER``: records the name of the tool used to install the project." +msgid "Records the name of the tool used to create the lock file." +msgstr "" +"``INSTALLER``: registras la nomon de la ilo uzita por instali la projekton." + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +msgid "``[[packages]]``" +msgstr "``[[packages]]``" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +#, fuzzy +#| msgid "TOML_ type: array of strings" +msgid "**Type**: array of tables" +msgstr "Tipo de TOML_: listo de signoĉenoj" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "``packages.name``" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +#, fuzzy +#| msgid "" +#| "For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgid "The name of the package :ref:`normalized `." +msgstr "" +"Por komparado, la nomoj estu :ref:`normigitaj ` antaŭ " +"komparado." + +#: ../source/specifications/pylock-toml.rst:210 +msgid "``packages.version``" +msgstr "``packages.version``" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +msgid "The version of the package." +msgstr "La versio de la pako." + +#: ../source/specifications/pylock-toml.rst:216 +#, fuzzy +#| msgid "" +#| "``subject[0].name`` is the distribution's filename, which **MUST** be a " +#| "valid :ref:`source distribution ` " +#| "or :ref:`wheel distribution ` filename." +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" +"``subject[0].name`` estas la dosiernomo de la distribuo, kiu **DEVAS** esti " +"valida dosiernomo por :ref:`fonta distribuo ` " +"or :ref:`wheel-distribuo `." + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "``packages.marker``" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "``packages.requires-python``" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +msgid "``[[packages.dependencies]]``" +msgstr "``[[packages.dependencies]]``" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "``[packages.vcs]``" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +#, fuzzy +#| msgid "TOML_ type: table" +msgid "**Type**: table" +msgstr "Tipo de TOML_: tabelo" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "``packages.vcs.type``" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +#, fuzzy +#| msgid "Install from version control systems" +msgid "The type of version control system used." +msgstr "Instali el versikontrola sistemo" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "``packages.vcs.url``" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +#, fuzzy +#| msgid "The source tree" +msgid "The URL_ to the source tree." +msgstr "La fontarbo" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "``packages.vcs.path``" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +#, fuzzy +#| msgid "The path to the Python interprer of the base installation." +msgid "The path to the local directory of the source tree." +msgstr "La dosierloko de la Python-interpretilo de la baza instalo." + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "``packages.vcs.requested-revision``" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "``packages.vcs.commit-id``" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +#, fuzzy +#| 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." +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" +"Ŝlosilo ``commit_id`` (de tipo ``string``) DEVAS ekzisti, kies valoro estas " +"la ekzakta revizia numero intalota. Se la versikontrola sistemo subtenas " +"haketaĵo-baza revizio-identigilo, oni DEVAS uzi tian haketaĵon kiel " +"``commit_id`` por referenci nemodifeblan version de la fontokodo." + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "``packages.vcs.subdirectory``" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "``[packages.directory]``" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "``packages.directory.path``" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "``packages.directory.editable``" + +#: ../source/specifications/pylock-toml.rst:410 +#, fuzzy +#| msgid "*boolean*" +msgid "**Type**: boolean" +msgstr "*boolean*" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "**Postulata?** ne, apriore ``false``" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "``packages.directory.subdirectory``" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "``[packages.archive]``" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "``packages.archive.url``" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "Vidu :ref:`pylock-packages-vcs-url`." + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "``packages.archive.path``" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "Vidu :ref:`pylock-packages-vcs-path`." + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "``packages.archive.size``" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +#, fuzzy +#| msgid "The name of the project." +msgid "The size of the archive file." +msgstr "La nomo de la projekto." + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "``packages.archive.upload-time``" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +#, fuzzy +#| msgid "Where the guide is deployed" +msgid "The time the file was uploaded." +msgstr "Kie la gvidilo disponiĝas" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "``[packages.archive.hashes]``" + +#: ../source/specifications/pylock-toml.rst:493 +#, fuzzy +#| msgid "TOML_ type: array of strings" +msgid "**Type**: Table of strings" +msgstr "Tipo de TOML_: listo de signoĉenoj" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "``packages.archive.subdirectory``" + +#: ../source/specifications/pylock-toml.rst:516 +msgid "``packages.index``" +msgstr "``packages.index``" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "``[packages.sdist]``" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "``packages.sdist.name``" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "``packages.sdist.upload-time``" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "Vidu :ref:`pylock-packages-archive-upload-time`." + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "``packages.sdist.url``" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "Vidu :ref:`pylock-packages-archive-url`." + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "``packages.sdist.path``" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "Vidu :ref:`pylock-packages-archive-path`." + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "``packages.sdist.size``" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "Vidu :ref:`pylock-packages-archive-size`." + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "``packages.sdist.hashes``" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "Vidu :ref:`pylock-packages-archive-hashes`." + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "``[[packages.wheels]]``" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "``packages.wheels.name``" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "``packages.wheels.upload-time``" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "``packages.wheels.url``" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "``packages.wheels.path``" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "``packages.wheels.size``" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "``packages.wheels.hashes``" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "``[[packages.attestation-identities]]``" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +#, fuzzy +#| msgid ":ref:`pyproject-toml-spec`" +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr ":ref:`pyproject-toml-spec`" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "``packages.attestation-identities.kind``" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "``[packages.tool]``" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "``[tool]``" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "Vidu :ref:`pylock-packages-tool`." + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +#, fuzzy +#| msgid "Binary distribution format" +msgid ":ref:`Install `." +msgstr "Duuma distribua formo" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "Aprilo 2025: unua versio, aprobita per :pep:`751`." + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "La dosiero :file:`.pypirc`" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" +"Dosiero :file:`.pypirc` agordas la :term:`pakindekson ` (ĉi " +"tie nomitan «deponejo»), por ke oni ne bezonas tajpi la retadreson, " +"salutnomon aŭ pasvorton ĉiun fojon, kiam oni alŝutas pakon per :ref:`twine` " +"aŭ :ref:`flit`." + +#: ../source/specifications/pypirc.rst:13 +#, fuzzy +#| msgid "The :file:`.pypirc` file" +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "La dosiero :file:`.pypirc`" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "Jen la formo (origine difinita de la pako :ref:`distutils`):" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" +"La sekcio ``distutils`` difinas kampon ``index-servers`` listigantan la " +"nomojn de ĉiuj sekcioj priskribantaj deponejojn." + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "Ĉiu sekcio priskribanta deponejon difinas tri kampojn:" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "``repository``: La retadreso de la deponejo." + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "``username``: La registrita salutnomo ĉe la deponejo." + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "``password``: La pasvorto por aŭtentikigi la salutnomon." + +#: ../source/specifications/pypirc.rst:48 +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 "" +"Atentu, ke tio konservas vian pasvorton en ordinara teksto. Por pli da " +"sekureco, konsideru alternativojn kiel `keyring`_, agordadon de " +"mediovariabloj, aŭ komandlinian disponigadon de la pasvorto." + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" +"Alie, agordu la permesojn pri :file:`'.pypirc` tiel, kiel nur vi rajtas vidi " +"aŭ modifi ĝin. Ekzemple, sur Linux aŭ macOS, rulu la jenon:" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "Oftaj agordoj" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" +"Tiuj ekzemploj validas por :ref:`twine`. Aliaj projektoj (kiel :ref:`flit`) " +"ankaŭ uzas :file:`.pypirc`, sed kun aliaj implicitaĵoj. Bonvolu legi la " +"dokumentaron de la projekto por pliaj detaloj kaj helpoj pri uzado." + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" +"La apriora agordo de Twine imitas :file:`.pypirc` kun deponejaj sekcioj por " +"PyPI kaj Prova PyPI:" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" +"Twine aldonos al la aprioraj agordoj suplementajn agordojn " +"el :file:`$HOME/.pypirc`, la komanda linio kaj mediaj variabloj." + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "Uzi PyPI-ĵetonon" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" +"Por agordi vian `API-ĵetonon ` por PyPI, vi povas krei " +"dosieron :file:`$HOME/.pypirc` similan al la jeno:" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" +"Por :ref:`Prova PyPI `, aldonu sekcion ``[testpypi]`` " +"uzante la API-ĵetonon por via konto ĉe Prova PyPI." + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "Uzi alian pakindekson" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" +"Por agordi plian deponejon, oni devas redifini la kampon ``index-servers`` " +"inkluzivante la nomon de la deponejo. Jen plena ekzemplo " +"de :file:`$HOME/.pypirc` por PyPI, Prova PyPI, kaj privata deponejo:" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" +"Anstataŭ uzi la kampon ``password``, konsideru konservi viajn API-ĵetonojn " +"kaj pasvortojn sekure per `keyring`_ (kiun Twine instalas):" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "specifo ``pyproject.toml``" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" +"Jen **teĥnika formala specifo**. Por milda, facila gvidilo pri " +"``pyproject.toml``, vidu :ref:`writing-pyproject-toml`." + +#: ../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 "" +"La dosiero ``pyproject.toml`` funkcias kiel agorda dosiero por pakado-" +"rilataj iloj (kaj aliaj iloj)." + +#: ../source/specifications/pyproject-toml.rst:17 +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 "" +"La dosierformo de la dosiero ``pyproject.toml`` estas `TOML `_. Jen la tri tabeloj specifitaj aktuale: :ref:`[build-system] " +"`, :ref:`[project] ` " +"kaj :ref:`[tool] `. Aliaj tabeloj estas rezervataj por " +"la estonteco (ilo-specifa agordo estu en la tabelo ``[tool]`` )." + +#: ../source/specifications/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "Deklari konstrusistemaj dependecoj: la tabelo ``[build-system]``" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" +"La tabelo ``[build-system]`` deklaras iujn ajn Python-nivelajn dependecojn " +"instalendajn por sukcese ruli la projektan konstrusistemon." + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" +"Jen ekzempla tabelo ``[build-system]`` por projekto konstruita per " +"``setuptools``:" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" +"Konstruilo uzu la ĉi-supran ekzemplan agordan dosieron kiel la implicitan " +"semantikon, se mankas dosiero ``pyproject.toml``." + +#: ../source/specifications/pyproject-toml.rst:54 +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 "" +"Ilo ne postulu la ekziston de la tabelo ``[build-system]``. Dosiero " +"``pyproject.toml`` povas esti uzita por agordaj detaloj aliaj ol konstruo-" +"rilataj datenoj kaj tial ne havi tabelon ``[build-system]``. Se la dosiero " +"ekzistas sed la tabelo ``[build-system]`` mankas, do oni uzu la apriorajn " +"valorojn specifitajn ĉi-supre. Se la tabelo estas specifita sed postulitaj " +"kampoj mankas, do ilo konsideru tion kiel eraron." + +#: ../source/specifications/pyproject-toml.rst:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" +"Por provizi tipo-specifan prezento de la rezultaj datenoj el la TOML-dosiero " +"sole por klarigado, la jena `JSON-Skemo `_ kongruus " +"kun la datena formo:" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "Deklari projektajn metadatenojn: la tabelo ``[project]``" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" +"La tabelo ``[project]`` specifas la :ref:`kernajn metadatenojn ` de la projekto." + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" +"Ekzistas du specoj de metadatenoj: *statika* kaj *dinamika*. Statika " +"metadateno estas specifita en la dosiero ``pyproject.toml`` rekte kaj ne " +"estas specifebla nek modifebla per ilo (tio inkluzivas datenojn *menciitajn* " +"de la metadatenoj, ekz. la enhavoj de dosieroj referencitaj en la " +"metadatenoj). Dinamika metadateno estas enlistigitaj per la ŝlosilo " +"``dynamic`` (difinita poste en ĉi tiu normo) kaj prezentas metadateno " +"provizotan de ilo." + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" +"La manko de tabelo ``[project]`` implicas, ke la :term:`konstrua malfasado " +"` dinamike provizos ĉiujn ŝlosilojn." + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "Jen tiuj ŝlosiloj, kiuj devas esti statike difinitaj:" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "Jen la devigaj ŝlosiloj specifeblaj *aŭ* statike *aŭ* dinamike:" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" +"Ĉiuj aliaj ŝlosiloj estas nedevigaj kaj povas esti specifitaj statike, " +"specifitaj dinamike, aŭ nespecifitaj." + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "Jen la plena listo de ŝlosiloj permesataj en la tabelo ``[project]``:" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "``authors``" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "``dependencies``" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "``dynamic``" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "``entry-points``" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "``gui-scripts``" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +#, fuzzy +#| msgid "``name``" +msgid "``import-names``" +msgstr "``name``" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "``maintainers``" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "``optional-dependencies``" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "Tipo de TOML_: signoĉeno" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" +"Respondanta :ref:`kerna metadatena ` kampo: :ref:`Name `" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "La nomo de la projekto." + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" +"Ilo :ref:`NORMIGU ` ĉi tiun nomon tuj post legado por " +"interna kohereco." + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" +"Respondanta :ref:`kerna metadatena ` kampo: :ref:`Version " +"`" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" +"La versio de la projekto laŭ :ref:`la specifo pri versispecifiloj `." + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "Uzantoj *PREFERU* specifi jam normigitajn versiojn." + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" +"Respondanta :ref:`kerna metadatena ` kampo: :ref:`Summary " +"`" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" +"La resuma priskribo pri la projekto en unu linio. Ilo POVAS sciigi eraron, " +"se ĝi inkluzivas plurajn liniojn." + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "Tipo de TOML_: signoĉeno aŭ tabelo" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" +"Respondanta :ref:`kerna metadatena ` kampo: :ref:`Description " +"` kaj :ref:`Description-Content-Type `" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "La plena priskribo de la projekto (t.e. la README)." + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" +"La ŝlosilo akceptas aŭ signoĉenon aŭ tabelon. Se ĝi estas signoĉeno, do ĝi " +"estas dosierloko relativa de ``pyproject.toml`` al teksta dosiero enhavanta " +"la plenan priskribon. Ilo DEVAS supozi, ke la dosiero estas kodita je UTF-8. " +"Se la dosierloko finiĝas per usklecoblinda sufikso ``.rst``, do ilo DEVAS " +"supozi, ke la enhavtipo estas ``text/markdown``. Se la dosierloko finiĝas " +"usklecoblinde per ``.rst``, do ilo DEVAS supozi, ke la enhavtipo estas " +"``text/x-rst``. Se ilo rekonas pli da sufiksoj ol ĉi tiu PEP, ĝi POVAS " +"inferenci la enhavtipon por la uzanto sen precizigado de tiu ŝlosilo kiel " +"``dynamic``. Por ĉia nerekonebla sufikso, kiam enhavtipo ne estas " +"disponigita, ilo DEVAS sciigi pri eraro." + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" +"Tabelo specifita en la ŝlosilo ``readme`` ankaŭ havas ŝlosilon ``content-" +"type`` prenantan signoĉenon de la enhavtipo de la plena priskribo. Ilo DEVAS " +"sciigi pri eraro, se la metadatenoj ne specifas tiun ŝlosilon en la tabelo. " +"Se la metadatenoj ne specifas la parametron ``charset``, oni supozas, ke ĝi " +"estas UTF-8. Ilo POVAS subteni alternativajn enhavtipojn transformeblajn al " +"enhavtipo subtenata de la :ref:`kernaj metadatenoj `. Alikaze " +"ilo DEVAS sciigi pri eraro por nesubtenataj enhavtipoj." + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" +"Respondanta :ref:`kerna metadatena ` kampo: :ref:`Requires-" +"Python `" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "La postuloj de la projekto pri versioj de Python." + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" +"Respondanta :ref:`kerna metadatena ` kampo: :ref:`License-" +"Expression `" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" +"Signoĉeno, kiu estas valida :term:`SPDX-licencesprimo ` " +"laŭ :doc:`/specifications/license-expression`. Ilo KONTROLU la validecon de " +"la esprimo kaj NORMIGU la usklecon." + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +msgid "Legacy specification" +msgstr "Malnova normo" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "Tipo de TOML_: tabelo" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" +"Respondanta :ref:`kerna metadatena ` kampo: :ref:`License " +"`" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`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 "" +"La tabelo povas havi unu el du ŝlosiloj. La ŝlosilo ``file`` havas " +"signoĉenan valoron, kiu estas dosierloko (relativa " +"al :file:`pyproject.toml`) de la dosiero, kiu enhavas la licencon de la " +"projekto. Ilo DEVAS supozi, ke la dosiero estas kodita laŭ UTF-8. La ŝlosilo " +"``text`` havas signoĉenan valoro, kiu estas la licenco de la projekto. Tiuj " +"ŝlosiloj estas disaŭaj: ilo DEVAS sciigi pri eraro, se la metadatenoj " +"enhavas ambaŭ ŝlosilojn." + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" +"La tabelajn subŝlosilojn malrekomendis :pep:`639`, rekomendante anstaŭe la " +"signoĉenan valoron." + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "Tipo de TOML_: listo de signoĉenoj" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" +"Respondanta :ref:`kerna metadatena ` kampo: :ref:`License-" +"File `" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" +"La signoĉeno DEVAS enhavi validan patroneon laŭ la normo :doc:`/" +"specifications/glob-patterns`." + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" +"Patroneo estas relativa al la dosierujo enhavanta :file:`pyproject.toml`," + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" +"Ilo DEVAS supozi, ke la enhavo de licenco-dosiero estas valida UTF-8-kodita " +"teksto, kaj KONTROLU la validecon kaj SCIIGU eraron, se ĝi ne validas." + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "Konstruiloj:" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" +"DEVAS inkluzivi ĉiujn dosierojn kongruajn al enlistigita patroneo en ĉiuj " +"distribuaj arĥivoj." + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" +"DEVAS enlistigi ĉiun kongruan dosierlokon sub kampo ``License-File`` en la " +"Kernaj Metadatenoj." + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" +"Se la ŝlosilo ``license-files`` ekzistas kaj ĝia valoro estas malplena " +"listo, do ilo DEVAS NE inkluzivi ajanan licencan dosieron kaj DEVAS NE " +"sciigi pri eraro. Se la ŝlosilon ``license-files`` ne estas difinita, ilo " +"povas decidi pri la traktado de licencaj dosieroj. Ekzemple, ĝi povas simple " +"ne inkluzivi ajanan dosieron, aŭ uzi sian propran logikon por trovi la " +"taŭgajn dosierojn en la distribuo." + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "Tipo de TOML_: Listo de tabeloj de signoĉenaj ŝlosiloj kaj valoroj" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" +"Respondanta :ref:`kerna metadatena ` kampo: :ref:`Author " +"`, :ref:`Author-email `, :ref:`Maintainer `, kaj :ref:`Maintainer-" +"email `" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" +"Homoj aŭ organizaĵoj rigardataj kiel la «aŭtoroj» de la projekto. La preciza " +"signifo dependas de interpretad – ĝi povas listigi la originalajn aŭ ĉefajn " +"verkintojn, aktualajn mastrumantojn, aŭ posedantojn de la pako." + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" +"La ŝlosilo ``maintainers`` similas al ``authors``: ĝia preciza signifo " +"dependas de interpretado." + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" +"Tiuj ŝlosiloj akceptas liston de tabeloj kun du ŝlosiloj: ``name`` kaj " +"``email``. Ambaŭ valoroj estas tekstaj. La valoro de ``name`` DEVAS esti " +"valida retpoŝta nomo (tiu, kiu povas servi kiel nomo antaŭ retpoŝta adreso " +"en :rfc:`822`) kaj ne povas inkluzivi komon. La valoro de ``email`` DEVAS " +"esti valida retpoŝta adreso. Ambaŭ ŝlosiloj estas ellaseblaj, sed la tabelo " +"devas enhavi almenaŭ unu el la duo." + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" +"La datenoj respondas al :ref:`kernaj metadatenoj ` jene:" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" +"Se nur ``name`` estas provizita, la valoro respondas al :ref:`Author ` aŭ :ref:`Maintainer ` depende." + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" +"Se nur ``email`` estas provizita, la valoro respondas al :ref:`Author-email " +"` aŭ :ref:`Maintainer-email ` depende." + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" +"Se kaj ``email`` kaj ``name`` estas provizitaj, la valoroj respondas " +"al :ref:`Author-email ` aŭ :ref:`Maintainer-" +"email ` depende, en la formo ``{name} " +"<{email}>``." + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "Oni apartigu plurajn valorojn per komoj." + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" +"Respondas al la :ref:`kerna metadatena ` " +"kampo: :ref:`Keywords `" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "La ŝlosilvortoj pri la projekto." + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" +"Respondas al la :ref:`kerna metadatena ` " +"kampo: :ref:`Classifier `" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "Klasigiloj Trove rilataj al la projekto." + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" +"La uzado de klasigiloj ``License ::`` estas evitinda. Ilo POVAS averti " +"uzantojn pri tio. Konstruilo POVAS sciigi pri eraro, se kaj la signoĉena " +"valoro ``license`` (por la metadatena kampo ``License-Expression``) kaj " +"klasigilo ``License ::`` estas uzataj." + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "Tipo de TOML_: tabelo kun ŝlosiloj kaj valoroj signoĉenaj" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" +"Respondanta :ref:`kerna metadatena ` kampo: :ref:`Project-URL " +"`" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" +"Tabelo de retadresoj, en kiu la ŝlosilo estas la retadresa etikedo kaj la " +"valoro estas la retadreso mem. Vidu :ref:`well-known-project-urls` por " +"reguloj pri normigado kaj prezentado de bone konataj metadatenoj." + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "Enirpunktoj" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" +"Tipo de TOML_: tabelo (``[project.scripts]``, ``[project.gui-scripts]``, kaj " +"``[project.entry-points]``)" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr ":ref:`Specifo pri enirpunktoj `" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" +"Ekzistas tri tabeloj pri enirpunktoj. La tabelo ``[project.scripts]`` " +"respondas al la grupo ``console_scripts`` en :ref:`la normo pri enirpunktoj " +"`. La ŝlosilo de la tabelo estas la nomo de la enirpunkto; la " +"valoro estas la referenco al objekto." + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" +"La tabelo ``[project.gui-scripts]`` respondas al la grupo ``gui_scripts`` " +"en :ref:`la specifo pri enirpunktoj `. Ĝia formo estas sama " +"kiel ``[project.scripts]``." + +#: ../source/specifications/pyproject-toml.rst:436 +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 "" +"La tabelo ``[project.entry-points]`` estas tabelo da subtabeloj. La nomo de " +"subtabelo estas enirpunktogrupo. La semantikoj de ŝlosiloj kaj valoroj estas " +"la sama kiel la semantiko de ``[project.scripts]``. Uzanto DEVAS NE krei " +"subsubtabelojn; la profundo de ingado de la enirpunktogrupoj estu nur unu " +"nivelo." + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" +"Konstrua malfasado DEVAS sciigi pri eraro, se la metadatenoj difinas " +"``[project.entry-points.console_scripts]`` aŭ ``[project.entry-" +"points.gui_scripts]``, ĉar tiuj estus ambiguaj pro ``[project.scripts]`` kaj " +"``[project.gui-scripts]``, respektive." + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" +"Tipo de TOML_: Listo de signoĉenoj laŭ :pep:`508` (``dependencies``) kaj " +"tabelo de valoroj de listoj de signoĉenoj laŭ :pep:`508` (``optional-" +"dependencies``)" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" +"Respondanta :ref:`kerna metadatena ` kampo: :ref:`Requires-" +"Dist ` kaj :ref:`Provides-Extra `" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "La (nedevigaj) dependecoj de la projektoj." + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" +"Por ``dependencies``, ĝi estas ŝlosilo, kies valoro estas listo de " +"signoĉenoj. Ĉiu signoĉeno prezentas dependecon de la projekto kaj DEVAS esti " +"valida laŭ :pep:`508`. Ĉiu signoĉeno rekte respondas al ero :ref:`Requires-" +"Dist `." + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +#, fuzzy +#| msgid "" +#| "Corresponding :ref:`core metadata ` field: :ref:`Name " +#| "`" +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" +"Respondanta :ref:`kerna metadatena ` kampo: :ref:`Name `" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +#, fuzzy +msgid "Examples:" +msgstr "Ekzemploj" + +#: ../source/specifications/pyproject-toml.rst:536 +#, fuzzy +#| msgid "" +#| "Corresponding :ref:`core metadata ` field: :ref:`Name " +#| "`" +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" +"Respondanta :ref:`kerna metadatena ` kampo: :ref:`Name `" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +#, fuzzy +#| msgid "Example::" +msgid "Example:" +msgstr "Ekzemple::" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "Tipo de TOML_: listo de signoĉenoj" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" +"Respondanta :ref:`kerna metadatena ` kampo: :ref:`Dynamic " +"`" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" +"Listigas tiujn ŝlosiloj en ĉi tiu PEP, kiuj estis intence nespecifitaj kaj " +"aŭtomate provizotaj de alia ilo dinamike. Per tio, oni klare distingas " +"intence nespecifitajn metadatenojn ne provizotajn far ilo, de metadatenoj " +"poste provizotaj far ilo." + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" +"Konstrua malfasado DEVAS observi statike specifitan metadatenon (de ŝlosilo " +"ne en ``dynamic``)." + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" +"Konstrua malfasado DEVAS sciigi pri eraro, se la metadatenoj specifas " +"``name`` en ``dynamic``." + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" +"Se la specifo de :ref:`kernaj metadatenoj ` priskribas kampon " +"kiel «Nedeviga», do la metadateno POVAS meti ĝin en ``dynamic``, se oni " +"atendas, ke konstrua malfasado poste provizos la datenon pri la ŝlosilo." + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" +"Konstrua malfasado DEVAS sciigi pri eraro, se la metadatenoj specifas unu " +"ŝlosilon kaj statike kaj en ``dynamic``." + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" +"Se la metadatenoj ne enhavas ŝlosilon en ``dynamic``, konstrua malfasado " +"DEVAS NE plenigi la medatenon por la uzanto (alivorte, ``dynamic`` estas la " +"ununura maniero por permesi al ilo plenigi metadatenojn, kaj la uzanto devas " +"eksplici la aŭtomatan plenigadon)." + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" +"Konstrua malfasado DEVAS sciigi eraron, se la metadatenoj specifas ŝlosilon " +"en ``dynamic`` sed la konstrua malfasado ne povis determini ĝian datenon " +"(estas akcepteble, se la ilo determinas, ke la dateno manku)." + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "Ĉiaj ilaj agordoj: la tabelo ``[tool]``" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" +"En subtabelo de la tabelo ``[tool]``, iu ajn ilo rilata al via Python-" +"projekto (ne nur konstruilo) povas havi agordojn. Ekzemple, la ilo `flit " +"`_ konservus siajn agordojn en " +"``[tool.flit]``." + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" +"Majo 2016: La unua specifo pri la dosiero ``pyproject.toml``, kun nur " +"``[build-system]`` enhavanta ŝlosilon ``requires`` kaj tabelon ``[tool]``, " +"estis aprobita per :pep:`518`." + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" +"Novembro 2020: La specifo de la tabelo ``[project]`` estis aprobita " +"per :pep:`621`." + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" +"Decembro 2024: La ŝlosilo ``license`` estis redifinita, la ŝlosilo ``license-" +"files`` estis aldonita, kaj la klasigiloj ``License::`` estis evitindigitaj " +"per :pep:`639`." + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "Registri instalitajn projektojn" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" +"Ĉi tiu dokumento specifas komunan dosierformon pri informoj pri " +"Python-:term:`projektoj ` instalitaj en medio. Komuna metadatena " +"dosierformo permesas serĉi, administri aŭ malinstali projektojn ĉiel " +"instalitajn." + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" +"Ĉiu projekto instalita el distribuo devas, krom dosieroj, instali dosierujon " +"``.dist-info`` apud la importeblaj moduloj kaj pakoj (ofte en la dosierujo " +"``site-packages``)." + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" +"Tiu dosierujo nomiĝas ``{name}-{version}.dist-info``, kun la kampoj ``name`` " +"kaj ``version`` same kiel :ref:`core-metadata`. Ambaŭ kampoj devas esti " +"normigitaj (vidu :ref:`la normon pri normigo de nomoj ` " +"kaj :ref:`la normon pri normigo de versioj `), kun streketoj (``-``) anstataŭigitaj per substreketoj " +"(``_``) , tiel ke la dosierujo ``.dist-info`` havas ekzakte unu streketon " +"(``-``) en ĝia nomo (krom la dosiersufikso), kiu apartigas la kampojn " +"``name`` kaj ``version``." + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" +"La nomo de dosierujo ``.dist-info`` estas aranĝita por malambigue prezenti " +"distribuon kiel dosiersisteman lokon. Ilo prezentanta nomon de distribuo al " +"uzanto evitu uzi la normigitan nomon kaj anstataŭe prezentu la specifitan " +"nomon (laŭbezone antaŭ solvado al instalita pako), aŭ legu la respektivajn " +"kampojn en Kernaj Metadatenoj, ĉar tieaj valoroj ne havas kodŝanĝojn kaj " +"precize reflektas la distribuon. Bibliotekoj provizu API pri la nenormigita " +"nomo por prezentado de informoj pri distribuo far tia ilo." + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" +"Tiu dosierujo ``.dist-info`` povas enhavi la jenajn dosierojn, priskribotajn " +"ĉi-sube:" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "``METADATA``: enhavas projektajn metadatenojn" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "``RECORD``: registras la liston de instalitaj dosieroj." + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" +"``INSTALLER``: registras la nomon de la ilo uzita por instali la projekton." + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "``entry_points.txt``: vidu :ref:`entry-points` por detaloj" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "``direct_url.json``: vidu :ref:`direct-url` por detaloj" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" +"La dosiero ``METADATA`` estas deviga. Ĉiuj aliaj dosieroj estas " +"preterlaseblaj laŭ la instalilo. Pliaj instalilo-specifaj dosieroj povas " +"ĉeesti." + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" +"Tiu dosierujo :file:`.dist-info/` povas enhavi la jenajn subdosierujojn, " +"priskribitajn ĉi-sube:" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr ":file:`licenses/`: enhavas licenco-dosierojn." + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" +"La specifo :ref:`binary-distribution-format` priskribas tiujn kromajn " +"dosierojn, kiuj povas aperi en la dosierujo ``.dist-info`` de :term:`Wheel`. " +"Tiaj dosieroj povas esti kopiitaj al la dosierujo ``.dist-info`` de " +"instalita projekto." + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" +"La antaŭaj versioj de ĉi tiu normo ankaŭ specifis la dosieron ``REQUESTED``. " +"Tiu dosiero estas nun rigardata kiel ilo-specifa etendaĵo, sed povas esti " +"normigita denove estontece. Vidu `PEP 376 `_ por ĝia originala signifo." + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "La dosiero METADATA" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" +"La dosiero ``METADATA`` enhavas metadatenojn laŭ la specifo :ref:`core-" +"metadata`, versio 1.1 aŭ pli nova." + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" +"La dosiero ``METADATA`` estas deviga. Se ĝi ne estas kreebla aŭ se " +"postulataj kernaj metadatenoj mankas, instalilo devas sciigi pri eraro kaj " +"malsukcesigi la instaladon de la projekto." + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "La dosiero RECORD" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" +"La dosiero ``RECORD`` tenas la liston de instalitaj dosieroj. Ĝi estas " +"diskoma dosiero enhavanta po unu rikordo (linio) por ĉiu instalita dosiero." + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" +"La dialekto de diskoma dosiero devas esti legebla per la apriora ``reader`` " +"de la modulo ``csv`` de Python:" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "Disigilo de kampoj: ``,`` (komo)," + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "Citilo: ``\"`` (neŭtra duobla citilo)," + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "linifino: aŭ ``\\r\\n`` aŭ ``\\n``." + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" +"Ĉiu rikordo konsistas el tri elemento: la dosierloko (**path**), la haketaĵo " +"(**hash**) de la enhavo, kaj la grando (**size**)." + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" +"La *path* povas esti aŭ malrelativa aŭ relativa al la dosierujo enhavanta la " +"dosierujon ``.dist-info`` (ordinare, la dosierujo ``site-packages``). Je " +"Windows, oni povas disigi dosierlokajn komponantojn per aŭ suprenstreko (``/" +"``) aŭ malsuprenstreko (``\\``)." + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" +"La *hash* estas aŭ malplena signoĉeno aŭ la nomo de haketaĵa algoritmo " +"el :py:data:`hashlib.algorithms_guaranteed`, sekvita de la egalsigno ``=`` " +"kaj la haketaĵo de la enhavo de la dosiero kodita laŭ urlsafe-base64-nopad " +"(:py:func:`base64.urlsafe_b64encode(haketaĵo) ` " +"sen fina ``=``)." + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" +"La *size* estas aŭ la malplena signoĉeno aŭ la grando de la dosiero en " +"bajtoj kiel dekuma entjero." + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" +"Por plene malinstali pakon, ilo devas forviŝi ĉiujn dosierojn en ``RECORD``, " +"ĉiujn dosierojn ``.pyc`` (de ajna optimumiga nivelo) respondantajn al " +"forviŝotaj ``.py``-dosieroj, kaj ajnaj dosierujoj malplenigotaj de la " +"malinstalo." + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "Jen ekzemplo de ebla dosiero ``RECORD``::" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" +"Se la dosiero ``RECORD`` mankas, ilo dependanta de ``.dist-info`` devas ne " +"provi malinstali aŭ ĝisdatigi la pakon. (Tiu devo ne temas pri ilo uzanta " +"aliajn informojn kiel sistema pakadministrilo de Linux-distribuo.)" + +#: ../source/specifications/recording-installed-packages.rst:172 +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 "" +"Ni *rekomendegas*, ke instalita pako ne modifu sin (ekz. per enkaŝmemorigo " +"de dosieroj sub sia nomspaco en ``site-packages``). Nur fakaj instaliloj " +"kiel pip modifu ``site-changes``. Se pako tamen tiel sin modifas, do ĝi " +"devas ĝisdatigu ``RECORD``; se tio ne okazus, malinstalado de pako lasus " +"eksterlistajn dosierojn (eble kreante fantoman nomspacan pakon)." + +#: ../source/specifications/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "La dosiero INSTALLER" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" +"Se dosiero ``INSTALLER`` ekzistas, ĝi estas unulinia teksta dosiero nomanta " +"la ilon uzitan por instali la projekton. Se la instalilo estas rulebla ĉe la " +"komandlinio, ``INSTALLER`` enhavu la nomon de la komando. Se ne, ĝi enhavu " +"preseblan Askian signoĉenon." + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "La dosiero povas finiĝi per nul aŭ pli da Askiaj blankspacaj signoj." + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "Jen ekzemploj de du eblaj dosieroj ``INSTALLER``::" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" +"Tiu valoro estu uzata nur por informaj celoj. Ekzemple, se oni provus " +"malinstali projekton per iu ilo, sed la ilo ne trovus dosieron ``RECORD``, " +"ĝi povus sugesti, ke oni uzu la ilon nomitan en ``INSTALLER`` por malinstali." + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "La dosiero entry_points.txt" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" +"Ĉi tiun dosieron instalilo POVAS krei por indiki, ke pako enhavas " +"komponantojn malkovreblajn kaj uzeblajn de alia kodo, inkluzive de konzolaj " +"programetoj kaj aliaj programoj rulebligitaj de la instalilo." + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "Ĝia detala specifo troviĝas ĉe :ref:`entry-points`." + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "La dosiero direct_url.json" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" +"Tiu dosiero DEVAS esti kreita de instalilo dum instalado de distribuo pro " +"postulo specifitanta rektan retadresan referencon (inkluzive de " +"versikontrolsistema retadreso)." + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "La detala specifo troviĝas ĉe :ref:`direct-url`." + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "La dosierujo :file:`licenses/`" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "La subdosierujo :file:`sboms/`" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "Intence malhelpi ŝanĝi instalitajn pakojn" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "Por tio, rilataj iloj faru la jenon:" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" +"Kreu dosieron ``INSTALLER`` sciiganta pri la nomo de la ilo por mastrumi la " +"pakon (tio permesas al ilo scianta pri ``RECORD`` provizi bonajn erarojn pri " +"modifado de rilataj pakoj)" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" +"Kelkfoje, oni bezonas malhelpi eĉ instaladon de pliaj pakoj per Python-" +"specifaj iloj. Tiukaze vidu :ref:`externally-managed-environments`" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" +"Junio 2009: La originala versio de ĉi tiu specifo estis aprobita " +"per :pep:`376`. Tiam, ĝi nomiĝis la *Datenbanko de Instalitaj Python-" +"Distribuoj*." + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" +"Marto 2020: La specifo de la dosiero ``direct_url.json`` estis aprobita " +"per :pep:`610`. Ĉi tiu paĝo nur mencias ĝin; vidu :ref:`direct-url` por la " +"plena difino." + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" +"Septembro 2020: Diversaj amendoj kaj klarigoj estis aprobitaj per :pep:`627`." + +#: ../source/specifications/schemas/index.rst:4 +#, fuzzy +#| msgid "Data schema" +msgid "PyPA schemas" +msgstr "Datena skemo" + +#: ../source/specifications/schemas/index.rst:6 +#, fuzzy +#| msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgid "`direct_url.json `_" +msgstr "``direct_url.json``: vidu :ref:`direct-url` por detaloj" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../source/specifications/section-distribution-formats.rst:3 +msgid "Package Distribution File Formats" +msgstr "Pako-Distribuaj Dosierformoj" + +#: ../source/specifications/section-distribution-metadata.rst:3 +msgid "Package Distribution Metadata" +msgstr "Pako-Distribuaj Metadatenoj" + +#: ../source/specifications/section-installation-metadata.rst:3 +msgid "Package Installation Metadata" +msgstr "Pako-Instalaj Metadatenoj" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "Pakindeksaj Interfacoj" + +#: ../source/specifications/section-python-description-formats.rst:3 +msgid "Python Description Formats" +msgstr "Python-Priskribaj Formoj" + +#: ../source/specifications/section-reproducible-environments.rst:3 +#, fuzzy +#| msgid "Virtual Environment" +msgid "Reproducible Environments" +msgstr "Virtuala Medio" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "Simpla deponeja API" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" +"La ŝlosilvortoj **«DEVAS» (MUST, SHALL)**, **«DEVAS NE» (MUST NOT, SHALL " +"NOT)**, **«POSTULATA» (REQUIRED)**, **«-U» (SHOULD)**, **«NE -U» (SHOULD " +"NOT)**, **«REKOMENDATA» (RECOMMENDED)**, **«POVAS» (MAY)** kaj **«NEDEVIGA» " +"(OPTIONAL)**\" en ĉi tiu dokumento estas interpretataj laŭ :rfc:`2119`." + +#: ../source/specifications/simple-repository-api.rst:13 +#, fuzzy +#| msgid "" +#| "The interface for querying available package versions and retrieving " +#| "packages from an index server comes in two forms: HTML and JSON." +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" +"La interfaco por peti informojn pri haveblaj versioj de pakoj kaj akiri " +"pakojn el indeksa servilo havas du formojn: HTML kaj JSON." + +#: ../source/specifications/simple-repository-api.rst:21 +#, fuzzy +#| msgid "Base HTML API" +msgid "Base API" +msgstr "Baza HTML API" + +#: ../source/specifications/simple-repository-api.rst:23 +#, fuzzy +#| 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/``." +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/``." +msgstr "" +"Deponejo realiganta la simplan API estas difinita de sia baza retadreso. Tiu " +"estas la supranivela URL, sub kiuj ĉiaj aliaj retadresoj ĉeestas. La API " +"nomiĝas «simpla», ĉar la baza retadreso de PyPI estas ``https://pypi.org/" +"simple/``." + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" +"Ĉiuj sekvaj retadresoj en ĉi tiu dokumento estos relativaj al tiu baza " +"retadreso. (Ekzemple, pri retadreso de PyPI, ``/foo/`` respondos al " +"``https://pypi.org/simple/foo/``." + +#: ../source/specifications/simple-repository-api.rst:33 +msgid "Normalized Names" +msgstr "Normigitaj Nomoj" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" +"Ĉi tiu specifo referencas la koncepton de «normigita» projekta nomo. " +"Laŭ :ref:`la specifo pri normigo de nomoj `, la validaj " +"skrisbignoj en nomo estas Askiaj literoj, Asikaj ciferoj, ``.``, ``-``, kaj " +"``_``. La nomo estu minuskligita, kun sinsekvoj de ``.``, ``-``, aŭ ``_`` " +"anstataŭigitaj per unu skribsigno ``-``. Oni povas fari tion en Python per " +"la modulo ``re``::" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "Versiado de la Simpla API de PyPI" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "Tio aspektus jene:" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "Dum interpretado de la deponeja versio:" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" +"Alkremento de la maĵora versio signifas neretrokongruan ŝanĝon tian, ke " +"ekzistanta kliento supozeble ne plu povas signife uzi la API." + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" +"Alkremento de la minora versio signifas retrokongruan ŝanĝon tian, ke " +"ekzistantaj klientoj verŝajne povas daŭre signife uzi la API." + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" +"La aŭtoroj de ĉi tiu normo atendas, ke la maĵora versio neniam " +"alkrementiĝos, kaj ajna estonta grava evoluo de la API uzos alian meĥanismon " +"por API-evoluo. Tamen la maĵora versio inkluziviĝas por malambiguigi kun " +"estontaj versioj (ekz. pri hipoteza simpla API v2, kiuj ĉeestus ĉe /v2/, " +"estus konfuza, se la deponejo-versio estus ≥2)." + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "Versio-historio de la API" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" +"Tiu sekcio enhavas nur mallongan historion de ŝanĝoj laŭ la versia numero de " +"la API. Por plena historio de ŝanĝoj inkluzive de ŝanĝoj faritaj antaŭ " +"ekstarigo de versioj de la API, vidu :ref:`la Historion `." + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" +"Versio 1.0 de la API: la unua versio de la API, deklarita per :pep:`629`." + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" +"Versio 1.1. de la API: Aldonis la metadatenojn ``versions``, " +"``files[].size``, kaj ``files[].upload-time`` al la JSON-seriigo, " +"deklaritajn per :pep:`700`." + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" +"Versio 1.2 de la API: aldonis deponejajn metadatenojn pri «spurado», " +"deklaritajn per :pep:`708`." + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" +"Versio 1.3 de la API: aldonis metadatenojn pri originpruvo, deklaritajn " +"per :pep:`740`." + +#: ../source/specifications/simple-repository-api.rst:100 +#, fuzzy +#| msgid "" +#| "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" +"Versio 1.3 de la API: aldonis metadatenojn pri originpruvo, deklaritajn " +"per :pep:`740`." + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "Klientoj" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" +"Kliento interaganta kun la simpla API **INSPEKTU** ĉiun respondon pri la " +"deponeja versio. Se tiu dateno mankas, la kliento **DEVAS** supozi, ke ĝi " +"estas versio 1.0." + +#: ../source/specifications/simple-repository-api.rst:109 +msgid "" +"When encountering a major version greater than expected, clients **MUST** " +"hard fail with an appropriate error message for the user." +msgstr "" +"Renkontinte maĵoran version pli grandan ol la atenditan, kliento **DEVAS** " +"malsukcesi kun taŭga erarmesaĝo por la uzanto." + +#: ../source/specifications/simple-repository-api.rst:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" +"Renkontinte minoran version pli grandan ol la atenditan, kliento **AVERTU** " +"la uzanton kun taŭga mesaĝo." + +#: ../source/specifications/simple-repository-api.rst:115 +msgid "" +"Clients **MAY** still continue to use feature detection in order to " +"determine what features a repository uses." +msgstr "" +"Kliento **POVAS** daŭre uzi detektadon de funkcioj por determini la " +"funkciojn uzatajn de iu deponejo." + +#: ../source/specifications/simple-repository-api.rst:121 +#, fuzzy +#| msgid "JSON Serialization" +msgid "HTML Serialization" +msgstr "JSON-igo" + +#: ../source/specifications/simple-repository-api.rst:125 +#, fuzzy +#| msgid "" +#| "The following constraints apply to all JSON serialized responses " +#| "described in this spec:" +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" +"La sekvaj limigoj validas por ĉiuj JSON-seriigitaj respondoj priskribitaj en " +"ĉi tiu specifo:" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +msgid "Project List" +msgstr "Listo de Projektoj" + +#: ../source/specifications/simple-repository-api.rst:135 +#, fuzzy +#| 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:" +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." +msgstr "" +"En deponejo, la radika retadreso (``/`` por ĉi tiu specifo, reprezentanta la " +"bazan retadreson) **DEVAS** esti valida HTML5-paĝo kun ankraj elementoj po " +"unu por ĉiu projekto en la deponejo. La teksto de la ankra elemento " +"**DEVAS** esti la nomo de la projekto, kaj la atributo ``href`` **DEVAS** " +"ligi al la retadreso de tiu projekto. Ekzemple:" + +#: ../source/specifications/simple-repository-api.rst:139 +#, fuzzy +#| 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:" +msgid "" +"The text of each 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 "" +"En deponejo, la radika retadreso (``/`` por ĉi tiu specifo, reprezentanta la " +"bazan retadreson) **DEVAS** esti valida HTML5-paĝo kun ankraj elementoj po " +"unu por ĉiu projekto en la deponejo. La teksto de la ankra elemento " +"**DEVAS** esti la nomo de la projekto, kaj la atributo ``href`` **DEVAS** " +"ligi al la retadreso de tiu projekto. Ekzemple:" + +#: ../source/specifications/simple-repository-api.rst:156 +#: ../source/specifications/simple-repository-api.rst:473 +msgid "Project Detail" +msgstr "Projekta Detalo" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +#, fuzzy +#| msgid "" +#| "The repository **SHOULD** provide the hash of the Core Metadata file as " +#| "the ``data-core-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." +msgid "" +"Each file 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 "" +"La deponejo **PROVIZU** la haketaĵon de la dosiero de Kernaj Metadatenoj " +"kiel la valoron de la atributo ``data-core-metadata`` laŭ la sintakso " +"``=``, en kiu ```` " +"estas la minuskla nomo de la uzita haketaĵa funkcio kaj ```` estas la deksesume kodita valoro de la haketaĵa funkcio. La " +"deponejo **POVAS** uzi ``true`` kiel la valoron de la atributo, se haketaĵo " +"ne estas disponebla." + +#: ../source/specifications/simple-repository-api.rst:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "Aldone al ĉi-supro, ekzistas la jenaj limigoj pri la API:" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" +"Ĉiu URL respondanta per HTML-paĝo **DEVAS** finiĝi per ``/``. La deponejo " +"**REDIREKTU** URL sen ``/`` al URL kun sufiksa ``/``." + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "URL povas esti aŭ absoluta aŭ relativa, se ĝi montras la ĝustan lokon." + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" +"Ekzistas nenia limigo pri kie la dosieroj ĉeestu relative al la deponejo." + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"There may be any other HTML elements on the API pages as long as the " +"required anchor elements exist." +msgstr "" +"Povas ekzisti aliaj HTML-elementoj sur la API-paĝo, se la postulataj ankraj " +"elementoj ekzistas." + +#: ../source/specifications/simple-repository-api.rst:192 +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." +msgstr "" +"Deponejo **POVAS** redirekti nenormigitan retadreson al la kanona normigita " +"retadreso (ekz. de ``/Foobar/`` al ``/foobar/``). Tamen, kliento **DEVAS " +"NE** dependi de tia redirektado kaj **DEVAS** peti la normigitan retadreson." + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" +"Deponejo **ELEKTU** haketfunkcion el unu el tiuj garantie disponeblaj ĉe la " +"modulo :py:mod:`hashlib` en la norma biblioteko de Python (aktuale ``md5``, " +"``sha1``, ``sha224``, ``sha256``, ``sha384``, ``sha512``). La nuna rekomendo " +"estas uzi ``sha256``." + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" +"Se ekzistas GPG-subskribo por iu distruo-dosiero, ĝi **DEVAS** ĉeesti apud " +"tiu dosiero kun la sama dosiernomo krom sufikso ``.asc``. Ekzemple, se la " +"dosiero ``/packages/SanktaGralo-1.0.tar.gz`` ekzistus kaj havus asociitan " +"subskribon, la subskribo troviĝus ĉe ``/packages/" +"SanktaGralo-1.0.tar.gz.asc``." + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" +"Deponejo **POVAS** inkluzivi atributon ``data-core-metadata`` sur dosiero-" +"hiperligo." + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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 "" +"La deponejo **PROVIZU** la haketaĵon de la dosiero de Kernaj Metadatenoj " +"kiel la valoron de la atributo ``data-core-metadata`` laŭ la sintakso " +"``=``, en kiu ```` " +"estas la minuskla nomo de la uzita haketaĵa funkcio kaj ```` estas la deksesume kodita valoro de la haketaĵa funkcio. La " +"deponejo **POVAS** uzi ``true`` kiel la valoron de la atributo, se haketaĵo " +"ne estas disponebla." + +#: ../source/specifications/simple-repository-api.rst:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" +"Deponejo **POVAS** inkluzivi atributon ``data-dist-info-metadata`` sur " +"dosiero-hiperligo." + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" +"Indekso-kliento **POVAS** uzi tiun ŝlosilon, se ĝi ekzistas, kiel evitindan " +"sinonimon de ``data-core-metadata``." + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" +"``data-dist-info-metadata`` estis normigita per :pep:`658`, kaj ĝia nomo " +"ŝanĝiĝis al ``data-core-metadata`` per :pep:`714`." + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" +"Deponejo **POVAS** inkluzivi atributon `data-gpg-sig`` sur dosiera hiperligo " +"kun valoro de aŭ ``true`` aŭ ``false`` por indiki, ĉu ekzistas GPG-" +"subskribo. Deponejo faranta tion **INKLUZIVU** ĝin sur ĉiu hiperligo." + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" +"Deponejo **POVAS** inkluzivi atributon ``data-requires-python`` sur dosiera " +"hiperligo. Tiu respondas al la metadatena kampo :ref:`core-metadata-requires-" +"python` por la eldono. Se tiu ekzistas, instalilo **IGNORU** la elŝuton por " +"instalado al Python-versio ne plenumanta la postulon. Ekzemple:" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" +"En la atributa valoro, < kaj > devas esti HTML-kodita kiel ``<`` and " +"``>`` respektive." + +#: ../source/specifications/simple-repository-api.rst:245 +#, fuzzy +#| msgid "" +#| "A repository **MAY** include a ``data-core-metadata`` attribute on a file " +#| "link." +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" +"Deponejo **POVAS** inkluzivi atributon ``data-core-metadata`` sur dosiero-" +"hiperligo." + +#: ../source/specifications/simple-repository-api.rst:247 +#, fuzzy +#| 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." +msgid "" +"The ``data-yanked`` attribute 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 "" +"Hiperligo en la simpla deponejo **POVAS** havi atributon ``data-yanked``, " +"kies valoro povas esti malplena aŭ esti ajna signoĉeno. La ĉeesto de " +"atributo ``data-yanked`` **ESTU** interpretata kiel indiko, ke la dosiero " +"montrata de la hiperligo estas fortirita kaj ĝenerale ne elektata de " +"instalilo krom specifaj kondiĉoj." + +#: ../source/specifications/simple-repository-api.rst:253 +#, fuzzy +#| 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." +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." +msgstr "" +"La valoro de la atributo ``data-yanked``, se ĝi ekzistas, estas arbitra " +"teksto pri la kialo de la fortiro. Ilo uzanta la simplan deponejan API " +"**POVAS** montri tiun tekston al uzanto." + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" +"Deponejo **POVAS** inkluzivi atributon ``data-provenance`` sur dosiera " +"hiperligo. La valoro de tiu atributo **DEVAS** esti plene kvalifikita URL, " +"asertante ke la originpruvo de la dosiero ĉeestas ĉe tiu URL. La URL " +"**DEVAS** prezenti `sekuran originon `_." + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" +"La atributo ``data-provenance`` estis aldonita por versio 1.3 de la API." + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" +"La formo de la ligita originpruvo estas difinita en :ref:`index-hosted-" +"attestations`." + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "Servi Distribuajn Metadatenojn per la Simpla Deponeja API" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" +"Se ekzistas atributo ``data-dist-info-metadata``, la deponejo **DEVAS** " +"provizi la Kernan Metadatenan dosieron de la distribuo apud la distribuo, " +"kun la sufikso ``.metadata`` post la dosiernomo de la distribuo. Ekzemple, " +"la Kernaj Metadatenoj de distribuo ĉe ``/dosieroj/distribuo-1.0-" +"py3.none.any.whl`` troviĝus ĉe ``/dosieroj/distribuo-1.0-" +"py3.none.any.whl.metadata``. Tio similas al la loko de la GPG-subskribo en " +"la :ref:`baza specifo de HTML API `." + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "Retrokongrueco" + +#: ../source/specifications/simple-repository-api.rst:321 +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 "" +"Se je ankra etikedo mankas la atributo ``data-dist-info-metadata``, ilo uzu " +"la aktualan konduton, elŝutante la distribuon kaj inspektante la " +"metadatenojn." + +#: ../source/specifications/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "JSON-baza Simpla API por Python-Pakindeksoj" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" +"Por ebligi analizi la sintakson de la respondo nur per la norma biblioteko, " +"ĉi tiu normo specifas, ke ĉiaj respondoj (krom la dosieroj mem kaj la HTML-" +"respondoj el :ref:`la baza normo pri HTML API ` " +"estu seriigitaj laŭ `JSON `_." + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" +"Simile al :ref:`la normo pri API-versioj `, oni DEVAS alkrementi la maĵoran versio-numeron, se ŝanĝoj al " +"la nova normo kaŭzus, ke ekzistanta kliento ne plu povos signife kompreni la " +"protokolon." + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" +"Simile, la minora versio **DEVAS** alkrementiĝi, se funkcioj estas aldonitaj " +"al aŭ malaldonitaj el la formo, sed ekzistanta kliento supozeble daŭre " +"komprenos la formon." + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" +"Ŝanĝoj, kiuj ne igus ekzistantajn klientojn ne plu kompreni la formon, kaj " +"kiuj ne aldonas aŭ forigas funkciojn, povas okazi sen ŝanĝado de la versia " +"numero." + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" +"Tio estas intencite malklara, ĉar la aŭtoroj de ĉi tiu normo kredas, la " +"aŭtoroj de verkotaj normoj ŝanĝantaj la API-on konsideru kaj decidu, ĉu " +"alkrementi la maĵoran aŭ minoran version." + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" +"Ĉi tiu normo intencas, ke oni rigardu la API kiel URL-funpunktojn " +"liverantajn datenojn, kies interpreton difinas la versio de tiuj datenoj, " +"seriigitajn laŭ la cela seriigita dosierformo." + +#: ../source/specifications/simple-repository-api.rst:390 +msgid "JSON Serialization" +msgstr "JSON-igo" + +#: ../source/specifications/simple-repository-api.rst:392 +#, fuzzy +#| 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." +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 "" +"La retadresa strukturo de la :ref:`specifo de la baza HTML API ` ankoraŭ validas, ĉar ĉi tiu specifo nur provizas plian " +"seriigan formon de jam ekzistanta API." + +#: ../source/specifications/simple-repository-api.rst:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" +"La sekvaj limigoj validas por ĉiuj JSON-seriigitaj respondoj priskribitaj en " +"ĉi tiu specifo:" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "Ĉiu JSON-respondo *ĉiam* estos JSON-objekto, ne tabelo aŭ alia tipo." + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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 "" +"Kvankam JSON ne indiĝene subtenas URL-datentipon, ajna valoro prezentanta " +"URL en ĉi tiu API povas esti aŭ absoluta aŭ relativa, se ĝi montras la " +"ĝustan lokon. Relativa valoro estas relativa al la aktuala URL, same kiel " +"HTML." + +#: ../source/specifications/simple-repository-api.rst:407 +msgid "" +"Additional keys may be added to any dictionary objects in the API responses " +"and clients **MUST** ignore keys that they don't understand." +msgstr "" +"Ekstraj ŝlosiloj povas esti aldonitaj al iuj ajn vortaraj objektoj en la API-" +"respondoj. Kliento **DEVAS** ignori ŝlosilojn ne kompreneblajn." + +#: ../source/specifications/simple-repository-api.rst:410 +msgid "" +"All JSON responses will have a ``meta`` key, which contains information " +"related to the response itself, rather than the content of the response." +msgstr "" +"Ĉiu JSON-respondo havas ŝlosilon ``meta`` enhavantan informojn pri la " +"respondo mem, ne pri la enhavo de la respondo." + +#: ../source/specifications/simple-repository-api.rst:413 +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 "" +"Ĉiu JSON-respondo havos ŝlosilon ``meta.api-version``, kiu estas teksto " +"enhavanta la versian numeron ``Maĵora.Minora`` de la :ref:`API-versia " +"specifo `, kun la sama semantiko pri " +"malsukceso/avertado kiel en :ref:`la API-versia specifo `." + +#: ../source/specifications/simple-repository-api.rst:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" +"Ĉiuj postuloj de :ref:`la baza HTML-API-specifo ` ne specifaj al HTML estas ankoraŭ observendaj." + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" +"Ŝlosiloj (en ajna nivelo) komenciĝanta per substreko estas rezervitaj por " +"privata uzado de indeksa servilo. Neniu estonta normo asignos signifon al " +"tia ŝlosilo." + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"The root URL ``/`` for this spec (which represents the base URL) will be a " +"JSON encoded dictionary which has a two keys:" +msgstr "" +"La projekta radika retadreso ``/`` por ĉi tiu specifo (kiu prezentas la " +"bazan retadreson) estas JSON-kodita vortaro kun du ŝlosiloj:" + +#: ../source/specifications/simple-repository-api.rst:433 +msgid "" +"``projects``: An array where each entry is a dictionary with a single key, " +"``name``, which represents string of the project name." +msgstr "" +"``projects``: Listo, kies ĉiu ero estas vortaro kun ununura ŝlosilo, " +"``nomo``, kies valoro estas signoĉeno de la projekta nomo." + +#: ../source/specifications/simple-repository-api.rst:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" +"``meta``: La ĝeneralaj respondaj metadatenoj laŭ `la priskribo ĉi-supra " +"`__." + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "Ekzemple:" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" +"Kvankam la ŝlosilo ``projects`` estas listo kaj tial devas esti ordita, " +"nek :ref:`la baza normo de HTML API ` nek ĉi tiu " +"normo postulas ian specifan ordon aŭ postulas, ke la ordo restu sama inter " +"petoj. Oni rigardu tion kiel aron, sed nek JSON nek HTML kapablas prezenti " +"aron." + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" +"La formo de ĉi tiu retadreso estas ``//``, en kiu ```` " +"estas anstataŭigita per la normigita nomo de la projekto laŭ :ref:`la " +"specifo de baza HTML API `. Do projekto nomita " +"«Ridinda_Piediro» havus la retadreson ``/ridinda-piediro/``." + +#: ../source/specifications/simple-repository-api.rst:480 +#, fuzzy +#| msgid "" +#| "This URL must respond with a JSON encoded dictionary that has four keys:" +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" +"Tiu URL devas respondi per JSON-kodita vortaro enhavanta kvar ŝlosilojn:" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "``name``: La normigita nomo de la projekto." + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +#, fuzzy +#| msgid "The ``versions`` key was added with API version 1.1." +msgid "The ``status`` key was added with API version 1.4." +msgstr "La ŝlosilo ``versions`` estis aldonita por versio 1.1 de la API." + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +#, fuzzy +#| msgid "The ``versions`` key was added with API version 1.1." +msgid "The ``reason`` key was added with API version 1.4." +msgstr "La ŝlosilo ``versions`` estis aldonita por versio 1.1 de la API." + +#: ../source/specifications/simple-repository-api.rst:505 +#, fuzzy +#| msgid "The ``versions`` key was added with API version 1.1." +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "La ŝlosilo ``versions`` estis aldonita por versio 1.1 de la API." + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "``files``: Listo de vortaroj, po unu por individua dosiero." + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" +"``versions``: Listo de versio-signoĉenoj specifantaj ĉiujn projektajn " +"versiojn alŝutitajn de la projekto. La valoro de ``versions`` estas logika " +"aro; tial, ĝi ne povas enhavi duoblaĵon, kaj la ordo de la versioj ne gravas." + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" +"Ĉiu dosiero en la ŝlosilo ``files`` DEVAS esti asociita kun unu el la " +"versioj en la ŝlosilo ``versions``. La ŝlosilo ``versions`` POVAS enhavi " +"version sen asociita dosiero (por versio sen âlsutita dosiero, se la servilo " +"subtenas tiaĵon)." + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "La ŝlosilo ``versions`` estis aldonita por versio 1.1 de la API." + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "Ĉiu individua dosiera vortaro havas la jenajn ŝlosilojn:" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "``filename``: La dosiernomo prezentata." + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "``url``: Retadreso, ĉe kiu oni povas elŝuti la dosieron." + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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 "" +"La vortaro ``hashes`` DEVAS ekzisti, eĉ se neniu haketaĵo disponeblas pri la " +"dosiero. Tamen, estas **REKOMENDEGATE** inkluzivi almenaŭ unu sekuran, " +"garantie haveblan haketaĵon." + +#: ../source/specifications/simple-repository-api.rst:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" +"``requires-python``: **Nedeviga** ŝlosilo por la metadatena kampo :ref:`core-" +"metadata-requires-python`. Se ĝi ekzistas, instalilo **IGNORU** la elŝuton " +"dum instalado al Python-versio ne plenumanta la postulon." + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" +"Malkiel ``data-requires-python`` en :ref:`la baza specifo de HTML API " +"`, la ŝlosilo ``requires-python`` ne postulas " +"specialan kodŝanĝadon alian ol la implicitan kodŝanĝon de JSON." + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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 "" +"``core-metadata``: **Nedeviga** ŝlosilo indikanta, ke metadatenoj de tiu " +"dosiero disponeblas ĉe la sama loko specifita en :ref:`la normo pri " +"metadatenaj dosiero por API ` " +"(``{file_url}.metadata``). Se ĝi ekzistas, ĝi **DEVAS** esti aŭ bulea valoro " +"(indikanta, ĉu asociita metadatena dosiero ekzistas) aŭ vortaro, kiu asocias " +"nomojn de haketaĵoj al deksesume koditaj haketaĵoj de la metadatenoj." + +#: ../source/specifications/simple-repository-api.rst:568 +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." +msgstr "" +"Se ĉi tiu estas vortaro da haketaĵoj kaj ne bulea valoro, do la postuloj kaj " +"rekomendoj por la ŝlosilo ``hashes`` ankaŭ validas por ĉi tiu ŝlosilo." + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" +"Se tiu ŝlosilo mankas, la metadateno-dosiero povas ekzisti aŭ ne. Se la " +"ŝlosila valoro estas vereca, la metadateno-dosiero ekzistas; se la ŝlosila " +"valoro estas malvereca, la metadateno-dosiero mankas." + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" +"Estas rekomendate, ke serviloj disponigu la haketaĵojn de la metadateno-" +"dosiero, se tio eblas." + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" +"``dist-info-metadata``: **Nedeviga**, evitinda sinonimo de ``core-metadata``." + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" +"Indekso-kliento **POVAS** uzi tiun ŝlosilon, se ĝi ekzistas, kiel evitindan " +"sinonimon de ``core-metadata``." + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" +"``dist-info-metadata`` estis normigita per :pep:`658`, kaj ĝia nomo ŝanĝiĝis " +"al ``core-metadata`` per :pep:`714`." + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" +"``size``: Ŝlosilo, kiu **DEVAS** ekzisti kaj **DEVAS** enhavi entjeron, kiu " +"estas la grando de la dosiero en bajtoj." + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "La ŝlosilo ``size`` estis aldonita por versio 1.1 de la API." + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" +"``upload-time``: Ŝlosilo kiu **POVAS** manki, kiu (se ĝi ekzistas) **DEVAS** " +"enhavi validan datotempan signoĉenon laŭ ISO 8601 en la formo ``jjjj-mm-" +"ttThh:mm:ss.ffffffZ``, kiu prezentas la tempon, kiam la dosiero estis " +"alŝutita al la indekso." + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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 "" +"Laŭ la sufikso ``Z``, la alŝuta tempo **DEVAS** esti la Universala " +"Kunordigita Tempo. La frakcia sekunda parto de la tempo (la parto " +"``.ffffff``) estas nedeviga kaj povas enhavi maksimume ses ciferojn. Se " +"servilo ne registras alŝutan tempon de dosiero, ĝi **POVAS** preterlasi la " +"ŝlosilon ``upload-time``." + +#: ../source/specifications/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "La ŝlosilo ``upload-time`` estis aldonita por versio 1.1 de la API." + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" +"``provenance``: **Nedeviga** ŝlosilo, kiu (se ĝi ekzistas) **DEVAS** esti aŭ " +"JSON-signoĉeno aŭ ``null``. Se ĝi ne estas ``null``, ĝi **DEVAS** esti " +"retadreso de la originpruvo asociita al la dosiero, kun la samaj reguloj " +"kiel ``data-provenance`` en la :ref:`normo pri la baza HTML API `." + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "La kampo ``provenance`` estis aldonita por versio 1.3 de la API." + +#: ../source/specifications/simple-repository-api.rst:670 +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 "" +"Kvankam la ŝlosilo ``files`` estas listo kaj tial devas esti ordita, " +"nek :ref:`la baza normo de HTML API ` nek ĉi tiu " +"normo postulas ian specifan ordon aŭ postulas, ke la ordo restu sama inter " +"petoj. Oni rigardu tion kiel aron, sed nek JSON nek HTML kapablas prezenti " +"aron." + +#: ../source/specifications/simple-repository-api.rst:679 +msgid "Content-Types" +msgstr "Content-Types" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" +"Ĉi tiu normo proponas, ke ĉiuj respondoj de la Simpla API havos norman " +"enhavtipon priskribantan kio la respondo estas (respondo de Simpla API), " +"kiun version de la API ĝi uzas, kaj kiun seriigan formon ĝi uzas." + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "La strukturo de ĉi tiu enhavtipo estos:" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "Tio signifas, ke por la ekzistanta API 1.0, la enhavtipoj estus:" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "**JSON:** ``application/vnd.pypi.simple.v1+json``" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "**HTML:** ``application/vnd.pypi.simple.v1+html``" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" +"Por ekzistanta kliento atendanta la ekzistantan API-respondon de :ref:`la " +"normo pri baza HTML API ` uzantan la enhavtipon " +"``text/html``, ĉi tiu normo difinas ``text/html`` kiel sinonimon de la " +"enhavtipo ``application/vnd.pypi.simple.v1+html`` ." + +#: ../source/specifications/simple-repository-api.rst:713 +msgid "Version + Format Selection" +msgstr "Elektado de Versio kaj Dosierformo" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" +"Por ebligi tion, ĉi tiu specifo normigas la uzadon de la `Servila Enhavo-" +"Marĉandado de HTTP `_." + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"While this spec won't fully describe the entirety of server-driven content " +"negotiation, the flow is roughly:" +msgstr "" +"Dum ĉi tiu specifo ne plene priskribas servilan enhavo-marĉandadon, la fluo " +"estas proksimume jena:" + +#: ../source/specifications/simple-repository-api.rst:726 +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 "" +"La kliento sendas HTTP-peton enhavantan ĉapon ``Accept`` listigantan ĉiujn " +"enhavtipojn de la formo versio+formo komprenatajn de la kliento." + +#: ../source/specifications/simple-repository-api.rst:728 +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: */*``)." +msgstr "" +"La servilo ekzamenas tiun ĉapon, elektas unu el la enhavtipoj en la listo, " +"kaj liveras respondon de tiu enhavtipo (la manko de ĉapo ``Accept`` estas " +"ekvivalenta al ``Accept: */*``)." + +#: ../source/specifications/simple-repository-api.rst:731 +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 "" +"Se la servilo ne subtenas iun ajn el la enhavtipoj en la ĉapo ``Accept``, ĝi " +"povas elekti inter la jenaj tri opcioj:" + +#: ../source/specifications/simple-repository-api.rst:735 +msgid "" +"Select a default content type other than what the client has requested and " +"return a response with that." +msgstr "" +"Elekti aprioran enhavtipon alian ol tiujn petitajn de la kliento kaj liveri " +"tian respondon." + +#: ../source/specifications/simple-repository-api.rst:737 +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." +msgstr "" +"Liveri HTTP-respondon ``406 Ne Akceptebla`` por sciigi, ke neniu el la " +"petitaj enhavtipoj estis disponeblaj, kaj la servilo ne volis aŭ ne povis " +"elekti aprioran respondan enhavtipon." + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"Return a HTTP ``300 Multiple Choices`` response that contains a list of all " +"of the possible responses that could have been chosen." +msgstr "" +"Liveri HTTP-respondon ``300 Pluraj Opcioj`` enhavantan liston de ĉiuj eblaj " +"respondoj, kiujn la kliento povas elekti." + +#: ../source/specifications/simple-repository-api.rst:742 +msgid "" +"The client interprets the response, handling the different types of " +"responses that the server may have responded with." +msgstr "" +"La kliento interpretas la respondon, pritraktante tiujn diversajn specojn de " +"respondoj, kiujn la servilo eble sendis." + +#: ../source/specifications/simple-repository-api.rst:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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 "" +"La ĉapo ``Accept`` estas kome disigita listo de enhavtipoj komprenataj kaj " +"pritrakteblaj de la kliento. Ĝu subtenas tri malsamjn formojn por ĉiu " +"pripetata enhavtipo:" + +#: ../source/specifications/simple-repository-api.rst:768 +msgid "``$type/$subtype``" +msgstr "``$tipo/$subtipo``" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "``$tipo/*``" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "``*/*``" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" +"Por elekti version kaj dosierformon, la plej utila el tiuj estas ``$tipo/" +"$subtipo``, ĉar tio estas la sola maniero specifi la deziratajn version kaj " +"dosierformon." + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" +"Tamen, kliento memoru, ke servilo rajtas elekti **ajnan* el la petitaj " +"enhavtipoj, malgraŭ la donitaj prioritatoj, kaj eĉ enhavtipon **ne** petitan." + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" +"Por helpi kliento determini la enhavtipon de la respondo al API-peto, ĉi tiu " +"specifo postulas, ke servilo ĉiam inkluzivu ĉapon``Content-Type`` pri la " +"enhavtipo de la respondo. Tio estas teĥnike ne retrokongrua ŝanĝo. Tamen " +"praktike `pip devigas ĉi tiun postulon `_. Tial la risko de reala rompo estas malgranda." + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "Jen ekzemplo de funkciado de kliento:" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" +"Se kliento volus nur subteni HTML aŭ JSON, do ĝi simple forigus nevolatan " +"enhavtipon el la ĉapo ``Accept``, tiel ke ricevi tion estus erare." + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "Alternativaj Marĉandaj Meĥanismoj" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "URL-Parametro" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" +"Servilo realiganta la Simplan API povas eble subteni retadresan parametron " +"nomitan ``format`` por peti specifan version de la retadreso." + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" +"La valoro de la parametro ``format`` estu **unu** el la validaj enhavtipoj. " +"Ne subtenataj estas pluraj enhavtipoj, ĵokero, kvalito-valoro ktp." + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" +"Ĉi tiu parametro ne estas subtenenda. Kliento **NE DEPENDU** de ĝi por " +"interagi kun la API. La marĉanda meĥanismo estas por pli facila homa " +"esplorado de la API en TTT-legilo aŭ por permesi hiperligon al specifa " +"versio kaj formo en dokumentaro aŭ notoj." + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" +"Servilo ne subtenanta tiun parametron povas raporti eraron se ĝi ĉeestas aŭ " +"simple ignori ĝin." + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "Agordado de Finpunkto" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" +"Tiu opcio teĥnike ne estas speciala opcio, sed nur natura konsekvenco de la " +"uzadon de enhavo-marĉandado, permesante al servilo elekti sian aprioraĵon el " +"la haveblaj enhavtipoj." + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" +"Se servilo ne volas aŭ ne povas subteni la servila enhavomarĉandado kaj " +"volas postuli, ke uzanto eksplicu la deziratan version, tio estas permesata." + +#: ../source/specifications/simple-repository-api.rst:903 +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 "" +"Por tio, servilo disponigu plurajn finpunktoj (ekzemple, ``/simple/v1+html/" +"`` kaj/aŭ ``/simple/v1+json/``) po unu por ĉiu paro de versio kaj " +"dosierformo subtenata. Ĉe finpunkto, servilo povas gastigi kopion de la " +"deponejo nur subtenanta unu (aŭ subaron) el la enhavtipoj. Kiam kliento " +"petas uzante la ĉapon ``Accept``, la servilo povas ignori tion kaj liveri la " +"enhavtipon por la finpunkto." + +#: ../source/specifications/simple-repository-api.rst:910 +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 "" +"Kliento, kiu volas postuli specifitan agordon, povas memori la version kaj " +"dosierformon de specifita deponeja retadreso, kaj (dum sendado de peto al " +"tiu servilo) sendi ĉapon ``Accept`` *nur* inkluzivantan la ĝustan enhavtipon." + +#: ../source/specifications/simple-repository-api.rst:918 +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." +msgstr "" +"Jen nedeviga paragrafo pri la plej bonaj aprioraj decidoj por realigi ĉi " +"tiun normon laŭ la opinioj de la aŭtoroj. Ĝi **ne** devige postulas tiajn " +"decidojn." + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "Ni rekomendas, ke serviloj faru la jenon:" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" +"Subtenu ĉiujn tri enhavtipojn priskribitajn en ĉi tiu normo, uzante servilan " +"marĉandadon, por tiel longe kiel oni racie povas, aŭ minimume tiel longe " +"kiel oni ricevas iom da trafiko uzanta la HTML-respondojn." + +#: ../source/specifications/simple-repository-api.rst:933 +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 "" +"Se servilo ricevas ĉapon ``Accept`` kiu ne enhavas ajnan konatan " +"dosiertipon, ĝi ne liveru respondon ``300 Multiple Choice``; anstataŭe ĝi " +"liveru respondon ``406 Not Acceptable``." + +#: ../source/specifications/simple-repository-api.rst:938 +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." +msgstr "" +"Tamen, se oni elektas uzi la finpunktan agordon, oni prefere liveru " +"respondon ``200 OK`` en la atendata enhavtipo de tiu finpunkto." + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "Ni rekomendas, ke klientoj faru la jenon:" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" +"Subtenu ĉiujn 3 enhavtipojn priskribitajn en ĉi tiu specifo, per servila " +"enhavo-marĉandado, tiel longe kiel racie eblas." + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" +"Dum konstruado de ĉapo ``Accept``, inkluzivu ĉiujn enhavtipojn subtenatajn." + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" +"La unu escepto al tiu rekomendo estas, ke estas rekomendate *inkluzivi* " +"valoron ``;q=0.01`` sur la malnova enhavtipo ``text/html``, krom se tiu " +"estas la sola enhavtipo, kiun vi petas." + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" +"Eksplicite elektu la version serĉatan, anstataŭ uzi la metadatenan version " +"``latest``, dum ordinara funkciado." + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" +"Kontrolu la ``Content-Type`` de la respondo, kaj certigu, ke ĝi kongruas kun " +"io atendata de vi." + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "Septembro 2015: unua versio de la HTML-formo, en :pep:`503`" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "Julio 2016: Metadateno Requires-Python, en ĝisdatigo al :pep:`503`" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "Majo 2019: Subteno de «fortiro», en :pep:`592`" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" +"Julio 2020: Versia konvencio de API kaj metadatenoj, kaj deklaro de la HTML-" +"formo kiel versio 1 de la API, en :pep:`629`" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" +"Majo 2021: provizi pakajn metadatenojn sendepende de pako, laŭ :pep:`658`" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" +"Majo 2022: komenca versio de la JSON-formo, kun meĥanismo por kliento elekti " +"inter ili, kaj deklaro de ambaŭ formoj kiel versio 1 de la API, en :pep:`691`" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" +"Oktobro 2022: projekta versio kaj dosiera grando kaj alŝuta tempo en la " +"formo JSON laŭ :pep:`700`" + +#: ../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 "" +"Junio 2023: ŝanĝi la nomon de la kampo provizantan pakajn metadatenojn " +"sendepende de pako laŭ :pep:`714`" + +#: ../source/specifications/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" +"Novembro 2024: originpruvaj metadatenoj en la formoj HTML kaj JSON, " +"en :pep:`740`" + +#: ../source/specifications/simple-repository-api.rst:990 +#, fuzzy +#| msgid "" +#| "November 2024: provenance metadata in the HTML and JSON formats, " +#| "in :pep:`740`" +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" +"Novembro 2024: originpruvaj metadatenoj en la formoj HTML kaj JSON, " +"en :pep:`740`" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "Fonta distribua formo" + +#: ../source/specifications/source-distribution-format.rst:8 +#, fuzzy +#| 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." +msgid "" +"The current standard 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 "" +"La aktuala norma dosierformo de fonta distribuo estas indikita per la " +"ekzisto de dosiero :file:`pyproject.toml` en la distribua arĥivo. La aranĝo " +"de tia distribuo estis originale specifita en :pep:`517` kaj estas formale " +"priskribita ĉi tie." + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "Fonta distribuo ankaŭ estas konata kiel *sdist* mallonge." + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "Fontarboj" + +#: ../source/specifications/source-distribution-format.rst:28 +#, fuzzy +#| 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." +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 used 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 "" +"*Fontarbo* estas kolekto de dosieroj kaj dosierujoj – kiel " +"versikontrolsistema kopio – kiu enhavas dosieron :file:`pyproject.toml` " +"uzeblan por konstrui fontan distribuon el la enhavitaj dosieroj kaj " +"dosierujoj. :pep:`517` kaj :pep:`518` difinas tion, " +"kion :file:`pyproject.toml` devas enhavi, por ke la kolekto rigardiĝas kiel " +"fontarbo." + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "Dosiernomo de fonta distribuo" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" +"La dosiernomo de fonta distribu estis normigita en :pep:`625`. La dosiernomo " +"devas esti en la formo ``{nomo}-{versio}.tar.gz``, en kiu ``{nomo}`` estas " +"normigita laŭ la samaj reguloj kiel por duumaj distribuoj (vidu :ref:`binary-" +"distribution-format`), kaj ``{versio}`` estas la kanonigita formo de la " +"projekta versio (vidu :ref:`version-specifiers`)." + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" +"La noma kaj versia komponantoj de la dosiernomo DEVAS kongrui kun la valoroj " +"en la metadatenoj en la dosiero." + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" +"Kodo generanta fonto-distribuan dosieron DEVAS nomi la dosieron laŭ ĉi tiu " +"specifo. Tio inkluzivas la hokon ``build_sdist`` de :term:`konstrua " +"malfasado `." + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "Dosierformo de fonta distribuo" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`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 "" +"Fonta distribuo ``.tar.gz`` (sdist) enhavas unu supranivelan dosierujon " +"nomitan ``{nomo}-{versio}`` (ekz. ``foo-1.0``), enhavantan la fontajn " +"dosierojn de la pako. La nomo kaj versio DEVAS kongrui kun la metadatenoj en " +"la dosiero. Tiu dosiero devas ankaŭ enhavi :file:`pyproject.toml` observanta " +"la formon difinitan en :ref:`pyproject-toml-spec`, kaj dosieron :file:`PKG-" +"INFO` enhavantan metadatenojn laŭ la formo difinita en la normo :ref:`core-" +"metadata`. La metadatenoj DEVAS konformi al almenaŭ versio 2.2 de la normo " +"pri metadatenoj." + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" +"Se la metadatena versio estas almenaŭ 2.4, la fonta distribuo DEVAS enhavi " +"ajnan licencan dosieron specifitan de la kampo ``License-File`` " +"en :file:`PKG-INFO` ĉe la respektivaj lokoj relativaj al la radika dosierujo " +"de la fonta distribuo (enhavanta la dosieron :file:`pyproject.toml` kaj la " +"metadateno-dosieron :file:`PKG-INFO`)." + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" +"Neniu alia enhavo de fonta distribuo estas postulata aŭ difinita. " +"Konstrusistemo povas enmeti iajn ajn informojn bezonatajn en la fontan " +"distribuon por konstrui la projekton." + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" +"La tar-arĥivo uzu la modernan pax-formon de POSIX.1-2001, kiu specifas UTF-8-" +"bazajn dosiernomojn. Speciale, dosiero de fonta distribuo devas esti legebla " +"per la norma biblioteka modulo ``tarfile`` kun la malferma flago ``'r:gz'``." + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "Trajtoj de fontdistribua arĥivo" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" +"Ĉar naiva malpakado de ``tar``-arĥivo danĝeras, kaj la rezultoj varias laŭ " +"platformo, arĥivaj funkcioj de fontaj distribuoj estas limigitaj." + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "Malpaki kun la datenfiltrilo" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" +"Dum malpakado de fonta distribuo, ilo DEVAS uzi " +"aŭ :py:func:`tarfile.data_filter` (ekz. :py:meth:`TarFile.extractall(..., " +"filter='data') `), AŬ sekvi la paragrafon " +"*Malpaki sen la datenfiltrilo* ĉi-sube." + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" +"Escepte, sur Python-interpretilo sen :py:func:`hasattr(tarfile, " +"'data_filter') ` (:pep:`706`), ilo ordinare uzanta tiun " +"filtrilon (rekte aŭ malrekte) POVAS averti la uzanton kaj ignori ĉi tiun " +"normon. La ilo pesu uzeblecon (ekz. plene fidi la arĥivon) kaj sekurecon " +"(e.g. rifuzi malpaki)." + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "Malpaki sen la datenfiltrilo" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" +"Ilo, kiu ne uzas la filtrilon ``data`` rekte (ekz. por retrokongrueco, por " +"permesi pliajn funkciojn, aŭ ne uzanta Python) DEVAS obei ĉi tiun " +"paragrafon. (Je la tempo de verkado, la filtrilo ``data`` ankaŭ obeas ĉi " +"tiun paragrafon, sed tio povas eksvalidiĝi estontece.)" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" +"La jenaj dosieroj ne validas en *fonta distribua* arĥivo. Trovante tian " +"eron, ilo SCIIGU la uzanton, DEVAS NE malpaki la eron, kaj POVAS malsukcesi:" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "Dosieroj, kiuj estus metitaj ekster la cela dosierujo." + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "Ligilo (simbola aŭ malmola) al loko ekster la cela dosierujo." + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "Aparatdosieroj (inkluzive de duktoj)." + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" +"La ĉi-subaj estas ankaŭ nevalidaj. Ilo POVAS, sed NE DEVAS, pritrakti ilin " +"same kiel la ĉi-supraĵojn:" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "Dosieroj kun la komponanto ``..`` en la dosiernomo aŭ ligila celo." + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "Ligiloj al dosiero, kiu ne estas parto de la arĥivo." + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" +"Ilo POVAS malpaki ligilon (simbolan aŭ malmolan) kiel ordinaran dosieron " +"uzante enhavon de la arĥivo." + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "Dum maldensigo de *fontdistribuaj* arĥivoj:" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" +"Komencaj suprenstrekoj en dosiernomo DEVAS esti senigitaj. (Tio estas " +"nuntempe norma konduto pri malpakado de ``tar``.)" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "Por ĉiu bito ``mode`` (de Unika permeso), ilo DEVAS:" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" +"aŭ uzi la aprioran valoron de la platformo por nova dosiero aŭ dosierujo " +"(respektive)," + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "aŭ agordi la biton laŭ la arĥivo," + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" +"aŭ uzi la biton el ``rw-r--r--`` (``0o644``) por nerulebla dosiero aŭ ``rwxr-" +"xr-x`` (``0o755``) por rulebla dosiero aŭ dosierujo." + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" +"La altaj bitoj ``mode`` (setuid, setgid, sticky) DEVAS esti malŝaltitaj." + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "Oni REKOMENDAS konservi la biton pri rulebleco far la uzanto." + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "Pluaj konsiloj" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" +"NI instigas aŭtorojn de iloj pripensi kiel la *hints for further " +"verification* en la dokumentaro de ``tarfile`` rilatas al la iloj." + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" +"Novembro 2020: La originala versio de ĉi tiu specifo estis aprobita " +"per :pep:`643`." + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "Julio 2021: Difinis fontarbon." + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" +"Septembro 2022: La dosiernomo de fonta distribuo estis normigita " +"per :pep:`625`." + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" +"Aŭgusto 2023: Trajtoj de fontdistribuaj arĥivoj estis normigitaj " +"per :pep:`721`." + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" +"Decembro 2024: inkluzivo de licenco-dosiero en fonta distribuo estis " +"normigita per :pep:`639`." + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "Versispecifiloj" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" +"Jen specifo pri skemo por identigi versiojn de Python-programaj distribuoj " +"kaj deklari dependecojn sur specifaj versioj." + +#: ../source/specifications/version-specifiers.rst:15 +msgid "Definitions" +msgstr "Difinoj" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +msgstr "" +"La ŝlosilvortoj «DEVAS» (MUST, SHALL), «DEVAS NE» (MUST NOT, SHALL NOT), " +"«POSTULATA» (REQUIRED), «-U» (SHOULD), «NE -U» (SHOULD NOT), «REKOMENDATA» " +"(RECOMMENDED), «POVAS» (MAY), kaj «NEDEVIGA» (OPTIONAL) en ĉi tiu dokumento " +"estas interpretataj laŭ :rfc:`2119`." + +#: ../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." +msgstr "" +"«Konstruilo» estas aŭtomata ilo por evoluada sistemo, produktanta fonto-" +"distribuajn kaj duum-distribuajn arĥivojn. Konstruilon integrilo povas " +"alvoki, por konstrui programon distribuitan kiel fontan distribuon, ne kiel " +"antaŭkonstruitan duuman arĥivon." + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" +"«Indekso-servilo» estas aktiva distribuo-registro eldonanta metadatenojn pri " +"versioj kaj dependecoj kaj limigas la permesatajn metadatenojn." + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" +"«Eldonilo» estas aŭtomata ilo ruliĝanta sur evoluada sistemo por alŝuti " +"fontajn kaj duumajn distribuajn arĥivojn al indeksoserviloj." + +#: ../source/specifications/version-specifiers.rst:32 +msgid "" +"\"Installation tools\" are integration tools specifically intended to run on " +"deployment targets, consuming source and binary distribution archives from " +"an index server or other designated location and deploying them to the " +"target system." +msgstr "" +"«Instalilo» estas integrilo specife por disponebligaĵoj, konsumanta fontan " +"aŭ duuman distribuan arĥivon el indeksa servilo aŭ alia provizita loko kaj " +"disponiganta ĝin al la cela sistemo." + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" +"«Aŭtomataj iloj» estas kolektiva esprimo inkluzivanta konstruilojn, " +"indeksoservilojn, eldonilojn, integrilojn kaj ajnajn aliajn programojn " +"produktantajn aŭ konsumantajn medatatenojn pri versioj kaj dependecoj de " +"distribuo." + +#: ../source/specifications/version-specifiers.rst:43 +msgid "Version scheme" +msgstr "Versia skemo" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" +"Distribuo estas identigita per publika versio-identigilo subtenanta ĉiujn " +"difinitajn versikomparajn operaciojn" + +#: ../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." +msgstr "" +"La versioskemo estas uzata kaj por priskribi la distribuversion disponigitan " +"de iu distribuo-arĥivo kaj ankaŭ por limigi la versiojn de dependaĵoj " +"necesaj por konstrui aŭ ruli la programon." + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "Publikaj versiidentigiloj" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "La kanona publika versia identigilo DEVAS observi la jenan skemon::" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" +"Publika versia identigilo DEVAS NE inkluzivi komencan aŭ finan blankan " +"spacon." + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "Publika versia identigilo DEVAS esti unika en iu distribuo." + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" +"Instalilo IGNORU ajnan publikan version, kiu ne observas tiun skemon, kaj " +"DEVAS inkluzivi la normigojn ĉi-subajn. Instalilo POVAS averti la uzanton, " +"kiam ĝi trovas neobservantajn aŭ ambiguajn versiojn." + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" +"Vidu ankaŭ :ref:`version-specifiers-regex`, kiu provizas regulan esprimon " +"por kontroli striktan konformecon al la kanona formo, kaj pli permeseman " +"regulan esprimon por tiuj enigaĵoj, kiujn oni devas normigi poste." + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "Publika versia identigilo konsistas el maksimume kvin segmentoj:" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "Epoka segmento: ``N!``" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "Eldona segmento: ``N(.N)*``" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "Antaŭeldona segmento: ``{a|b|rc}N``" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "Posteldona segmento: ``.postN``" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "Evoluada eldona segmento: ``.devN``" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" +"Ĉia eldono estas aŭ «fina eldono», aŭ «antaŭeldono», aŭ «posteldono» aŭ " +"«evolua eldono» laŭ la ĉi-subaj paragrafoj." + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" +"Ĉiu nombra komponanto DEVAS esti nenegativa entjero reprezentita kiel vico " +"de Askiaj ciferoj." + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" +"Ĉiu numera komponanto DEVAS esti interpretata kaj ordigita laŭ sia numera " +"valoro, ne kiel teksto." + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" +"Ĉia numera komponanto POVAS esti nulo. Krom la ĉi-suba paragrafo pri la " +"eldono-segmento, la numera komponanto nulo ne estas speciala; ĝi estas " +"simple la plej malgranda valoro je ordigado de versioj." + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" +"Kelkaj malfacile legeblaj versio-identigiloj estas permesataj de tiu skemo " +"por pli bone adapti al la larĝa gamo de versio-formoj en ekzistantaj " +"publikaj kaj privataj Python-projektoj." + +#: ../source/specifications/version-specifiers.rst:105 +msgid "" +"Accordingly, some of the versioning practices which are technically " +"permitted by the specification are strongly discouraged for new projects. " +"Where this is the case, the relevant details are noted in the following " +"sections." +msgstr "" +"Tial, kelkaj el la versiaj formoj teĥnike permesataj de la specifo estas " +"malrekomendegataj por novaj projektoj. Por tiaj kazoj, la ĉi-subaj " +"paragrafoj notas detalojn." + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "Loka versia identigilo DEVAS observi la jenan skemon::" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" +"Por certigi, ke loka versio-identigilo estu facile enmetebla en dosiernomojn " +"kaj retadresojn, kaj por eviti aranĝan malkoherecon pri deksesumaj prezentoj " +"de haketaĵoj, loka versio-etikedo DEVAS konsisti nur el la ĉi-subaj " +"permesataj skribsignoj:" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "Askiaj literoj (``[a-zA-Z]``)" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "Askiaj ciferoj (``[0-9]``)" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "punktoj (``.``)" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" +"Loka versia etikedo DEVAS komenciĝi kaj finiĝi per Askiaj literoj aŭ ciferoj." + +#: ../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 "" +"Komparo kaj ordigo de lokaj versioj temas pri ĉiu individua segmento de la " +"loka versio (apartigita de ``.``). Se segmento konsistas tute el Askiaj " +"ciferoj, tiu sekcio estas konsiderata kiel entjero por komparo; se segmento " +"enhavas ajnan Askian literon, tiu segmento estas komparata leksikografie " +"usklecblinde. Dum komparo inter numera kaj leksikografia segmentoj, la " +"numera sekcio ĉiam estas pli granda ol la leksikografia segmento. Plie, loka " +"versio kun pli granda nombro de segmentoj ĉiam estas pli granda ol loka " +"versio kun malpli da segmentoj, se la segmentoj de la pli mallonga loka " +"versio ekzakte egalas la komencon de la pli longa loka versio." + +#: ../source/specifications/version-specifiers.rst:160 +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." +msgstr "" +"«Suprula projekto» estas projekto, kiu difinas siajn publikajn versiojn. " +"«Malsuprula projekto» estas projekto, kiu spuras kaj redistribuas suprulan " +"projekton, eble kun sekurigaj flikoj kaj cimriparoj el pli novaj versioj de " +"la suprula projekto." + +#: ../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 "" +"Oni NE UZU lokan versio-identigilon por eldoni originan projekton al publika " +"indeksoservilo, sed POVAS uzi ĝin por identigi privatan konstruon kreitan " +"rekte el la projekta fonto. Repaka projekto UZU lokan versio-identigilon por " +"versio API-kongrua kun la versio de la origina projekto de la publika versio-" +"identigilo, sed kun pliaj ŝanĝoj (kiel cimriparoj). Ĉar la Python-Pakindekso " +"celas sole indeksi kaj gastigi originajn projektojn, ĝi DEVAS NE permesi la " +"uzon de loka versio-identigilo." + +#: ../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`)." +msgstr "" +"Fonta distribuo uzanta lokan versian identigilon PROVIZU la etendaĵan " +"metadatenon ``python.integrator`` (laŭ :pep:`459`)." + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "Finaj eldonoj" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" +"Versia identigilo konsistanta nur el eldona segmento kaj nedeviga epok-" +"identigilo nomiĝas «fina eldono»." + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" +"La eldona segmento konsistas el unu aŭ pluraj nenegativaj entjeraj valoroj, " +"apartigitaj per punktoj::" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" +"Finaj eldonoj por iu projekto DEVAS esti numeritaj alkremente. Alie, " +"aŭtomata ilo ne povus ĝisdatigi versiojn ĝuste." + +#: ../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 "" +"Komparado kaj ordigado de eldonsegmentoj uzas la nombran valoron de ĉiu " +"komponanto de la eldonsegmento. Dum komparado de eldonsegmentoj kun malsamaj " +"nombroj da komponantoj, la pli mallonga segmento plilongiĝas per nuloj por " +"egallongeco." + +#: ../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\")." +msgstr "" +"Dum la skemo permesas ajnan nombron da komponantoj post la unua, plej ofte " +"oni uzas du komponantojn («maĵora.minora») aŭ tri («maĵora.minora.mikroa»)." + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "Ekzemple::" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" +"Eldona serio estas aro de finaj eldonnumeroj komenciĝantaj per komuna " +"prefikso. Ekzemple, ``3.3.1``, ``3.3.5`` kaj ``3.3.9.45`` estas partoj de la " +"eldona serio ``3.3``." + +#: ../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." +msgstr "" +"``X.Y`` kaj ``X.Y.0`` ne distingiĝas kiel versiaj numeroj, ĉar la reguloj " +"pri komparado de eldonsegmentoj implicite plilongigas la du-komponantan " +"formon al ``X.Y.0`` por komparado al ajna eldonsegmento inkluzivanta tri " +"komponantojn." + +#: ../source/specifications/version-specifiers.rst:229 +#, fuzzy +#| msgid "" +#| "Date based release segments are also permitted. An example of a date " +#| "based release scheme using the year and month of the release::" +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 "" +"Datobaza eldonsegmento estas ankaŭ permesata. Jen ekzemplo de datobaza " +"eldonskemo uzanta la jaron kaj monaton de la eldono::" + +#: ../source/specifications/version-specifiers.rst:243 +msgid "Pre-releases" +msgstr "Antaŭeldonoj" + +#: ../source/specifications/version-specifiers.rst:245 +msgid "" +"Some projects use an \"alpha, beta, release candidate\" pre-release cycle to " +"support testing by their users prior to a final release." +msgstr "" +"Kelkaj projektoj uzas la antaŭeldonan ciklon «alfa, beta, eldonkandidato» " +"por helpi testadon far uzantoj antaŭ fina eldonado." + +#: ../source/specifications/version-specifiers.rst:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" +"Se antaŭeldono estas parto de la evolua ciklo de projekto, ĝi indikiĝas per " +"antaŭeldona segmento en la versia identigilo::" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" +"Versia identigilo konsistanta nur el eldona segmento kaj antaŭeldona " +"segmento nomiĝas «antaŭeldono»." + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +msgid "" +"Installation tools MAY accept both ``c`` and ``rc`` releases for a common " +"release segment in order to handle some existing legacy distributions." +msgstr "" +"Instalilo POVAS akcepti kaj ``c``- kaj ``rc``-eldonoj por la sama eldona " +"segmento por kongrueco kun kelkaj ekzistantaj malnovaj distribuoj." + +#: ../source/specifications/version-specifiers.rst:267 +msgid "" +"Installation tools SHOULD interpret ``c`` versions as being equivalent to " +"``rc`` versions (that is, ``c1`` indicates the same version as ``rc1``)." +msgstr "" +"Instalilo INTERPRETU ``c``-versiojn kiel ekvivalentojn de ``rc``-versioj " +"(alivorte, ``c1`` indikas la saman version kiel ``rc1``)." + +#: ../source/specifications/version-specifiers.rst:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" +"Konstruilo, eldonilo kaj indeksoservilo MALPERMESU la kreadon de kaj ``rc``- " +"kaj ``c``-eldonoj por la sama eldona segmento." + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "Posteldonoj" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" +"Kelkaj projektoj uzas posteldonon por korekti negravajn erarojn en fina " +"eldono ne efikantajn sur la distribuita programo (ekzemple, por korekti " +"eraron en la eldonaj notoj)." + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" +"Se posteldono estas parto de la evolua ciklo de projekto, ĝi indikiĝas per " +"posteldona segmento en la versia identigilo::" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" +"Versia identigilo inkluzivanta posteldonan segmenton sen evolueldona " +"segmento nomiĝas «posteldono»." + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" +"La posteldona segmento konsistas el la signoĉeno ``.post`` sekvita de " +"nenegativa entjero. Posteldono estas ordigita laŭ sia numera komponanto, tuj " +"post la respondanta eldono, kaj antaŭ ajna sekva eldono." + +#: ../source/specifications/version-specifiers.rst:296 +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 "" +"La uzo de posteldono por ripari faktan cimon estas malrekomendegata. " +"Ĝenerale, oni uzu pli longan eldonan numeron kaj alkrementu la finan " +"komponanton por ĉiu cimripara eldono." + +#: ../source/specifications/version-specifiers.rst:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "Posteldonoj estas ankaŭ permesataj por antaŭeldonoj::" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" +"Krei posteldono de antaŭeldono estas malrekomendegate, ĉar tio malfaciligas " +"la versio-identigilon por homoj. Ĝenerale, estas pli simple krei novan " +"antaŭeldonon alkrementante la numeran komponanton." + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "Evoluaj eldonoj" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" +"Kelkaj projektoj regule kreas evoluadajn eldonojn. Sistema pakanto (speciale " +"por Linux-distribuo) eble volas krei fruan eldonon rekte el fontarbo ne " +"konfliktantan kun postaj projektaj eldonoj." + +#: ../source/specifications/version-specifiers.rst:323 +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 "" +"Kiel parto de la evoluciklo de projekto, tiuj evoluaj eldonoj indikiĝas per " +"segmento de evolua eldono en la versia identigilo::" + +#: ../source/specifications/version-specifiers.rst:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" +"Versia identigilo inkluzivanta evolueldona segmento nomiĝas «evolua eldono»." + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "Evolua eldono estas ankaŭ permesata por antaŭeldono kaj posteldono::" + +#: ../source/specifications/version-specifiers.rst:346 +#, fuzzy +#| msgid "" +#| "Developmental releases are also permitted for pre-releases and post-" +#| "releases::" +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "Evolua eldono estas ankaŭ permesata por antaŭeldono kaj posteldono::" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" +"Evoluada eldono de posteldono estas ankaŭ malrekomendegata, sed ĝi eble " +"taŭgas por projekto uzanta la posteldonan notacion por plena flega eldono " +"eble inkluzivanta ŝanĝojn de kodo." + +#: ../source/specifications/version-specifiers.rst:364 +msgid "Version epochs" +msgstr "Versiaj epokoj" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" +"Se epoko ekzistas en versio-identigilo, ĝi ĉeestas antaŭ ĉiaj aliaj " +"komponantoj, apartigite el la eldono-segmento per krisigno::" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "Se la epoko ne estas eksplicita, la implicita epoko estas ``0``." + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" +"Multaj versio-identigiloj ne inkluzivas epokon, ĉar eksplicita epoko nur " +"necees, se projekto *ŝanĝas* la manieron de versia numerado tiel, ke la " +"ordinaraj reguloj pri ordigado de versioj estas malĝustaj. Ekzemple, se " +"projekto uzas dato-bazajn versiojn kiel ``2014.04`` kaj volas ŝanĝi al " +"semantikaj versioj kiel ``1.0``, do la novaj eldonoj estus rigardataj kiel " +"*pli malnovaj* ol la dato-bazaj eldonoj laŭ la ordinara ordigado::" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" +"Tamen, eksplicitante epokon, oni povas ŝanĝi la ordon, ĉar ĉiuj versioj de " +"pli posta epoko estas ordigitaj post versioj de pli frua epoko::" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +msgid "Normalization" +msgstr "Normigo" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "Usklecdistingo" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" +"Ĉiu Askia litero interpretiĝu usklecblinde en versio. La norma formo estas " +"minusklo. Tio permesas version kiel ``1.1RC1``, kies norma formo estas " +"``1.1rc1``." + +#: ../source/specifications/version-specifiers.rst:433 +msgid "Integer Normalization" +msgstr "Entjera Normigo" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" +"Ĉiu entjero interpretiĝas laŭ la apriora funkcio ``int()``, kaj la normigita " +"formo estas la teksta eligaĵo. Alivorte, la normigita formo de ``00`` estas " +"``0``, kaj la normigita formo de ``09000`` estas ``9000``. Tio ne temas pri " +"entjero en alfabetcifera segmento de loka versio kiel ``1.0+foo0100``, kiu " +"estas sia propra normigita formo." + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "Antaŭeldonaj apartigiloj" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" +"Antaŭeldono permesas la apartigilojn ``.``, ``-`` aŭ ``_`` inter la eldono-" +"segmento kaj la antaŭeldono-segmento. La norma formo ne uzas apartigilon. " +"Tio permesas versiojn kiel ``1.1.a1`` aŭ ``1.1-a1``, kies norma formo estas " +"``1.1a1``. Antaŭeldono ankaŭ permesas apartigilon inter la antaŭeldono-" +"specifilo kaj la numero. Tio permesas versiojn kiel ``1.0a.1``, kies norma " +"formo estas ``1.0a1``." + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "Literumado de antaŭeldono" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" +"Antaŭeldono permesas la literumaĵojn ``alpha``, ``beta``, ``c``, ``pre`` kaj " +"``preview`` por ``a``, ``b``, ``rc``, ``rc`` kaj``rc`` respektive. Tio " +"permesas versiojn kiel ``1.1alpha1``, ``1.1beta2`` kaj ``1.1c3``, kiuj estas " +"normigitaj al ``1.1a1``, ``1.1b2`` kaj ``1.1rc3``. Ĉiukaze la ekstra " +"literumaĵo ekvivalentas la norman formon." + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "Implicita antaŭeldona numero" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" +"Antaŭeldono permesas forlasi la numeron, kio implicas ``0``. La norma formo " +"eksplicas ``0``. Tio permesas versiojn kiel ``1.2a``, kies norma formo estas " +"``1.2a0``." + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "Posteldonaj disigiloj" + +#: ../source/specifications/version-specifiers.rst:475 +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 "" +"Posteldono permesas la apartigilojn ``.``, ``-`` aŭ ``_``, aŭ eĉ la mankon " +"de apartigilo. La norma formo uzas la apartigilon ``.``. Tio permesas " +"versiojn kiel ``1.2-post2`` aŭ ``1.2post2``, kies norma formo estas " +"``1.2.post2``. Simile al apartigilo de antaŭeldono, tio ankaŭ permesas " +"nedevigan apartigilon inter la posteldono-specifilo kaj la numero. Tio " +"permesas versiojn kiel ``1.2.post-2``, kies norma formo estas ``1.2.post2``." + +#: ../source/specifications/version-specifiers.rst:484 +msgid "Post release spelling" +msgstr "Posteldona literumado" + +#: ../source/specifications/version-specifiers.rst:486 +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 "" +"Posteldono ankaŭ permesas la literumaĵojn ``rev`` kaj ``r``. Tio permesas " +"versiojn kiel ``1.0-r4``, kies normigita formo estas ``1.0.post4``. Same " +"kiel antaŭeldono, la ekstraj literumaĵoj ekvivalentas la normigitajn formojn." + +#: ../source/specifications/version-specifiers.rst:493 +msgid "Implicit post release number" +msgstr "Implicita posteldona numero" + +#: ../source/specifications/version-specifiers.rst:495 +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 "" +"Posteldono permesas forlasi la numeron, kio implicas ``0``. La norma formo " +"eksplicas ``0``. Tio permesas versiojn kiel ``1.2post``, kies norma formo " +"estas ``1.2post0``." + +#: ../source/specifications/version-specifiers.rst:501 +msgid "Implicit post releases" +msgstr "Implicitaj posteldonoj" + +#: ../source/specifications/version-specifiers.rst:503 +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 "" +"Posteldono permesas la mankon de la signifilo ``post``. Por tiu formo, la " +"apartigilo DEVAS esti ``-``; neniu alia formo estas permesata. Tio permesas " +"versiojn kiel ``1.0-1``, kies norma formo estas ``1.0.post1``. Oni DEVAS NE " +"uzi tion kune kun la regulo de implicita posteldona numero. Alivorte, ``1.0-" +"`` *ne* validas, kaj ĝia norma formo *ne* estas ``1.0.post0``." + +#: ../source/specifications/version-specifiers.rst:512 +msgid "Development release separators" +msgstr "Disigiloj de evoluada eldono" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" +"Evoluada eldono permesas la apartigilojn ``.``, ``-``, aŭ ``_``, aŭ eĉ la " +"mankon de apartigilo. La norma formo uzas la apartigilon ``.``. Tio permesas " +"versiojn kiel ``1.2-dev2`` aŭ ``1.2dev2``, kies norma formo estas " +"``1.2dev2``." + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "Implicita evoluada eldona numero" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" +"Evoluada eldono permesas forlasi la numeron, kio implicas ``0``. La norma " +"formo eksplicas ``0``. Tio permesas versiojn kiel ``1.2.dev``, kies norma " +"formo estas ``1.2.dev0``." + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "Lokaj versiaj segmentoj" + +#: ../source/specifications/version-specifiers.rst:532 +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 "" +"Loka versio permesas, krom ``.`` kiel apartigilo de segmentoj, ankaŭ la " +"apartigiloj ``-`` kaj ``_``. La norma formo uzas ``.``. Tio permesas " +"versiojn kiel ``1.0+ubuntu-1``, kies norma formo estas ``1.0+ubuntu.1``." + +#: ../source/specifications/version-specifiers.rst:539 +msgid "Preceding v character" +msgstr "Prefiksa signo «v»" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "Komenca kaj Fina Blanka Spaco" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" +"Komenca kaj fina blankaj spacoj devas esti silente ignorata kaj forigita el " +"ĉiuj normigitaj formoj de versio. Tio inkluzivas ``\" \"``, ``\\t``, " +"``\\n``, ``\\r``, ``\\f``, kaj ``\\v``. Tio permesas racian pritraktadon de " +"senintenca blanka spaco, kiel ``1.0\\n``, kiu estas normigita al ``1.0``." + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "Ekzemploj de versiaj skemoj observantaj la regulojn" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "Simpla «maĵora.minora» versiado::" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "Simpla «maĵora.minora.mikroa» versiado::" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" +"«maĵora.minora» versiado kun alfa-, beta-, kaj kandidataj antaŭeldonoj::" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" +"«maĵora.minora» versiado kun evoluaj eldonoj, eldonkandidatoj kaj " +"posteldonoj por malgravaj korektoj::" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "Datobaza eldono, kun alkrementata numero en ĉiu jaro, sen nulo::" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "Resumo pri permesataj sufiksoj kaj relativa ordo" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" +"Ĉi tiu paragrafo estas por aŭtoroj de iloj aŭtomate pritraktantaj " +"distribuajn metadatenojn, ne aŭtoroj de Python-distribuoj elektantaj versian " +"skemon." + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" +"La epoka segmento de versio-identigilo DEVAS esti ordigita laŭ la nombra " +"valoro de la epoko. Se epoka segmento mankas, la implicita nombra valoro " +"estas ``0``." + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" +"La eldona segmento de versia identigilo DEVAS esti ordigita same kiel la " +"ordo de opoj en Python, kiam la normigita eldona segmento estas analizita " +"jene::" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" +"Ĉiuj eldono-segmentoj pri la komparo DEVAS esti samlongigitaj, metante " +"nulojn antaŭ pli mallongaj segmentoj laŭbezone." + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" +"Ene de numera eldono (``1.0``, ``2.7.3``), la ĉi-subaj sufiksoj estas " +"permesataj kaj DEVAS esti ordigitaj jene::" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" +"Notu, ke ``c`` semantike ekvivalentas ``rc`` kaj estas ordigita kvazaŭ ĝi " +"estis ``rc``. Ilo POVAS malakcepti la kazon de la sama ``N`` por kaj ``r`` " +"kaj ``rc`` en la sama eldonsegmento pro ambigueco kaj tamen observi la " +"specifon." + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" +"En alfa (``1.0a1``), beta (``1.0b1``) aŭ eldonkandidato (``1.0rc1``, " +"``1.0c1``), la ĉi-subaj sufiksoj estas permesataj kaj DEVAS esti ordigitaj " +"jene::" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" +"Ene de posteldono (``1.0.post1``), la jenaj sufiksoj estas permesataj kaj " +"DEVAS esti ordigitaj jene::" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" +"Notu, ke ``devN`` kaj ``postN`` DEVAS esti antaŭita de punkto, eĉ tuj post " +"numera versio (ekz. ``1.0.dev456``, ``1.0.post1``)." + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" +"En antaŭeldona, posteldona aŭ evoluada-eldona segmento kun komuna prefikso, " +"ordigado DEVAS esti laŭ la valoro de la numera komponanto." + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "Jen ekzemplo de multaj eblaj kombinaĵoj::" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "Ordigo de versioj trans diversaj metadatenaj versioj" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" +"Metadatenoj v1.0 (:pep:`241`) and Metadatenoj v1.1 (:pep:`314`) ne specifas " +"norman skemon pri identigado kaj ordigado de versioj. Tamen Metadatenoj v1.2 " +"(:pep:`345`) ja specifas skemon difinitan en :pep:`386`." + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" +"Pro la naturo de la simpla instalila API, instalilo ne povas scii la " +"metadatenan version uzatan de iu distribuo. Plie instalilo postulas la " +"kapablon krei sufiĉe prioritatigitan liston inkluzivantan ĉiom, aŭ tiom " +"multe kiom eblas, da versioj de projekto, por determini la instalotan " +"version. Tiaj postuloj necesigas normigadon al unu sintaksanaliza meĥanismo " +"uzenda por ĉiuj versioj de projekto." + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" +"Uzanto de distribuo povas deziri eksplicite forigi nekongruajn versiojn el " +"sia privata pakindekso." + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "Kongrueco kun aliaj versiaj skemoj" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" +"Kelkaj projektoj povas uzi versio-skemon, kiu postulas tradukadon por " +"observi la publikan versio-skemon difinitan en ĉi tiu specifo. Tiakaze, la " +"projekto-specifa versio povas esti konservita en la metadatenoj, dum la " +"tradukita publika versio estas en la versia kampo." + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" +"Tiu permesas al aŭtomata distribuilo ĝuste ordigi eldonojn dum aŭtoroj povas " +"uzi sian preferatan versian skemon por siaj projektoj." + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" +"`Semantika versiado `_ estas populara versio-identiga " +"skemo pli preskriba ol ĉi tiu specifo pri la signifo de elementoj de versia " +"numero. Eĉ se projekto elektas ne obei la detalojn de semantika versiado, " +"indas kompreni ĝin, ĉar ĝi diskutas multajn problemojn pri dependado de " +"aliaj distribuoj kaj pri eldonado de distribuo, de kiu aliaj dependas." + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" +"La aspekto «Maĵora.Minora.Flika» (en ĉi tiu normo, «maĵora.minora.mikroa») " +"de semantika versiado (paragrafoj 1–8 de la versio 2.0.0 de la normo) plene " +"kongruas kun la versia skemo en ĉi tiu specifo, kaj ni rekomendas observi " +"tian aspekton." + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" +"Semantika versio enhavanta streketon (antaŭeldonoj – paragrafo 10) aŭ " +"plusosigno (konstruoj – paragrafo 11) *ne* observas ĉi tiun specifon kaj " +"estas malpermesata en la publika versia kampo." + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" +"Unu meĥanismo por traduki tian semantikversio-bazan fonto-etikedon al " +"kongrua publika versio estas uzi la sufikson ``.devN`` por specifi la taŭgan " +"versian ordon." + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" +"Specifaj konstruaj informoj povas ankaŭ esti inkluzivitaj en lokaj versiaj " +"etikedoj." + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "Versiaj etikedoj per distribuita versikontrola sistemo" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" +"Multaj konstruiloj integras kun distribuitaj versikontrolsistemoj kiel Git " +"kaj Mercurial por aldoni identigan haketaĵon al la versio-identigilo. Ĉar " +"oni ne povas fidinde ordigi haketaĵojn, oni ne permesas tiajn versiojn en la " +"publika versio-kampo." + +#: ../source/specifications/version-specifiers.rst:776 +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 "" +"Same kiel semantika versio, la publika sufikso ``.devN`` malambigue " +"identigas tiajn eldonojn publike, dum la originala versikontrolsistema " +"etikedo povas esti unu el la projektaj metadatenoj." + +#: ../source/specifications/version-specifiers.rst:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" +"Loka versia etikedo ankaŭ povas inkluzivi identigan haketaĵan informon." + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "Versiado laŭ Olson-datenbanko" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" +"La projekto ``pytz`` heredas sian versian skemon el la versia skemo de la " +"horzono-datenbanko Olson: la jaron, sekvitan de minuskla litero de la versio " +"de la datenbanko en tiu jaro." + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" +"Tiu estas tradukebla al valida publika versio-identigilo kiel ``." +"``, en kiu la numero komenciĝas ĉe nulo aŭ unuo (por la eldono " +"``a``) kaj alkrementiĝas por ĉiu sekva datenbanka ĝisdatigo en la jaro." + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" +"Samkiel aliaj tradukitaj versiaj identigiloj, la respondanta versio de la " +"Olson-datenbanko povas esti registrita en la projektaj metadatenoj." + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" +"Versi-specifilo konsistas el serio de versio-kondiĉoj apartigitaj per komoj. " +"Ekzemple::" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "La kompara operatoro determinas la specon de versia kondiĉo:" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "``~=``: Kondiĉo `Kongrua eldono `_" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "``==``: Kondiĉo `Versia egaleco `_" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "``!=``: Kondiĉo `Ekskluzivo de versio `_" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" +"``<=``, ``>=``: Kondiĉo `Inkluziva orda komparo `_" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" +"``<``, ``>``: Kondiĉo `Ekskluziva orda komparo `_" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "``===``: Kondiĉo `Arbitra egaleco `_." + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" +"La komo («,») ekvivalentas al logika **kaj**-operatoro: kandidata versio " +"devas kongrui kun ĉiuj donitaj versio-kondiĉoj por kongrui kun la tuta " +"specifilo." + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" +"Blanka spaco inter kondiĉa operatoro kaj la sekva versia identigilo estas " +"nedeviga; same pri la blanka spaco ĉirkaŭ komo." + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" +"Krom la specife notitaj esceptoj ĉi-subaj, loka versia identigilo DEVAS NE " +"esti uzata en versio-specifilo, kaj oni DEVAS plene ignori lokan versian " +"etikedon dum kontrolado ĉu kandidata versio kongruas kun iu versio-specifilo." + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "Kongrua eldono" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" +"Kondiĉo de kongrua eldono konsistas el la operatoro de kongrua eldono ``~=`` " +"kaj versio-identigilo. Ĝi kongruas kun kandidata versio atendate kongrua kun " +"la specifita versio." + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" +"La specifita versio-identigilo devas esti en la norma formo laŭ `Versia " +"skemo `_. Loka versio-identigilo estas MALPERMESATA en ĉi " +"tiu versio-specifilo." + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" +"Por iu eldono-specifilo ``V.N``, la kondiĉo pri kongrua eldono estas " +"proksimume ekvivalenta al la jena paro de kondiĉoj::" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" +"Oni DEVAS NE uzi ĉi tiun operatoron kun unusegmenta versia numero kiel " +"``~=1``." + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "Ekzemple, la jenaj grupoj de versio-kondiĉoj estas ekvivalentaj::" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" +"Se antaŭeldono, posteldono aŭ evoluada eldono estas nomita en kondiĉo de " +"kongrua eldono kiel ``V.N.sufikso``, do la sufikso estas ignorita dum " +"determinado de la postulata prefiksa kongrueco::" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" +"La reguloj pri metado de nuloj por komparado de eldono-segmento signifas, ke " +"la supozata grado de kongrueco en kondiĉo pri kongruaj eldonoj estas " +"modifebla per nuloj ĉe la komenco de la versio-specifilo::" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "Versia egaleco" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" +"Versio-egaleca kondiĉo inkluzivas la versio-egalecan operatoron ``==`` kaj " +"versian identigilon." + +#: ../source/specifications/version-specifiers.rst:891 +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 "" +"La specifita versio-identigilo devas observi la norman formon priskribitan " +"en `Versia skemo `_, sed sufiksa ``.*`` estas permesata post " +"publika versio-identigilo jene." + +#: ../source/specifications/version-specifiers.rst:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" +"Ĉu aŭ ne strikta versio-egaleco taŭgas, dependas de la specifa uzkazo de la " +"versio-specifilo. Aŭtomata ilo almenaŭ AVERTU pri maltaŭga strikta versio-" +"egaleco kaj POVAS malakcepti ĝin." + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" +"Ekzemple, pri la versio ``1.1.post1``, la ĉi-subaj kondiĉoj estas plenumitaj " +"aŭ ne jene::" + +#: ../source/specifications/version-specifiers.rst:920 +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 "" +"Pri kongrueco de prefikso, la antaŭeldono-segmento havas implicitan " +"prefiksan ``.``. Tial, pri la versio ``1.1a1``, kaj jenaj kondiĉoj kongruus " +"aŭ ne kongruus jene::" + +#: ../source/specifications/version-specifiers.rst:928 +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::" +msgstr "" +"Ekzakta kongrueco implicas prefiksan kongruecon (tia interpreto estas " +"konsekvenco de la nulo-antaŭmeta regulo pri la eldonsegmento de versio-" +"identigilo). Pri la versio ``1.1``, la jenaj kondiĉoj kongruus aŭ ne jene::" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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 "" +"Se la specifita versio-identigilo estas publika versio-identigilo (sen loka " +"versio-etikedo), do la loka versio-etikedo de iu ajn kandidata versio DEVAS " +"ignoriĝi dum komputado de kongrueco inter versioj." + +#: ../source/specifications/version-specifiers.rst:957 +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:965 +msgid "Version exclusion" +msgstr "Ekskluzivo de versio" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" +"Versi-ekskluzivada kondiĉo konsistas el la versio-ekskluzivada operatoro ``!" +"=`` kaj versia identigilo." + +#: ../source/specifications/version-specifiers.rst:970 +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 "" +"La permesataj versio-identigiloj kaj la semantiko de komparado estas sama " +"kiel tiuj de la operatoro de `Versia egaleco `_, krom ke " +"la senco de kongrueco estas mala." + +#: ../source/specifications/version-specifiers.rst:983 +msgid "Inclusive ordered comparison" +msgstr "Inkluziva ordita komparo" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "La operatoroj de inkluziva orda komparo estas ``<=`` kaj ``>=``." + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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 "" +"Same kiel kongrueco de versioj, la eldonsegmento estas antaŭita de tiom da " +"nuloj, kiom necesas por certigi, ke la eldonsegmentoj kompariĝas je la sama " +"longo." + +#: ../source/specifications/version-specifiers.rst:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "Loka versia identigilo NE estas permesata en ĉi tiu versispecifilo." + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "Ekskluziva ordita komparo" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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 "" +"La eksluzive ordita komparo ``>V`` **DEVAS NE** permesi posteldonon de la " +"donito krom se ``V`` mem estas posteldono. Oni povas devigi, ke eldono estu " +"pli nova ol iu posteldono (inkluzive de pliaj posteldonoj), uzante " +"``>V.postN``. Ekzemple, ``>1.7`` permesas ``1.7.1`` sed ne ``1.7.0.post1``; " +"``>1.7.post2`` permesas ``1.7.1`` kaj ``1.7.0.post3`` sed ne ``1.7.0``." + +#: ../source/specifications/version-specifiers.rst:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" +"La ekskluziva orda komparo ``>V`` **DEVAS NE** kongrui kun loka versio de la " +"specifita versio." + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" +"Por referencoj al fonta arĥivo aŭ wheel, oni povas specifi atendatan " +"haketaĵan valoron inkluzivante eron ``=`` kiel parton de la URL-fragmento." + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" +"Por versikontrola sistemo ne ebliganta inkluzivi referencon al enmeto aŭ " +"etikedo rekte en la retadreson, oni povas postmeti tiajn informojn ĉe la " +"fino de la retadreso laŭ la notacio ``@`` aŭ " +"``@#``." + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" +"Tio ne estas *ekzakte* sama kiel la ekzistanta versikontrolsistemo-referenca " +"notacio de pip. Unue, la distribuonomo estas movita antaŭen, ne integrita " +"kiel parto de la retadreso. Due, la haketaĵo de la enmeto estas inkluzivita " +"eĉ dum prenado per etikedo, por plenumi la postulon, ke *ĉiu* hiperligo " +"inkluzivu haketaĵon por malhelpi falsadon (estas facile krei fideponejon kun " +"iu deponejo; estas malpli facile krei fideponejon kun specifa *haketaĵo*)." + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "Ekzemploj de foraj retadresoj::" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "Dosieraj retadresoj" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" +"Dosiera retadreso havas la formon ``file:///``. Se la " +"```` mankas, tio implicas ``localhost``. Eĉ se la " +"```` mankas, la tria suprenstreko DEVAS tamen ekzisti. La " +"```` difinas la dosierlokan vojon ĉe la dosiersistemo atingota." + +#: ../source/specifications/version-specifiers.rst:1184 +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 "" +"Sur la diversaj Unisekcaj mastrumaj sistemoj, la nuraj permesataj valoroj " +"por ```` estas manko, ``localhost``, aŭ alia plene kvalifikita " +"nomregno (FQDN), kiu egalas la gastiganton de la aktuala maŝino. Alivorte, " +"sur Unikso, la skemo ``file://`` nur povas atingi vojojn ĉe la loka maŝino." + +#: ../source/specifications/version-specifiers.rst:1189 +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 "" +"Sur Windows, la dosierformo inkluzivu la diskliteron, se tiu ekzistas, kiel " +"parton de la ```` (ekz. ``file:///c:/vojo/al/dosiero``). Malsimile al " +"Unikso, sur Windows la parametro ```` povas specifi foran " +"dosieron en reto. Alivorte, ``\\\\maŝino\\volumo\\dosiero`` tradukita al " +"``file://``-adreso estas ``file://maŝino/volumo/dosiero``. Por pliaj " +"informoj pri ``file://``-adresoj ĉe Windows, vidu `MSDN `_." + +#: ../source/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "Resumo pri diferencoj de pkg_resources.parse_version" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.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 "" +"Notu: tiu komparo estis al ``pkg_resources.parse_version``, kiam :pep:`440` " +"estis verkita. Post la aprobo de la PEP, setuptools 6.0 kaj postaj versioj " +"adoptis la konduton priskribitan ĉi tie." + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" +"Loka versio estas ordigita alimaniere. Ĉi tiu specifo postulas, ke loka " +"versio estu pli granda ol la sama versio sen loka versio, dum " +"``pkg_resources.parse_version`` konsideras ĝin kiel markon de antaŭeldono." + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" +"Ĉiu tiu specifo intence restriktas la sintakson de valida versio, dum " +"``pkg_resources.parse_version`` provas analizi *iun ajn* signoĉenon." + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" +"``pkg_resources.parse_version`` permesas iom ajn da versio-signifiloj kiel " +"``1.0.dev1.post1.dev5``. Ĉi tiu specifo, tamen, nur permesas nur unu uzon de " +"ĉiu tipo, en difinita ordo." + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "Apendico: Sintaksanalizi versian tekston per regulaj esprimoj" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" +"Por kontroli, ĉu versia identigilo estas en la kanona formo, oni povas uzi " +"la jenan funkcion:" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" +"Por eltiri la komponantojn de versia identigilo, uzu la jenan regulan " +"esprimon (difinitan de la projekto `packaging `_):" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "Aŭgusto 2014: Ĉi tiu specifo estis aprobita per :pep:`440`." + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "Virtualaj Python-Medioj" + +#: ../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 "" +"Por Python 3.3 kaj postaj versioj, :pep:`405` enkondukis interpretilo-" +"nivelan subtenon por la koncepto de «Virtuala Python-Medio». Ĉiu virtuala " +"medio havas sian propran Python-duumaĵon (ebligante kreadon de medioj kun " +"diversaj Python-versioj) kaj sian propran sendependan aron de instalitaj " +"Python-pakoj, sed komune kunhavas la norman bibliotekon kun la baza " +"instalita Python. Dum la koncepto de virtuala medio ekzistis antaŭ tiu " +"ĝisdatigo, mankis normigita meĥanismo por deklari aŭ malkovri ĝin." + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "Rultempa detektado de virtualaj medioj" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +msgstr "" +"Rultempe oni povas detekti virtualan medion kontrolante, " +"ĉu :py:data:`sys.prefix` (la dosiersistema loko de la rulata interpretilo) " +"diferencas de :py:data:`sys.base_prefix` (la apriora dosiersistema loko de " +"la normaj bibliotekoj)." + +#: ../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)." +msgstr "" +":ref:`venv-explanation` en la dokumentaro de la norma biblioteko de Python " +"pri :py:mod:`venv` diskutas tion, kune kun la koncepto de «aktivigo» de " +"virtuala medio en interaga mastrusistema ŝelo (tiu paŝo ne estas deviga, kaj " +"tial oni ne povas dependi de la ŝanĝoj pri aktivigo por detekti, ĉu programo " +"ruliĝas en virtuala medio)." + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "Deklari instalajn mediojn kiel virtualajn Python-mediojn" + +#: ../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." +msgstr "" +"Laŭ :pep:`405`, la plej simpla formo de virtuala Python-medio konsistas nur " +"el kopio aŭ simbola ligilo de Python-interpretilo kun dosierujo ``site-" +"packages`` kaj dosiero ``pyvenv.cfg`` kun ŝlosilo ``home`` pri la lokoj de " +"la moduloj de la norma biblioteko de Python." + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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 "" +"Eĉ se la dosiero ``pyvenv.cfg`` mankas, ajna maniero (ekz. " +"``sitecustomize.py``, modifi la instalitan Python-rultempon) kaŭzanta " +"malsamajn valorojn inter :py:data:`sys.prefix` " +"kaj :py:data:`sys.base_prefix`, dum kongrua apriora pak-instala skemo " +"ekzistas en :py:mod:`sysconfig`, detektiĝos kaj funkcios kiel virtuala medio " +"de Python." + +#: ../source/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "Majo 2012: Ĉi tiu specifo estis aprobita per :pep:`405`." + +#: ../source/specifications/well-known-project-urls.rst:5 +msgid "Well-known Project URLs in Metadata" +msgstr "Bone Konataj Projektaj Retadresoj en Metadatenoj" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" +"Ĉi tiu dokumento estas ĉefe por *konsumanto* de metadatenoj, kiu uzu la " +"regulojn pri normigado kaj liston de bone konataj etikedoj ĉi-subajn por " +"prezenti projektajn retadresojn unuforme tra la ekosistemo de Python." + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" +"Vidu :ref:`Verki vian pyproject.toml – retadresoj ` por diskuto pri elektado de projekta retadresa etikedo por la " +"metadatenoj de via pako." + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "Ĉi tiu specifo estis originale difinita en :pep:`753`." + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" +":pep:`753` evitindigas la metadatenajn kampojn :ref:`core-metadata-home-" +"page` kaj :ref:`core-metadata-download-url` (kiujn :ref:`core-metadata-" +"project-url` anstataŭas), kaj difinas normigan kaj serĉan procedon por " +"kontroli, ĉu ``Project-URL`` estas «bone konata», t.e. asignita al ``Home-" +"page``, ``Download-URL``, aŭ alia ofta projekta retadreso." + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" +"Per tio, indekso (kiel la Python-Pakindekso) kaj aliaj uzantoj de " +"metadatenoj povas prezenti projektajn retadresojn kohere." + +#: ../source/specifications/well-known-project-urls.rst:42 +msgid "Label normalization" +msgstr "Normigo de etikedo" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" +"Normigon de etikedoj faras la *uzantoj* de metadatenoj, ne la produktantoj " +"de metadatenoj." + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" +"Por determini ĉu etikedo ``Project-URL`` estas «bone konata», uzanto de " +"metadatenoj normigo la etikedon antaŭ ol kompari al la :ref:`listo de bone " +"konataj etikedoj `." + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" +"La normiga proceduro por etikedoj ``Project-URL`` estas difinita per la jena " +"Python-funkcio:" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" +"En ordinara lingvo: oni *normigas* etikedon forigante ĉiujn Askiajn " +"interpunkciojn kaj minuskligante la rezulton." + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" +"Jen tabelo da ekzemploj de etikedoj antaŭ normigo (krudaj) kaj post normigo:" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "Kruda" + +#: ../source/specifications/well-known-project-urls.rst:75 +msgid "Normalized" +msgstr "Normigita" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "``Homepage``" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "``homepage``" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "``Home-page``" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "``Home page``" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "``Change_Log``" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "``changelog``" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "``What's New?``" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "``whatsnew``" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "``github``" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "Bone konataj etikedoj" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" +"La listo de bone konataj etikedoj estas viva normo, mastrumata kiel parto de " +"ĉi tiu dokumento." + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" +"Jen tabelo de etikedoj bone konataj por montrado de metadatenoj ``Project-" +"URL``:" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "Etikedo (Home legebla ekvivalentaĵo)" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "Sinonimoj" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "``homepage`` (Homepage)" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "La ĉefpaĝo de la projekto" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "*(nenio)*" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "``source`` (Source Code)" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "La gastigita fontokodo aŭ deponejo de la projekto" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "``repository``, ``sourcecode``, ``github``" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "``download`` (Download)" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "Elŝuta retadreso por la distribuo, ekvivalenta al ``Download-URL``" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "``changelog`` (Changelog)" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "La plena ŝanĝoprotokolo de la projekto" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "``changes``, ``whatsnew``, ``history``" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "``releasenotes`` (Release Notes)" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "La eldonaj notoj de la projekto" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "``documentation`` (Documentation)" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "La Interreta dokumentaro de la projekto" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "``docs``" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "``issues`` (Issue Tracker)" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "La cimdatenbanko de la projekto" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "``funding`` (Funding)" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "Informoj pri Financado" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "``sponsor``, ``donate``, ``donation``" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" +"Uzanto de pakaj metadatenoj povas montri sinonimajn etikedojn same kiel la " +"«gepatran» bone konatan etikedon aŭ pli speciale." + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "Ekzempla konduto" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" +"Jen la fluo de projekta retadresa metadateno el ``pyproject.toml`` al kerna " +"metadateno al ebla indeksa prezento:" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "Ekzemplaj projektaj retadresoj por ordinara agordado" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "Prezento de kernaj metadatenoj" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "Ebla montrado" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" +"Notu, ke la kernaj metadatenoj aperas en la formo provizita de la uzanto (la " +"*produktanto* de metadatenoj ne normigas), sed la *konsumanto* de " +"metadatenoj normigas kaj identigas taŭgajn home legeblajn ekvivalentaĵojn " +"laŭ la normigitaj formoj:" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "``Home page`` fariĝas ``homepage``, kiu montriĝas kiel ``Homepage``" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" +"``DOCUMENTATION`` fariĝas ``documentation``, kiu montriĝas kiel " +"``Documentation``" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" +"``Repository`` fariĝas ``repository``, kiu montriĝas kiel ``Source Code``" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" +"``GitHub`` fariĝas ``github``, kiu montriĝas kiel ``Source Code (GitHub)`` " +"(specialaĵo de ``Source Code``)" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "Kiel Esti Helpata" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" +"Por subteno pri specifa projekto, vidu la hiperligojn ĉe la " +"paĝo :doc:`Projektoj `." + +#: ../source/support.rst:8 +msgid "" +"For something more general, or when you're just not sure, please `open an " +"issue `_ on the `packaging-problems `_ repository on GitHub." +msgstr "" +"Por io pli ĝenerala, aŭ se vi ne certas, bonvolu `raporti problemon `_ " +"pri la deponejo `packaging-problems `_ ĉe GitHub." + +#: ../source/tutorials/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "Krei dokumentaron" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" +"Jen forigita lernilo, ĉar ĝi ne estas rilata al pakado kaj ne estis " +"mastrumata. Bonvolu legi `la lernilon pri Sphinx `_ anstataŭe." + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" +"**Lernilo** estas opinihava paŝo-post-paŝa dokumento helpanta vin sci pli " +"pri konceptoj pri pakado. Por pli detalaj informoj pri specifaj temoj pri " +"pakado, vidu :doc:`/guides/index`." + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "Instali Pakojn" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" +"Jen paragrafo pri kiel instali Python-:term:`pakojn `." + +#: ../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 "" +"Notu, ke la esprimo «pako» en tiu kunteksto estas instalebla fasko da " +"programoj (t.e. sinonimo de :term:`distribuo `). Ĝi ne " +"signifas :term:`pakon `, kiun vi importas en via Python-" +"fontkodo (ujon de moduloj). La Python-komunumo ofte uzas la terminon «pako» " +"por signifi :term:`distribuon ` Ofte oni evitas la " +"terminon «distribuo», pro konfuzo kun Linux-distribuo aŭ pli granda " +"programdistribuo kiel Python mem." + +#: ../source/tutorials/installing-packages.rst:24 +msgid "Requirements for Installing Packages" +msgstr "Postuloj por Instali Pakojn" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" +"Jen paragrafo pri la paŝoj farendaj antaŭ ol instali aliajn Python-pakojn." + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +msgstr "Certigu, ke vi povas ruli Python komandlinie" + +#: ../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:" +msgstr "" +"Komence certigu, ke vi havas Python kaj ke la atendata versio disponiĝas ĉe " +"via komandlinio. Vi povas kontroli tion rulante la jenon:" + +#: ../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 "" +"Vi ricevu eligaĵon kiel ``Python 3.6.3``. Se vi ne havas Python, bonvolu " +"instali la plej novan version 3.x el `python.org`_ aŭ vidu la " +"paragrafon :ref:`Instali Python ` de la " +"dokumentaro." + +#: ../source/tutorials/installing-packages.rst:53 +msgid "If you're a newcomer and you get an error like this:" +msgstr "Se vi estas komencanto kaj ricevas eraron similan al la jeno:" + +#: ../source/tutorials/installing-packages.rst:62 +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." +msgstr "" +"Tio estas ĉar tiu komando kaj aliaj sugestataj komandoj en ĉi tiu lernilo " +"estu rulata en *ŝelo* (ankaŭ konata kiel *terminalo* aŭ *konzolo*). Vidu " +"`tiun lernilon `_ por enkonduko pri uzado de la " +"ŝelo de via mastruma sistemo kaj interagado kun Python." + +#: ../source/tutorials/installing-packages.rst:68 +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:" +msgstr "" +"Se oni uzas pliigitan ŝelon kiel IPython aŭ Jupyter-notlibron, oni povas " +"ruli sistemajn komandojn kiel tiujn en ĉi tiu lernilo per prefikso ``!``:" + +#: ../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 "" +"Ni rekomendas skribi ``{sys.Executable}`` prefere ol ``python`` por certigi, " +"ke komandoj ruliĝas en la Python-instalo kongrua kun la aktuale rulata " +"notlibro (kiu povas esti ne sama kiel la instalo de Python identigita de la " +"komando ``python``)." + +#: ../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 "" +"Pro la maniero, kiel multaj Linux-distribuoj pritraktas la migradon al " +"Python 3, uzanto de Linux uzanta la sisteman Python-on sen virtuala medio " +"unue devas anstataŭigi la komandon ``python`` en ĉi tiu lernilo per " +"``python3`` kaj la komandon ``python -m pip`` per ``python3 -m pip --user``. " +"*Ne* rulu ajnan komandon en ĉi tiu lernilo kun ``sudo``: se vi ricevas " +"eraron pri permesoj, reiru al la paragrafo pri kreado de virtuala medio, " +"kreu virtualan medion, kaj daŭru sekvante la lernilon laŭvorte." + +#: ../source/tutorials/installing-packages.rst:95 +msgid "Ensure you can run pip from the command line" +msgstr "Certigu, ke vi povas ruli pip ĉe la komandlinio" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" +"Krome, vi devas certigi, ke :ref:`pip` estas disponebla. Vi povas kontroli " +"tion rulante la jenon:" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" +"Se vi instalis Python el fontkodo, per instalilo el `python.org`_, aŭ per " +"`Homebrew`_, vi jam havas pip. Se vi uzas Linux kaj instalis Python per via " +"mastrumasistema pakadministrilo, vi eble bezonas aparte instali pip " +"laŭ :doc:`/guides/installing-using-linux-tools`." + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" +"Se ``pip`` ankoraŭ ne estas instalita, do unue provu estigi ĝin per la norma " +"biblioteko:" + +#: ../source/tutorials/installing-packages.rst:134 +msgid "If that still doesn't allow you to run ``python -m pip``:" +msgstr "Se tio ankoraŭ ne ebligas ruli ``python -m pip``:" + +#: ../source/tutorials/installing-packages.rst:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" +"Sekure elŝutu `get-pip.py `_ [1]_" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" +"Rulu ``python get-pip.py``. [2]_ Tio instalos aŭ ĝisdatigos pip. Krome, ĝi " +"instalos :ref:`setuptools` kaj :ref:`wheel`, se tiuj ne estas jam instalitaj." + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "Certigu, ke pip, setuptools kaj wheel estas ĝisdataj" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" +"Dum ``pip`` sole sufiĉas por instali el antaŭkonstruita duuma arĥivo, " +"ĝisdataj kopioj de la projektoj ``setuptools`` kaj ``wheel`` utilas por " +"instali el fonta arĥivo:" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "Nedevige, kreu virtualan medion" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"See :ref:`section below ` for " +"details, but here's the basic :doc:`venv ` [3]_ command " +"to use on a typical Linux system:" +msgstr "" +"Vidu :ref:`la ĉi-suban paragrafon ` " +"por detaloj, sed jen la baza komando de :doc:`venv ` " +"[3]_ por tipa Linux-sistemo:" + +#: ../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 "" +"Tio kreos novan virtualan medion en la subdosierujo ``tutorial_env`` kaj " +"igas la aktualan ŝelon uzi ĝin kiel la implicitan ``python``-medion." + +#: ../source/tutorials/installing-packages.rst:199 +msgid "Creating Virtual Environments" +msgstr "Krei Virtualajn Mediojn" + +#: ../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 "" +"«Virtuala Medio» de Python permesas instaladon de :term:`Python-pako " +"` en izolita loko por iu programo, ne instalita " +"malloke. Se vi volas sekure instali komandlinian ilon, vidu :doc:`/guides/" +"installing-stand-alone-command-line-tools`." + +#: ../source/tutorials/installing-packages.rst:207 +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." +msgstr "" +"Supozu, ke oni havas programon bezonantan version 1 de LibFoo, sed alia " +"programo bezonas version 2. Kiel oni povas uzi ambaŭ programojn? Se oni " +"instalus ĉion en /usr/lib/python3.6/site-packages (aŭ la norma loko por onia " +"platformo), oni ofte senintence ĝisdatigus programon ne ĝisdatindan." + +#: ../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 "" +"Aŭ pli ĝenerale, kio se oni volas instali programon kaj ne ŝanĝi ĝin? Se " +"programo funkcias, ajna ŝanĝo de ĝiaj bibliotekoj aŭ de la bibliotekaj " +"versioj povas misfunkciigi la programon." + +#: ../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 "" +"Ankaŭ, kio okazos, se oni ne povas instali :term:`pakon ` en la tutsisteman dosierujon ``site-packages``? Ekzemple, je " +"komuna gastiganto." + +#: ../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 "" +"En tiuj kazoj, virtuala medio povas helpi vin. Ĝi havas sian propran " +"instalan dosierujon kaj ne havas bibliotekon komunan kun aliaj virtualaj " +"medioj." + +#: ../source/tutorials/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "Aktuale ekzistas du oftaj iloj por krei virtualajn Python-mediojn:" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" +":doc:`venv ` estas apriore disponebla en Python 3.3 kaj " +"pli novaj, kaj instalas :ref:`pip` en la kreitan virtualan medion en Python " +"3.4 kaj pli novaj (versioj de Python antaŭ 3.12 ankaŭ " +"instalis :ref:`setuptools`)." + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" +":ref:`virtualenv` devas esti aparte instalita sed subtenas Python 2.7+ kaj " +"Python 3.3+. :ref:`pip`, :ref:`setuptools` kaj :ref:`wheel` estas instalitaj " +"en la kreitan virtualan medion apriore. Notu, ke ``setuptools`` ne plu estas " +"inkluzivita apriore ekde Python 3.12 (kaj ``virtualenv`` sekvas tion)." + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "Jen la baza uzmaniero:" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "Uzi :doc:`venv `:" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "Uzi :ref:`virtualenv`:" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" +"Plir pliaj informoj, vidu la dokumentaron pri :doc:`venv ` aŭ la dokumentaron pri :doc:`virtualenv `." + +#: ../source/tutorials/installing-packages.rst:271 +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)." +msgstr "" +"La uzo de :command:`source` en Unikseca ŝelo certigas, ke la variabloj de la " +"virtuala medio estas agorditaj ene de la aktuala ŝelo kaj ne en subprocezo " +"(kiu poste malaperos kaj estos efikinte neniel)." + +#: ../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 "" +"En ambaŭ ĉi-supraj kazoj, uzanto de Windows *ne* uzu la " +"komandon :command:`source`, sed preferu ruli la " +"programeton :command:`activate` rekte en la komanda ŝelo jene:" + +#: ../source/tutorials/installing-packages.rst:286 +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 "" +"Rekta administrado de multaj virtualaj medioj tedas, kaj la :ref:`lernilo " +"pri administrado de dependecoj ` enkondukas " +"plialtnivelan ilon :ref:`Pipenv`, kiu aŭtomate administras po unu aparta " +"virtuala medio por ĉiu projekto aŭ programo evoluigata de vi." + +#: ../source/tutorials/installing-packages.rst:293 +msgid "Use pip for Installing" +msgstr "Uzu pip por instali" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" +":ref:`pip` estas la rekomendata instalilo. Ĉi-sube, ni priskribos la plej " +"oftajn uzkazojn. Por pli da detaloj, vidu :doc:`la dokumentaron de pip " +"`, kiu inkluzivas plenan :doc:`Referencan Gvidilon `." + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "Instali el PyPI" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" +"La plej ofta uzmaniero de :ref:`pip` estas instalado el :term:`la Python-" +"Pakindekso ` per :term:`postulo-specifilo " +"`. Ĝenerale, postulo-specifilo konsistas el projekta " +"nomo sekvita de nedeviga :term:`versio-specifilo `. " +"Plena priskribo de la permesataj specifiloj troviĝas en la :ref:`Normo pri " +"versio-specifiloj `. Jen kelkaj ekzemploj." + +#: ../source/tutorials/installing-packages.rst:311 +msgid "To install the latest version of \"SomeProject\":" +msgstr "Por instali la plej novan version de «SomeProject»:" + +#: ../source/tutorials/installing-packages.rst:325 +msgid "To install a specific version:" +msgstr "Por instali specifan version:" + +#: ../source/tutorials/installing-packages.rst:339 +msgid "To install greater than or equal to one version and less than another:" +msgstr "" +"Por instali version ne malpli novan ol unu version kaj malpli novan ol alian:" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" +"Por instali version :ref:`kongruan ` " +"kun iu versio: [4]_" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" +"Tiukaze, tio signifas instali ajnan version «==1.4.*» ankaŭ plenumantan " +"«>=1.4.2»." + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "Fonto-Distribuoj kontraste kun Wheel-oj" + +#: ../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` povas instali aŭ :term:`fontan distribuon (sdist) ` aŭ :term:`Wheel `. Se ambaŭ ekzistas ĉe " +"PyPI, pip preferas kongruan :term:`wheel `. Oni povas ŝanĝi la " +"aprioran konduton de pip per la flago :ref:`--no-binary `." + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" +":term:`Wheel ` estas antaŭkonstruita :term:`distribua ` formo pli rapide instalebla ol :term:`Fonta Distribuo (sdist) " +"`, speciale por projekto enhavanta " +"tradukitan etendaĵon." + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" +"Se :ref:`pip` ne trovas instalotan wheel, ĝi loke konstruos wheel kaj " +"enkaŝmemorigi ĝin por estonteco anstataŭ rekonstruado de la fonta distribuo." + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "Ĝisdatigi jam instalitan ``SomeProject`` al la plej nova ĉe PyPI." + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "Instali al la Loko de la Uzanto" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" +"Por instali :term:`pakojn ` izolitajn al la aktuala " +"uzanto, uzu la flagon ``--user``:" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" +"Por pli da informoj, vidu la paragrafon `User Installs `_ de la dokumentaro de pip." + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +msgstr "" +"Notu, ke la flago ``-user`` havas neniun efikon ene de virtuala medio – ĉiaj " +"instalaj komandoj ŝanĝos la virtualan medion." + +#: ../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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" +"Sur Linux kaj macOS, vi povas trovi la bazan duumaĵan dosierujon de la " +"uzanto per ``python -m site --user-base`` kaj aldonanta ``bin`` al la fino. " +"Ekzemple, tio ordinare eligas ``~/.local`` (kun ``~`` anstataŭiigta per la " +"absoluta dosierloko de via hejma dosierujo); do vi aldonos ``~/.local/bin`` " +"al via ``PATH ``. Vi povas fiksi vian ``PATH`` `modifante ~/.profile " +"`_." + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" +"Sur Windows, oni povas trovi la bazan duumaĵan dosierujon de uzanto rulante " +"``py -m site --user-site`` kaj anstataŭigante ``site-packages`` per " +"``Scripts``. Ekzemple, la komando povus eligi ``C:" +"\\Users\\Salutnomo\\AppData\\Roaming\\Python36\\site-packages``, kaj oni " +"agordus sian ``PATH`` inkluzivante ``C:" +"\\Users\\Salutnomo\\AppData\\Roaming\\Python36\\Scripts``. Oni povas agordi " +"sian ``PATH`` malprovizore en la `Stirpanelo `_. Oni eble " +"devas adiaŭi por efektivigi la ŝanĝojn pri ``PATH``." + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" +"Instali liston de postuloj en :ref:`Postulo-Dosiero `." + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "Instali el Versikontrola Sistemo" + +#: ../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 `." +msgstr "" +"Instali projekton el versikontrola sistem en «redaktebla» reĝimo. Por " +"plenaj detaloj de la sintakso, vidu la dokumentaron de pip pri :ref:`Subteno " +"de Versikontrola Sistemo `." + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "Instali el aliaj Indeksoj" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "Instali el alternativa indekso" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" +"Dum instalado serĉi plian indekson kune kun :term:`PyPI `" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "Instali el loka fonta arbo" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" +"Instali el loka fontarbo en :doc:`evoluada reĝimo `, tiel ke la projekto estas instalita sed tamen modifebla " +"ĉe la fontarbo." + +#: ../source/tutorials/installing-packages.rst:558 +msgid "You can also install normally from src" +msgstr "Vi ankaŭ povas instali ordinare el fonto" + +#: ../source/tutorials/installing-packages.rst:573 +msgid "Installing from local archives" +msgstr "Instali el loka arĥivo" + +#: ../source/tutorials/installing-packages.rst:575 +msgid "Install a particular source archive file." +msgstr "Instali specifan fontan arĥivan dosieron." + +#: ../source/tutorials/installing-packages.rst:589 +msgid "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" +"Instali el loka dosierujo enhavanta arĥivojn (kaj ne kontroli :term:`PyPI " +"`)" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "Instali el aliaj fontoj" + +#: ../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 "" +"Por instali el alia datenfonto (ekzemple el konservejo Amazon S3), oni povas " +"krei helpan programon, kiu prezentas la datenojn kongrue kun la :ref:`simpla " +"deponeja API `:, kaj uzi la flagon ``--extra-index-" +"url`` igante pip uzi tiun indekson." + +#: ../source/tutorials/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "Instali Antaŭeldonojn" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" +"Trovi antaŭeldonajn kaj evoluadajn versiojn, aldone al stabilaj versioj. " +"Apriore, pip nur trovas stabilajn versiojn." + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "Instali «Ekstraĵojn»" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" +"Ekstraĵo estas laŭvola «varianto» de pako, kiuj povas inkluzivi pliajn " +"dependecojn kaj tiel ebligi pliajn funkciojn de la pako. Se oni deziras " +"instali ekstraĵon por pako, kiu havas ekstraĵon, oni povas inkluzivi ĝin en " +"la instalokomandon de pip:" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" +"En ĉi tiu kunteksto, «sekura» signifas uzi modernan TTT-legilon aŭ ilon " +"kiel :command:`curl` kiu konfirmas SSL-atestilojn dum elŝutado el ``https``-" +"retadresoj." + +#: ../source/tutorials/installing-packages.rst:675 +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`." +msgstr "" +"Ekde Python 3.4, ``venv`` (alternativo al :ref:`virtualenv` en la norma " +"biblioteko) kreas virtualan medion kun antaŭinstalita ``pip``, simile " +"al :ref:`virtualenv`." + +#: ../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" +msgstr "" +"La specifilo pri kongrua eldono estis akceptita en :pep:`440`, " +"kaj :ref:`setuptools` v8.0 kaj :ref:`pip` v6.0 eksubtenis ĝin" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "Administri Programajn Dependecojn" + +#: ../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." +msgstr "" +"La :ref:`lernilo pri instalado de pako ` diskutis la " +"fundamentojn pri instalado kaj ĝisdatigado de Python-pakoj." + +#: ../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." +msgstr "" +"Tamen, interage ruli tiajn komandojn estas tede, eĉ por onia propra " +"projekto, kaj eĉ pli malfacile estas starigi disvolvajn mediojn aŭtomate por " +"projektoj kun multaj kontribuantoj." + +#: ../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 "" +"Ĉi tiu lernilo priskribas kiel uzi :ref:`Pipenv` por administri dependecojn " +"de programo. Ĝi klarigas kiel instali kaj uzi la necesajn ilojn, kaj " +"rekomendegas bonajn elektojn." + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" +"Python estas uzata por multaj diversaj celoj, kaj ĝuste kiel oni administras " +"dependecojn dependas de la maniero de eldonado de la programo. La konsilo ĉi " +"tie plej taŭgas por programado kaj disponigado de retservoj (inkluzive de " +"TTT-programoj), sed ankaŭ estas bona por mastrumi programadajn kaj testajn " +"mediojn de ĉia projekto." + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" +"Por alternativoj, vidu la paragrafon `Aliaj Iloj por Administri Programan " +"Dependecon `_." + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "Instali Pipenv" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" +":ref:`Pipenv` estas dependeco-administrilo por Python-projekto. Se vi konas " +"`npm`_ de Node.js aŭ `bundler`_ de Ruby, ĝi estas simila en spirito al tiuj " +"iloj. Dum :ref:`pip` sola ofte sufiĉas por persona uzado, Pipenv estas " +"rekomendata por kunlabora projekto, ĉar ĝi estas altnivela ilo simpliganta " +"administradon de dependecoj por oftaj uzkazoj." + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "Uzi ``pip`` por instali Pipenv:" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "Instali pakojn por via projekto" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +msgstr "" +"Pipenv administras dependecojn por projekto. Por instali pakon, iru al la " +"dosierujo de via projekto (aŭ malplena dosierujo por ĉi tiu lernilo), kaj " +"rulu la jenon:" + +#: ../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):" +msgstr "" +"Pipenv instalos la bibliotekon `Requests`_ kaj kreos la dosieron ``Pipfile`` " +"por vi en la projekta dosierujo. :ref:`Pipfile` registras la dependecojn " +"postulatajn de via projekto, kiam oni volas reinstali ilin, ekzemple kiam vi " +"sendas vian projekton al aliuloj. Vi ricevos eligaĵon similan al la jeno " +"(kvankam la precizaj dosierlokoj diferencos):" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "Uzi instalitajn pakojn" + +#: ../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 "" +"Post instalo de Requests, vi povas krei simplan dosieron :file:`main.py` por " +"uzi ĝin:" + +#: ../source/tutorials/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "Poste vi povas ruli la programon per ``pipenv run``:" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "Vi ricevos eligaĵon simila al la jeno:" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" +"Uzo de ``pipenv run`` certigas, ke via programo povas atingi viajn " +"instalitajn pakojn. Ankaŭ vi povas lanĉi novan ŝelon per ``pipenv " +"shell``certigante, ke viaj komandoj povas atingi viajn instalitajn pakojn." + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "Sekvaj paŝoj" + +#: ../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 "" +"Gratulon, vi nun scias kiel efektive administri dependecojn kaj evoluajn " +"mediojn en kulabora Python-projekto! ✨ 🍰 ✨" + +#: ../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 "" +"Se vi interesiĝas krei kaj distribui vian propran Python-pakon, vidu " +"la :ref:`lernilon pri kreado kaj distribuado de pakoj `." + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" +"Nodu, ke se via programo inkluzivas difinojn de Python-fontpakojn, oni povas " +"aldoni ilin (kaj iliajn dependaĵojn) al la medio ``pipenv`` per ``pipenv " +"install -e `` (ekz. ``pipinstall " +"-e .`` aŭ ``pipenv install -e src``)." + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "Aliaj Iloj por Administri Programan Dependecon" + +#: ../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/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 `_ por opiniriĉa subtenado de eĉ pli " +"da paŝoj en la projekta mastruma laborluo, kiel alkrementado de versio kaj " +"kreado de nova projekto el projekto-ŝablono." + +#: ../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 "" +"`micropipenv `_ por leĝera " +"volvilo ĉirkaŭ pip subtenanta ``requirements.txt``, Pipenv- kaj Poetry-" +"serurdosieroj, kaj konvertado al formo kongrua kun pip-tools. Fasonita por, " +"sed ne nur por, enujigita Python-programo." + +#: ../source/tutorials/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" +"`PDM `_ por moderna Python-" +"pakadministrado per normoj kiel :pep:`517` kaj :pep:`621`." + +#: ../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 "" +"`pip-tools `_ por krei serurdosieron " +"de ĉiuj dependaĵoj el listo de pakoj rekte uzataj en projekto, certigante, " +"ke nur tiuj dependaĵoj estas instalitaj." + +#: ../source/tutorials/managing-dependencies.rst:175 +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." +msgstr "" +"`Poetry `__ por ilo de simila utilo " +"al Pipenv, kiu pli temas pri tiuj uzkazoj, kie la administrata projekto " +"estas strukturita kiel distribuebla Python-pako kun valida dosiero " +"``pyproject.toml``. Malkiele, Pipenv eksplicite ne supozas, ke la " +"administrata programo estas distribuebla kiel ``pip``-instalebla Python-pako." + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "Paki projektojn de Python" + +#: ../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 "" +"Jen lernilo pri kiel paki simplan Python-projekton. Ĝi klarigas kiel aldoni " +"la necesajn dosierojn kaj strukturon por krei la pakon, kiel konstrui la " +"pakon, kaj kiel alŝuti ĝin al la Python-Pakindekso ( 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 "" +"Se vi spertas problemon pri la komandoj en ĉi tiu lernilo, bonvolu kopii la " +"komandon kaj ĝian eligaĵon, kaj `raportu problemon `_ pri la " +"deponejo `packaging-problems`_ ĉe GitHub. Ni provos helpi vin!" + +#: ../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:" +msgstr "" +"Kelkaj komandoj postulas novan version de :ref:`pip`. Tial, certigu, ke vi " +"havas la plej novan version:" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "Simpla projekto" + +#: ../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 "" +"Ĉi tiu lernilo uzas simplan projekton nomitan " +"``example_package_VIA_SALUTNOMO``. Se via salutnomo estus ``mi``, la pako " +"estus ``example_package_mi``. Tio certigas, ke oni havas unikan paknomon ne " +"konfliktantan kun pakoj alŝutitaj de aliuloj legintaj ĉi tiun lernilon. Ni " +"rekomendas, ke vi sekvu ĉi tiun lernilon laŭvorte per ĉi tiu projekto antaŭ " +"ol paki vian propran projekton." + +#: ../source/tutorials/packaging-projects.rst:44 +msgid "Create the following file structure locally:" +msgstr "Kreu loke la jenan dosieran strukturon:" + +#: ../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 "" +"La nomo de la dosierujo enhavanta la Python-dosierojn estu la nomo de la " +"projekto. Tio simpligas la agordadon kaj estas pli klara al instalantoj de " +"la pako." + +#: ../source/tutorials/packaging-projects.rst:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" +"Krei la dosieron :file:`__init__.py` estas rekomendate, ĉar la ekzisto de " +"dosiero :file:`__init__.py` permesas al uzantoj importi la dosierujon kiel " +"ordinaran pakon, eĉ se (kiel estas la kazo en ĉi tiu " +"lernilo) :file:`__init__.py` estas malplena. [#namespace-packages]_" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" +":file:`example.py` estas ekzemplo de modulo en la pako, kiu povas enhavi la " +"logikon (funkciojn, klasojn, konstantojn ktp.) de via pako. Malfermu tiun " +"dosieron, kaj tajpu la jenon:" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" +"Se vi ne konas :term:`modulon ` kaj :term:`importan pakon ` de Python, bonvolu tralegi la `dokumentaron de Python pri pakoj " +"kaj moduloj `_." + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"Once you create this structure, you'll want to run all of the commands in " +"this tutorial within the ``packaging_tutorial`` directory." +msgstr "" +"Post kiam vi kreas tiun strukturon, vi rulu ĉiujn komandojn en ĉi tiu " +"lernilo ene de la dosierujo ``packaging_tutorial``." + +#: ../source/tutorials/packaging-projects.rst:83 +msgid "Creating the package files" +msgstr "Krei dosierojn de la pakaĵo" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" +"Vi nun aldonos dosierojn por prepari la projekton por distribuado. Post tio, " +"la projekta strukturo aspektos jene:" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "Krei elprovan dosierujon" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" +":file:`tests/` estas loko por testaj dosieroj. Lasu ĝin malplena portempe." + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "Elekti konstruan malfasadon" + +#: ../source/tutorials/packaging-projects.rst:113 +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 "" +"Ilo kiel :ref:`pip` aŭ :ref:`build` ne fakte transformas viajn fontojn " +"en :term:`distribuan pakon ` (kiel radon); tiu tasko " +"estas farita de :term:`konstrua malfasado `. La konstrua " +"malfasado determinas kiel specifi la projektajn agordojn, inkluzive de la " +"metadatenoj (informoj pri la projekto, ekzemple, la nomo kaj etikedoj " +"montrotaj ĉe PyPI) kaj enigaj dosieroj. Diversaj konstruaj malfasadoj havas " +"diversajn nivelojn de funkcio, pri ĉu ili subtenas konstrui :term:`etendaĵan " +"modulon `, kaj oni elektu konstruan malfasadon taŭgan por " +"viaj bezonoj." + +#: ../source/tutorials/packaging-projects.rst:122 +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 "" +"Vi povas elekti inter multaj malfasadoj. Ĉi tiu lernilo uzas :ref:`Hatchling " +"`, sed ĝi ankaŭ funkcios same kun :ref:`setuptools`, :ref:`Flit " +"`, :ref:`PDM `, aŭ aliaj malfasadoj subtenantaj la tabelon " +"``[project]`` por :ref:`metadatenoj `." + +#: ../source/tutorials/packaging-projects.rst:129 +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 "" +"Kelkaj konstruaj malfasadoj estas parto de pli grandaj iloj, kiuj disponigas " +"komandlinian interfacon kun kromaj funkcioj kiel ekstarigo de projekto kaj " +"administrado de versioj, kune kun konstruado, alŝutado kaj instalado de " +"pakoj. Ĉi tiu lernilo uzas unucelan sendependan ilon." + +#: ../source/tutorials/packaging-projects.rst:134 +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." +msgstr "" +"La dosiero :file:`pyproject.toml` sciigas :term:`la konstruan fasadon ` kiel :ref:`pip` kaj :ref:`build` pri la malfasado uzota por la " +"projekto. Jen kelkaj ekzemploj por oftaj konstruaj malfasadoj, sed legu la " +"dokumentaron de via malfasado por detaloj." + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" +"La ŝlosilo ``requires`` estas listo de pakoj necesaj por konstrui la pakon. " +"La :term:`malfasado ` instalos ilin aŭtomate dum konstruado " +"de la pako. Malfasado ordinare konstruas en izolita medio, tiel ke forlaso " +"de dependaĵo povas kaŭzi eraron dum konstruado. Tio ĉiam inkluzivu la pakon " +"de la malfasado kaj eble aliajn konstrutempajn dependaĵojn. La minimuma " +"versio specifita en la ĉi-supra kodbloko estas tiu, kiu eksubtenis " +"la :ref:`novan licencan metadatenon `." + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"The ``build-backend`` key is the name of the Python object that frontends " +"will use to perform the build." +msgstr "" +"La ŝlosilo ``build-backend`` estas la nomo de la Python-objekto uzota de " +"fasadoj por fari la konstruon." + +#: ../source/tutorials/packaging-projects.rst:153 +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 "" +"Ambaŭ valoroj estos disponigitaj de la dokumentaro de la konstrua malfasado " +"aŭ genereblaj per ĝia komandlinia fasado. Ne necesu, ke oni adaptu tiajn " +"agordojn." + +#: ../source/tutorials/packaging-projects.rst:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "Agordi metadatenojn" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" +"Malfermu :file:`pyproject.toml`, kaj tajpu la jenon. Ŝanĝu ``name`` " +"inkluzivante vian salutnomon; tio certigas, ke via paka nomo estas unika, ne " +"kolizianta kun la pakojn alŝutitajn de aliuloj sekvantaj ĉi tiun lernilon." + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" +"``name`` estas la *distribua nomo* de via pako. Ĝi povas esti ajna nomo " +"enhavanta nur literojn, ciferojn, ``.``, ``_`` , kaj ``-``. Ĝi ankaŭ devas " +"ne esti jam uzata ĉe PyPI. **Certigu, ke vi ĝisdatigu ĝin per via " +"salutnomo** por ĉi tiu lernilo; tio certigas, ke vi ne alŝutos pakon de la " +"sama nomo kiel pako jam ekzistanta." + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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`` estas la versio de la pako. (Kelkaj konstruaj malfasadoj " +"permesas aliajn manierojn specifi ĝin, kiel per dosiero aŭ Git-etikedo.)" + +#: ../source/tutorials/packaging-projects.rst:203 +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." +msgstr "" +"``authors`` identigas la aŭtoron de la pakon; vi specifu nomon kaj retpoŝtan " +"adreson por ĉiu aŭtoro. La kampo ``maintainers`` por mastrumantoj sekvas la " +"saman formon." + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "``description`` estas mallonga, unufraza resumo de la pako." + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" +"``requires-python`` listigas la versiojn de Python subtenataj de via " +"projekto. Instalilo kiel :ref:`pip` serĉas tra malnovaj versioj de pakoj ĝis " +"kiam ĝi trovas pakan version kongruan al la versio de Python." + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +#, fuzzy +#| msgid "" +#| "``license`` is the :term:`SPDX license expression ` " +#| "of your package." +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" +"``license`` estas la :term:`SPDX-esprimo ` de via pako." + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" +"``license-files`` estas la listo de dosierloko-patroneoj al la licenco-" +"dosieroj, relativa al la dosierujo en kiu ĉeestas :file:`pyproject.toml`." + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" +"``urls`` ebligas vin listigi ajnan nombron da ekstraj hiperligoj montrotaj " +"sur PyPI. Ĝenerale tiuj povas esti la fonto, dokumentaro, cimaro ktp." + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" +"Vidu la :ref:`gvidilon pri pyproject.toml ` por " +"detaloj pri tiuj kaj aliaj kampoj difineblaj en la tabelo ``[project]``. Jen " +"aliaj oftaj kampoj: ``keywords`` por malkovrebleco, ``dependencies`` pri " +"dependecoj postulataj por instali la pakon." + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "Krei la dosieron README.md" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" +"Malfermu :file:`README.md`, kaj tajpu la jenon. Vi povas adapti ĝin, se tio " +"plaĉas al vi." + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "Krei la dosieron LICENSE" + +#: ../source/tutorials/packaging-projects.rst:253 +#, fuzzy +#| 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:" +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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 "" +"Gravas, ke ĉiu pako alŝutita al la Python-Pakindekso inkluzivu licencon. Tio " +"sciigas al uzanto instalinta pakon la kondiĉojn, sub kiuj oni povas uzi la " +"pakon. Por helpo elekti licencon, vizitu https://choosealicense.com/. Post " +"elekto de licenco, malfermu :file:`LICENSE`, kaj tajpu la licencan tekston. " +"Ekzemple, se vi elektus la MIT-licencon:" + +#: ../source/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" +"La plejmulto de konstruaj malfasadoj aŭtomate inkluzivas licencajn dosierojn " +"en pakojn. Legu la dokumentaron de via malfasado por detaloj. Se vi metas la " +"dosierlokon de la licenco en la ŝlosilon ``license-files`` " +"de :file:`pyproject.toml` kaj via konstrua malfasado subtenas :pep:`639`, la " +"dosiero aŭtomate inkluziviĝos en la pakon." + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "Inkluzivi aliajn dosierojn" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" +"La ĉi-supraj dosieroj inkluziviĝos aŭtomate en vian :term:`fontan distribuon " +"`. Se vi volas inkluzivi aliajn " +"dosierojn, legu la dokumentaron por via konstruilo." + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "Generi distribuan arĥivon" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" +"La sekva paŝo estas generi :term:`distribuajn pakojn ` " +"por la pakoj. Tiuj estas arĥivoj alŝutotaj al Python Package Index kaj " +"instaleblaj per :ref:`pip`." + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "Certigu, ke vi instalis la plej novan version de :ref:`build` de PyPA:" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" +"Se malfacilas instali tiujn, vidu la lernilon :doc:`installing-packages`." + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" +"Nun rulu la jenan komandon ĉe la sama dosierujo kie " +"troviĝas :file:`pyproject.toml`:" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" +"Tiu komando eligos multon da teksto, kaj post fino estos kreinta du " +"dosierojn en la dosierujo :file:`dist`:" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" +"La dosiero ``tar.gz`` estas :term:`fonta distribuo `, dum la dosiero ``.whl`` estas :term:`konstruita distribuo " +"`. Novaj versioj de :ref:`pip` preferas instali " +"konstruitan distribuon sed instalas fontan distribuon, se tio necesas. Oni " +"ĉiam alŝutu fontan distribuon kaj ankaŭ la konstruitajn distribuojn por " +"kongruaj platformoj. Niakaze, la ekzempla pako kongruas kun Python sur ajna " +"platformo; tial ni nur bezonas unu konstruitan distribuon." + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "Alŝuti la distribuajn arĥivojn" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "Finfine, vi pretas alŝuti vian pakon al Python Package Index!" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" +"Unue, vi registru vin ĉe Prova PyPI, kiu estas aparta servilo de la " +"pakindekso por testado kaj eksperimentado. Ĝi estas bonega por lerniloj, kie " +"oni ne volas alŝuti al la reala indekso. Por registri vin, vizitu https://" +"test.pypi.org/account/register/ kaj plenumu la paŝojn sur tiu paĝo. Vi ankaŭ " +"devas konfirmi vian retpoŝtan adreson antaŭ ol alŝutade pako. Por pli da " +"detaloj, vidu :doc:`/guides/using-testpypi`." + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" +"Por sekure alŝuti vian projekton, vi bezonas `API-ĵetonon ĉe PyPI `_. Kreu ĝin ĉe https://test.pypi.org/manage/account/#api-tokens, kun " +"la «Amplekso» estanta «Tuta konto». **Ne fermu la paĝon antaŭ ol vi kopiis " +"kaj konservis la ĵetonon — vi ne povos revidi tiun ĵetonon.**" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" +"Post registrado, vi povas uzi :ref:`twine` por alŝuti la distribuajn pakojn. " +"Vi devas instali Twine:" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "Post instalo, rulu Twine por alŝuti ĉiujn arĥivojn en :file:`dist`:" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" +"Vi estos petata pri API-ĵetono. Tajpu la ĵetonan valoron inkluzive de la " +"prefikso ``pypi-``. Notu, ke la enigaĵo estos kaŝita; tial certigu, ke vi " +"algluos ĝuste." + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "Post la fino de la komando, vi vidos eligaĵon similan al la jeno:" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" +"Post alŝuto, via pako estos videbla ĉe TestPyPI; ekzemple: ``https://" +"test.pypi.org/project/example_package_VIA_SALUTNOMO_ĈI_TIE``." + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "Instali vian nove alŝutitan pakon" + +#: ../source/tutorials/packaging-projects.rst:424 +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 "" +"Vi povas uzi :ref:`pip` por instali vian pakon kaj konfirmi, ĉu ĝi funkcias. " +"Kreu :ref:`virtualan medion `, kaj " +"instalu vian pakon el TestPyPI:" + +#: ../source/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "Certigu, ke vi indikas vian salutnomon en la nomo de la pako!" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "pip instalos la pakon el TestPyPI, kaj la eligaĵo aspektu jene:" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" +"Tiu ekzemplo uzas la flagon ``--index-url`` por specifi la Provan PyPI " +"anstataŭ la vera PyPI. Krome ĝi uzas la flagon ``--no-deps``. Ĉar Prova PyPI " +"ne havas la samajn pakojn kiel PyPI, eblas, ke provado instali dependaĵojn " +"povas malsukcesi aŭ estigi ion neatenditan. Kvankam nia ekzempla pako ne " +"havas dependecon, estas bone averti instaladon de dependaĵojn por Prova PyPI." + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" +"Importante la pakon, vi povas kontroli, ĉu ĝi estis instalita ĝuste. " +"Certigu, ke vi ankoraŭ estas en via virtuala medio, kaj rulu la jenan Python-" +"kodon:" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "kaj importu la pakon:" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "**Gratulon, vi pakis kaj distribuis Python-projekton!** ✨ 🍰 ✨" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" +"Notu, ke ĉi tiu lernilo klarigis al vi kiel alŝuti vian pakon al Prova PyPI, " +"kiu ne estas permanenta konservejo. La Prova sistemo fojfoje forviŝas pakojn " +"kaj kontojn. Oni uzu Provan PyPI nur por testado kaj eksperimentado kiel en " +"ĉi tiu lernilo." + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" +"Kiam vi pretas alŝuti veran pakon al la Python-Pakindekso, vi povas fari pli-" +"malpli same kiel ĉi tiu lernilo, krom la jenaj gravaj diferencoj:" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" +"Elektu memorindan kaj unikan nomon por via pako. Vi ne devas postmeti vian " +"salutnomon kiel en la lernilo, sed vi ne povas uzi ekzistantan nomon." + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" +"Registru konton ĉe https://pypi.org – notu, ke tiuj du estas apartaj " +"serviloj; la akreditiloj ne estas komunaj inter ili." + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" +"Uzu ``twine upload dist/*`` por alŝuti vian pakon. Tajpu la akreditilon por " +"la konto ĉe la vera PyPI. Ĉar vi estas alŝutanta al la reala pakindekso, vi " +"ne devas uzi la flagon ``--repository``; la pako estos implicite alŝutita al " +"https://pypi.org/." + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" +"Instalu vian pakon el la vera PyPI per ``python3 -m pip install [your-" +"package]``." + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" +"Nun, se vi volas legi pli pri pakado de Python-bibliotekoj, jen kelkaj " +"legindaĵoj:" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" +"Legu pri altnivela agordado de via konstrua malfasado: `Hatchling `_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" +"Legu la :doc:`gvidilojn ` ĉe ĉi tiu retejo por pli komplikaj " +"praktikaj informoj aŭ la :doc:`diskutojn ` por klarigoj " +"kaj fonaj informoj pri specifaj temoj." + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" +"Konsideru pakadan ilon disponigantan unu komandlinian fasadon por " +"projektadministrado kaj pakado, kiel " +"ekzemple :ref:`hatch`, :ref:`flit`, :ref:`pdm` kaj :ref:`poetry`." + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "Notoj" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" +"Teĥnike, vi ankaŭ povas krei Python-pakon sen dosiero ``__init__.py``, sed " +"tia pako nomiĝas :doc:`nomspaca pako ` " +"kaj estas **altnivelaĵo** (ne pridiskutata en ĉi tiu lernilo). Se vi estas " +"komencanto pri Python-pakado, recomendate estas nur uzi *ordinarajn pakojn* " +"kaj ``__init__.py`` (eĉ se tiu dosiero estas malplena)." + +#~ msgid "" +#~ "This specification was originally defined in :pep:`518` and :pep:`621`." +#~ msgstr "" +#~ "Ĉi tiu specifo estis originale difinta en :pep:`518` kaj :pep:`621`." + +#~ msgid "" +#~ "Refer to the `pkg_resources documentation `__ for more details." +#~ msgstr "" +#~ "Por pliaj detaloj, vidu `la dokumentaron de pkg_resources `__." + +#~ msgid "" +#~ "A complete working example of two pkg_resources-style namespace packages " +#~ "can be found in the `pkg_resources namespace example project`_." +#~ msgstr "" +#~ "Plena funkcianta ekzemplo de du pkg_resources-stilaj nomspacaj pakoj " +#~ "troviĝas en la `pkg_resources-nomspaca ekzempla projekto `_." + +#, fuzzy +#~| msgid "The ``versions`` key was added with API version 1.1." +#~ msgid "The ``project-status-reason`` key was added with API version 1.4." +#~ msgstr "La ŝlosilo ``versions`` estis aldonita por versio 1.1 de la API." + +#~ msgid "" +#~ "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." +#~ msgstr "" +#~ "RECORD.jws estas uzataj por ciferecaj subskriboj. Ĝi ne estas menciita " +#~ "en RECORD." + +#~ 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 "" +#~ "RECORD.p7s estas permesata por tiuj, kiuj preferas uzi S/MIME-subskribon " +#~ "por sekurigi wheel-dosieron. Ĝi ne menciiĝas en RECORD." + +#~ msgid "Signed wheel files" +#~ msgstr "Subskribitaj wheel-dosieroj" + +#~ 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::" +#~ msgstr "" +#~ "Wheel-dosiero inkluzivas etenditan ``RECORD`` por ciferecaj subskriboj. " +#~ "La ``RECORD`` de PEP 376 estas modifita por inkluzivi sekuran haketaĵon " +#~ "``digestname=urlsafe_b64encode_nopad(digest)`` (URL-sekura base64-kodado " +#~ "sen finaj signoj ``=``) kiel la duan kolumnon anstataŭ md5sum. Ĉiaj " +#~ "eblaj eroj havu haketaĵojn, inkluzive de generitaj dosieroj kiel ``.pyc``-" +#~ "dosieroj, krom ``RECORD`` mem, kiu ne povas enhavi sian propran " +#~ "haketaĵon. Ekzemple::" + +#~ 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." +#~ msgstr "" +#~ "La subskribo-dosiero(j) RECORD.jws kaj RECORD.p7s ne menciiĝas en RECORD, " +#~ "ĉar ili estas nur aldoneblaj post la generado de RECORD. Ĉiu alia dosiero " +#~ "en la arĥivo devas havi ĝustan haketaĵon en RECORD; se ne, la instalado " +#~ "malsukcesos." + +#~ 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:" +#~ msgstr "" +#~ "Se oni uzas JSON-retsubskriboj (JWS), unu aŭ pluraj subskriboj uzantaj " +#~ "JSON-seriigon de JSON-retsubskribo (JWS-JS) konserviĝas en dosiero " +#~ "``RECORD.jws`` apud ``RECORD``. Oni uzas JWS por subskribi ``RECORD`` " +#~ "inkluzivante la haketaĵon SHA-256 de ``RECORD`` kiel la JSON-ŝarĝon de la " +#~ "subskribo:" + +#~ msgid "(The hash value is the same format used in RECORD.)" +#~ msgstr "(La haketaĵa valoro estas la sama formo uzata en RECORD.)" + +#~ msgid "" +#~ "If RECORD.p7s is used, it must contain a detached S/MIME format signature " +#~ "of RECORD." +#~ msgstr "" +#~ "Se RECORD.p7s estas uzata, ĝi devas enhavi malligitan S/MIME-forman " +#~ "subskribon de RECORD." + +#~ 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." +#~ msgstr "" +#~ "Instalilo de wheel ne devas kompreni ciferecan subskribon sed DEVAS " +#~ "kompari la haketaĵojn en ``RECORD`` al la enhavoj de la maldensigitaj " +#~ "dosieroj. Kiam instalilo komparas la dosierajn haketaĵojn kaj ``RECORD``, " +#~ "aparta subskribo-kontrolilo devas nur kontroli, ĉu ``RECORD`` kongruas " +#~ "kun la subskribo." + +#~ msgid "See" +#~ msgstr "Vidu" + +#~ msgid "https://datatracker.ietf.org/doc/html/rfc7515" +#~ msgstr "https://datatracker.ietf.org/doc/html/rfc7515" + +#~ msgid "" +#~ "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" +#~ "serialization-01" +#~ msgstr "" +#~ "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" +#~ "serialization-01" + +#~ msgid "https://datatracker.ietf.org/doc/html/rfc7517" +#~ msgstr "https://datatracker.ietf.org/doc/html/rfc7517" + +#~ msgid "" +#~ "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" +#~ msgstr "" +#~ "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" + +#~ msgid "Why does wheel include attached signatures?" +#~ msgstr "Kial wheel inkluzivas alkroĉitajn subskribojn?" + +#~ 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." +#~ msgstr "" +#~ "Alkroĉita subskribo estas pli oportuna ol nealkroĉita subskribo, ĉar ĝi " +#~ "moviĝas kune kun la arĥivo. Ĉar nur la individuaj dosieroj estas " +#~ "subskribitaj, la arĥivo estas redensigebla sen eksvalidigi la subskribon, " +#~ "kaj individuaj dosieroj estas kontroleblaj sen reelŝutado de la tuta " +#~ "arĥivo." + +#~ msgid "Why does wheel allow JWS signatures?" +#~ msgstr "Kial wheel permesas JWS-subskribojn?" + +#~ msgid "" +#~ "The JOSE specifications of which JWS is a part are designed to be easy to " +#~ "implement, a feature that is also one of wheel's primary design goals. " +#~ "JWS yields a useful, concise pure-Python implementation." +#~ msgstr "" +#~ "La normoj JOSE, de kiuj JWS estas parto, estas laŭfasone facile " +#~ "realigebla; tio estas ankaŭ unu el la fasonaj ĉefceloj de wheel. JWS " +#~ "ebligas utilan, mallongan pure Python-an realigon." + +#~ msgid "Why does wheel also allow S/MIME signatures?" +#~ msgstr "Kial wheel ankaŭ permesas S/MIME-subskribojn?" + +#~ msgid "" +#~ "S/MIME signatures are allowed for users who need or want to use existing " +#~ "public key infrastructure with wheel." +#~ msgstr "" +#~ "S/MIME-subskribo estas permesata por tiuj uzantoj, kiuj devas aŭ volas " +#~ "uzi ekzistantan publikŝlosilan infrastrukturon kun wheel." + +#~ msgid "" +#~ "Signed packages are only a basic building block in a secure package " +#~ "update system. Wheel only provides the building block." +#~ msgstr "" +#~ "Subskribita pako estas nur baza briko de sekura pako-ĝisdatiga sistemo. " +#~ "Wheel nur provizas la bazan brikon." + +#~ msgid "The license expressions for these projects are:" +#~ msgstr "Jen la licenco-esprimoj por tiuj projektoj:" + +#~ msgid "TUF Support - PEP 458" +#~ msgstr "Subteno de TUF – PEP 458" + +#~ 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." +#~ msgstr "" +#~ ":pep:`458` postulas, ke ĉiu API-respondo estu haketebla kaj unike " +#~ "identigebla per dosierloko relativa al la deponeja radiko. Por deponejo " +#~ "de simpla API, la cela dosierloko estas la Radiko de nia API (ekz. ``/" +#~ "simple/`` ĉe PyPI). Tio estas problema dum uzado de la API per TUF-" +#~ "kliento anstataŭ ordinara HTTP-kliento, ĉar la TUF-kliento ne povas " +#~ "pritrakti la fakton, ke celo povas havi plurajn malsamajn prezentaojn de " +#~ "malsamaj haketaĵoj." + +#~ 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 "" +#~ ":pep:`458` ne specifas la celan dosierlokon por la Simpla API, sed TUF " +#~ "postulas, ke cela dosierloko estu «dosiereca»: alivorte, dosierloko kiel " +#~ "``simple/PROJEKTO/`` ne validas, ĉar ĝi estas dosierujo." + +#~ 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." +#~ msgstr "" +#~ "Dankinde, la cela dosierloko *ne devas* kongrui kun la retadreso de la " +#~ "Simpla API; ĝi povas esti simple ĵetono, kiun la elŝuta kodo povas " +#~ "transformi al la fakta elŝutota retadreso. La samo veras por aliaj " +#~ "aspektoj de la fakta HTTP-peto kiel la ĉapo ``Accept``." + +#~ 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``." +#~ msgstr "" +#~ "Tamen, ŝajnas ke la nuna evoluanta branĉo de pip, kiu provas " +#~ "realigi :pep:`458`, uzas celan dosierlokon kiel `simple/PROJEKTO/" +#~ "index.html``. Oni povus modifi tion inkluzivante la version de la API kaj " +#~ "la seriigon, kiel ``simple/PROJEKTO/vnd.pypi.simple.vN.FORMO``. Do la " +#~ "versio 1 de la HTML-formo estus ``simple/PROJEKTO/" +#~ "vnd.pypi.simple.v1.html``, dum la versio 1 de la JSON-formo estus " +#~ "``simple/PROJEKTO/vnd.pypi.simple.v1.json``." + +#~ 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." +#~ msgstr "" +#~ "Tiukaze, ĉar ``text/html`` estas sinonimo de ``application/" +#~ "vnd.pypi.simple.v1+html`` dum interagado per TUF, estas pli bone normigi " +#~ "al la pli eksplicita nomo." + +#~ msgid "" +#~ "Likewise the ``latest`` metaversion should not be included in the " +#~ "targets, only explicitly declared versions should be supported." +#~ msgstr "" +#~ "Simile la metaversio ``latest`` ne inkluziviĝu en la celoj; nur " +#~ "eksplicite deklarita versio estu subtenata." + +#~ msgid "`not yet `_" +#~ msgstr "`ankoraŭ ne `_" + +#~ msgid "`Vagrant `_" +#~ msgstr "`Vagrant `_" + +#, fuzzy +#~| msgid ":ref:`pyproject-toml-spec`" +#~ msgid "**Inspiration**: :ref:` pyproject-tool-table`" +#~ msgstr ":ref:`pyproject-toml-spec`" + +#~ 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." +#~ msgstr "" +#~ "Sub la radika URL estas alia URL por ĉiu individua projekto en deponejo. " +#~ "La formo de ĉi tiu URL estas ``//``, en kiu la ```` " +#~ "estas anstataŭigita de la normigita nomo de la projekto; ekzemple la URL " +#~ "de projekto nomita «SanktaGralo» estus ``/sanktagralo/``. Ĉi tiu URL " +#~ "devas respondi per valida HTML5-paĝo kun po unu ankra elemento por ĉiu " +#~ "dosiero en la projekto. La href-atributo **DEVAS** esti URL, kiu ligas al " +#~ "la loko de la dosiero por elŝuto, kaj la teksto de la ankra etikedo " +#~ "**DEVAS** esti la sama kiel la fina komponanto (la dosiernomo) de la URL. " +#~ "La URL **INKLUZIVU** haketaĵon en la formo de URL-fragmento de la jena " +#~ "sintakso: ``#=``, en kiu ```` estas " +#~ "la minuskla nomo de la haketfunkcio (kiel ``sha256``) kaj ```` " +#~ "estas la deksesume kodita haketaĵo." + +#~ msgid "Adding \"Yank\" Support to the Simple API" +#~ msgstr "Aldoni Subtenon «Fortiri» al la Simpla API" + +#~ msgid "Signing the distribution packages" +#~ msgstr "Subskribi la distribuajn pakojn" + +#~ msgid "" +#~ "The following job signs the distribution packages with `Sigstore`_, the " +#~ "same artifact signing system `used to sign CPython `_." +#~ msgstr "" +#~ "La jena tasko subskribas la distribuajn pakojn per `Sigstore`_, la sama " +#~ "artefakto-subskriba sistemo `uzata por CPython `_." + +#~ 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 "" +#~ "Unue, ĝi uzas la `GitHub-ago sigstore/gh-action-sigstore-python `_ por subskribi la distribuajn " +#~ "pakojn. Sekve, ĝi kreas malplenan eldonon ĉe GitHub el la aktuala etikedo " +#~ "per la komandlinia ilo ``gh``. Notu, ke tiu paŝo estas modifebla; vidu la " +#~ "`dokumentaron pri gh release `_." + +#~ 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." +#~ msgstr "" +#~ "Vi eble devas administri la permesojn de ``GITHUB_TOKEN`` por ŝalti krei " +#~ "la GitHub-eldonon. Vidu `la dokumentaron de GitHub `_ por instrukcioj. Specife, la ĵetono bezonas la permeson " +#~ "``contents: write``." + +#~ msgid "" +#~ "Finally, the signed distributions are uploaded to the GitHub Release." +#~ msgstr "Fine, la subskribitaj distribuoj alŝutiĝas al GitHub Release." + +#~ 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." +#~ msgstr "" +#~ "Tio anstataŭigas GPG-subskribon, kiun `PyPI ne plu subtenas `_. Tamen, tiu tasko ne " +#~ "estas deviga kaj estas ellasebla por alŝutado al PyPI." + +#~ msgid "" +#~ ":download:`https://packaging.python.org/en/latest/specifications/schemas/" +#~ "build-details-v1.0.schema.json <../schemas/build-details-" +#~ "v1.0.schema.json>`" +#~ msgstr "" +#~ ":download:`https://packaging.python.org/en/latest/specifications/schemas/" +#~ "build-details-v1.0.schema.json <../schemas/build-details-" +#~ "v1.0.schema.json>`" + +#~ msgid "" +#~ ":pep:`639` (accepted in August 2024) has changed the way the ``license`` " +#~ "field is declared. Make sure your preferred build backend " +#~ "supports :pep:`639` before trying to apply the newer guidelines. As of " +#~ "February 2025, :doc:`setuptools ` " +#~ "and :ref:`flit ` don't support :pep:`639` " +#~ "yet." +#~ msgstr "" +#~ ":pep:`639` (akceptita en la Aŭgusto de 2024) ŝanĝis la manieron deklari " +#~ "la kampon ``license``. Certigu, ke via preferata konstrua malfasado " +#~ "komprenas :pep:`639` antaŭ ol provi uzi la novajn gvidliniojn. Je la " +#~ "Februaro de 2025, ankoraŭ nek :doc:`setuptools ` nek :ref:`flit ` " +#~ "subtenas :pep:`639`." + +#~ msgid ":pep:`639` license declaration" +#~ msgstr "Licenco-deklaro laŭ :pep:`639`" + +#~ msgid "Legacy license declaration" +#~ msgstr "Malnovstila licenco-deklaro" + +#~ msgid "" +#~ "This can take two forms. You can put your license in a file, " +#~ "typically :file:`LICENSE` or :file:`LICENSE.txt`, and link that file here:" +#~ msgstr "" +#~ "Vi povas esti unu el du formoj. Vi povas meti vian licencon en dosieron, " +#~ "ofte :file:`LICENSE` aŭ :file:`LICENSE.txt`, kaj ligi la dosieron al ĉi " +#~ "tie:" + +#~ msgid "or you can write the name of the license:" +#~ msgstr "aŭ vi povas skribi la nomon de la licenco:" + +#~ msgid "" +#~ "If you are using a standard, well-known license, it is not necessary to " +#~ "use this field. Instead, you should use 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 "" +#~ "Se oni uzas norman, vaste konatan licencon, oni ne devas uzi ĉi tiun " +#~ "kampon; anstataŭe, oni uzu unu el la :ref:`klasigiloj ` " +#~ "komenciĝantaj per ``License::``. (Ĝenerale, estas bone uzi norman, bone " +#~ "konatan licencon, kaj por eviti konfuziĝon, kaj ĉar kelkaj organizaĵoj " +#~ "evitas programon sen aprobita licenco.)" + +#~ msgid "" +#~ ":pep:`639` (accepted in August 2024) has introduced the ``license-files`` " +#~ "field. Make sure your preferred build backend supports :pep:`639` before " +#~ "declaring the field. As of February 2025, :doc:`setuptools " +#~ "` and :ref:`flit " +#~ "` don't support :pep:`639` yet." +#~ msgstr "" +#~ ":pep:`639` (akceptita je la Aŭgusto de 2024) enkondukis la kampon " +#~ "``license-files``. Certigu, ke via preferata konstrua malfasado " +#~ "subtenas :pep:`639` antaŭ ol deklari la kampon. Je la Februaro de " +#~ "2025, :doc:`setuptools ` " +#~ "kaj :ref:`flit ` ankoraŭ ne " +#~ "subtenas :pep:`639`." + +#~ msgid "" +#~ "Text string that is a valid SPDX `license expression `__ as `defined in PEP " +#~ "639 `__." +#~ msgstr "" +#~ "Signoĉeno, kiu estas valida SPDX-`licenco-esprimo `__ laŭ `PEP 639 " +#~ "`__." + +#~ msgid "The table subkeys of the ``license`` key are deprecated." +#~ msgstr "La tabelaj subŝlosiloj de la ŝlosilo ``license`` estas evitindaj." + +#~ msgid "Rename dist-info-metadata in the Simple API" +#~ msgstr "Ŝanĝi la nomon dist-info-metadata en la Simpla API" + +#~ msgid "Servers" +#~ msgstr "Serviloj" + +#~ 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." +#~ msgstr "" +#~ "La metadatenoj de :ref:`la API-medateno-dosiera specifo `, se uzata en la HTML-prezento de la Simpla " +#~ "API, **DEVAS** enhavi la atributan nomon ``data-core-metadata``, kun la " +#~ "subtenataj valoroj restantaj same." + +#~ 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``." +#~ msgstr "" +#~ "Por subteni klientojn uzantajn la antaŭajn ŝlosilajn nomojn, la HTML-" +#~ "prezento **POVAS** ankaŭ enhavi ``data-dist-info-metadata``. Se ĝi ja " +#~ "enhavas tion, ĝi **DEVAS** kongrui kun la valoro de ``data-core-" +#~ "metadata``." + +#~ 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." +#~ msgstr "" +#~ "Ĉi tiu specifo difinas la aktualan API-version kiel «1.0», kaj supozas, " +#~ "ke estontaj specifoj plu evoluigantaj la simplan API alkrementos la " +#~ "minoran versian numeron." + +#~ msgid "Additional Fields for the Simple API for Package Indexes" +#~ msgstr "Pliaj Kampoj por la Simpla API por Pakindeksoj" + +#~ 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:" +#~ msgstr "" +#~ "Ĉi tiu specifo difinas version 1.1. de la simpla deponeja API. Por la " +#~ "HTML-versio de la API, ne ekzistas ŝanĝoj kompare al versio 1.0. Por la " +#~ "JSON-versio de la API, ekzistas la jenaj ŝanĝoj:" + +#~ msgid "The ``api-version`` must specify version 1.1 or later." +#~ msgstr "La ``api-version`` devas specifi version 1.1 aŭ pli novan." + +#~ msgid "A new ``versions`` key is added at the top level." +#~ msgstr "Nova ŝlosilo ``versions`` estis aldonita supranivele." + +#~ msgid "" +#~ "Two new \"file information\" keys, ``size`` and ``upload-time``, are " +#~ "added to the ``files`` data." +#~ msgstr "" +#~ "Du novaj «dosierinformaj» ŝlosiloj ``size`` kaj ``upload-time`` estas " +#~ "aldonitaj al la datenoj ``files``." + +#~ msgid "" +#~ "The ``versions`` and ``size`` keys are mandatory. The ``upload-time`` key " +#~ "is optional." +#~ msgstr "" +#~ "La ŝlosiloj ``versions`` kaj ``size`` estas devigaj. La ŝlosilo ``upload-" +#~ "time`` ne estas deviga." + +#~ msgid "Additional file information" +#~ msgstr "Pliaj dosieraj informoj" + +#~ msgid "Two new keys are added to the ``files`` key." +#~ msgstr "Du novaj ŝlosiloj estas aldonitaj al la ŝlosilo ``files``." + +#~ msgid "" +#~ "Most build backends automatically include license files in packages. See " +#~ "your backend's documentation for more details." +#~ msgstr "" +#~ "Multaj konstruaj malfasadoj aŭtomate inkluzivas licencajn dosierojn en " +#~ "pakojn. Vidu la dokumentaron de via malfasado por pli da detaloj." + +#~ msgid "The summary description of the project." +#~ msgstr "La resuma priskribo de la projekto." + +#~ msgid "Wheel vs Egg" +#~ msgstr "Wheel kontraste kun Egg" + +#, fuzzy +#~ msgid "``url``" +#~ msgstr "``urls``" + +#, fuzzy +#~ msgid "``project_urls``" +#~ msgstr "``urls``" + +#, fuzzy +#~ msgid "``python_requires``" +#~ msgstr "``requires-python``" + +#, fuzzy +#~ msgid "``console_scripts``" +#~ msgstr "``description``" + +#~ msgid "Comparison to .egg" +#~ msgstr "Komparo al .egg" + +#, fuzzy +#~ msgid ":ref:`declaring-build-dependencies`" +#~ msgstr "``dependencies``/``optional-dependencies``" + +#, fuzzy +#~ msgid "" +#~ "Read :pep:`517` and :pep:`518` for background and details on build tool " +#~ "configuration." +#~ msgstr "Vidu :pep:`517` kaj :pep:`518` por fonaj informoj kaj detaloj." + +#~ msgid "Read about :doc:`/guides/packaging-binary-extensions`." +#~ msgstr "Legu pri :doc:`/guides/packaging-binary-extensions`." + +#, fuzzy +#~ msgid "Current recommendation" +#~ msgstr "Krei la dosieron pyproject.toml" + +#~ msgid "The version of the project as supported by :pep:`440`." +#~ msgstr "La versio de la projekto laŭ :pep:`440`." + +#~ msgid "Learn more" +#~ msgstr "Lerni pli" + +#, fuzzy +#~ msgid "" +#~ ":doc:`Docs ` | `Issues `__ | `Bitbucket `__ | `PyPI `__" +#~ msgstr "" +#~ "`Dokumentaro `__ | `Cimoj `__ | `Bitbucket " +#~ "`__ | `PyPI `__" + +#~ msgid "There are two types of metadata: static and dynamic." +#~ msgstr "Ekzistas du tipoj de metadatenoj: statika kaj dinamika." + +#, fuzzy +#~ msgid "" +#~ "https://self-issued.info/docs/draft-ietf-jose-json-web-signature.html" +#~ msgstr "" +#~ "http://self-issued.info/docs/draft-ietf-jose-json-web-signature.html" + +#, fuzzy +#~ msgid "https://self-issued.info/docs/draft-ietf-jose-json-web-key.html" +#~ msgstr "http://self-issued.info/docs/draft-ietf-jose-json-web-key.html" + +#~ msgid "2014-11-11" +#~ msgstr "2014-11-11" + +#~ msgid "Using `venv`_:" +#~ msgstr "Uzante `venv`_:" diff --git a/locales/es/LC_MESSAGES/messages.po b/locales/es/LC_MESSAGES/messages.po new file mode 100644 index 000000000..c146aa8ea --- /dev/null +++ b/locales/es/LC_MESSAGES/messages.po @@ -0,0 +1,27445 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# Adolfo Jayme Barrientos , 2021, 2022, 2023. +# meowmeowmeowcat , 2021. +# Jaime Marquínez Ferrándiz , 2022. +# Cristián Maureira-Fredes , 2022. +# Diego Ramirez , 2022, 2023, 2024. +# Rafael Jesus Guillen Osorio , 2023. +# Luis Ruiz San Segundo , 2023. +# gallegonovato , 2023, 2024. +# Rafael Fontenelle , 2024. +# "Edgar R. M." , 2024. +# Joseph Hale , 2025. +# Jonathan-den , 2025. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: 2025-12-12 01:00+0000\n" +"Last-Translator: Joseph Hale \n" +"Language-Team: Spanish \n" +"Language: es\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=2; plural=n != 1;\n" +"X-Generator: Weblate 5.15-dev\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "Contribuya a esta guía" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "" +"La |PyPUG| aprecia las contribuciones de cualquier tipo, entre los cuales se " +"incluyen:" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "Leer la guía y brindar observaciones" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "Revisar contribuciones nuevas" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "Revisar el contenido existente" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "Escribir contenido nuevo" + +#: ../source/contribute.rst:14 +#, fuzzy +#| msgid "Translate the guide" +msgid "Translating the guide" +msgstr "Traducir la guía" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" +"La mayor parte del trabajo en |PyPUG| tiene lugar en el `project's GitHub " +"repository`__. Para comenzar, consulte la lista de `open issues`__ y `pull " +"requests`__. Si planea escribir o editar la guía, lea la :ref:`guía de " +"estilo `." + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" +"Al contribuir al |PyPUG|, se espera que siga el `Código de Conducta`__ del " +"PSF." + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "Tipos de documentación" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" +"Este proyecto se compone de cuatro tipos de documentación diferentes, cada " +"uno con finalidades específicas. Este proyecto aspira a seguir el `proceso " +"Diátaxis `_ a fin de crear una documentación de calidad. " +"Al proponer adiciones nuevas al proyecto, seleccione el tipo de " +"documentación apropiado." + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "Tutoriales" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" +"Los tutoriales se centran en enseñar al lector nuevos conceptos mediante la " +"consecución de un objetivo. Son guías paso a paso basadas en opiniones. No " +"incluyen advertencias ni información superflua. `ejemplo de documento estilo " +"tutorial`_." + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "Guías" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" +"Las guías se centran en la realización de una tarea específica y pueden " +"presuponer cierto nivel de conocimientos previos. Son similares a los " +"tutoriales, pero tienen un enfoque limitado y claro y pueden proporcionar " +"muchas advertencias e información adicional según sea necesario. También " +"pueden discutir múltiples enfoques para llevar a cabo la " +"tarea. :doc:`documento de ejemplo de estilo de guía `." + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "Debates" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" +"Los debates se centran en la comprensión y la información. Exploran un tema " +"específico sin un objetivo concreto. :doc:`documento de ejemplo de estilo " +"del debate `." + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "Especificaciones" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" +"Las especificaciones son documentación de referencia centrada en documentar " +"exhaustivamente una interfaz acordada para la interoperabilidad entre las " +"herramientas de empaquetado. :doc:`documento como ejemplo del estilo de la " +"especificación `." + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "Traducciones" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" +"Usamos `Weblate`_ para gestionar las traducciones de este proyecto. Visite " +"el proyecto `packaging.python.org`_ en Weblate para contribuir." + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" +"Si encuentra problemas mientras trabaja en las traducciones, abra una " +"incidencia en `GitHub`_." + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" +"Cualquier traducción de este proyecto debe seguir la sintaxis " +"`reStructuredText`_." + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "Añadir un idioma" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" +"Si su idioma no aparece en `packaging.python.org`_, haga clic en el " +"botón :guilabel:`Start new translation` en la parte inferior de la lista de " +"idiomas y agregue el idioma que desea traducir." + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "Seguir la sintaxis de reStructuredText" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" +"Si no está familiarizado con la sintaxis de reStructuredText (RST), le `esta " +"guía`_ antes de traducir en Weblate." + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "**No traducir directamente el texto de referencia**" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "Al traducir el texto del enlace, no lo traduzca directamente." + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "Incorrecto: traduzca el texto siguiente directamente:" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" +"Correct: Traducir el siguiente text a tu propio idioma y agrega la " +"referencia original:" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "Construyendo la guía localmente" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" +"Aunque no es un requisito para contribuir, puede ser útil construir esta " +"guía localmente para probar tus cambios. Para poder construir esta guía " +"localmente, necesitarás:" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" +":doc:`Nox `. Puedes instalar or actualizar nox usando ``pip``:" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" +"Python 3.11. Nuestras secuencias de comandos usualmente son probabas sólo " +"con Python 3.11. Vea la :doc:`Hitchhiker's Guide to Python installation " +"instructions ` para instalar Python 3.11 " +"en su sistema operativo." + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" +"Para construir esta guía, ejecute el siguiente comando de shell en el " +"directorio raíz del proyecto:" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" +"Después de completar el proceso podrás encontrar el resultado HTML in el " +"directorio ``./build/html``. Puedes abrir el archivo ``index.html`` para ver " +"la guía en el navegador, pero se recomienda servir la guía usando un " +"servidor HTTP." + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" +"Puedes construir la guía y servirla vía un servidor HTTP usando el siguiente " +"comando:" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "Podrá explorar la guía a través de http://localhost:8000." + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "A dónde es desplegada la guía" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" +"La guía es desplegada a través de ReadTheDocs y la configuración vive en " +"https://readthedocs.org/projects/python-packaging-user-guide/. Es servida " +"desde un dominio y frontend personalizado por Fast.ly." + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "Guía de estilo" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" +"Esta guía de estilo contiene recomendaciones sobre cómo deberías escribir el " +"|PyPUG|. Antes de comenzar a escribir, por favor revísela. Al seguir esta " +"guía de estilo, sus contribuciones sumarán a un conjunto cohesivo y a " +"facilitarán que tus contribuciones sean aceptadas en el proyecto." + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "Propósito" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" +"El propósito de la |PyPUG| es ser el recurso oficial en temas de " +"empaquetamiento, publicación, e instalación de proyectos de Python usando " +"herramientas actuales." + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "Alcance" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" +"Esta guía pretende responder preguntas y resolver problemas con " +"recomendaciones precisas y concisas." + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" +"Esta guía no pretende ser exhaustiva y no pretende reemplazar la " +"documentación de cada proyecto. Por ejemple, pip tiene docenas de comandos, " +"opciones, y configuraciones. La documentación de pip describe cada uno éstos " +"detalladamente, mientras que esta guía describe sólo las partes de pip que " +"son necesarias para completar las tareas específicas descritas en esta guía." + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "Audiencia" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "" +"La audiencia de esta guía es cualquier persona que utilice Python con " +"paquetes." + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" +"No olvide que la comunidad de Python es grande y hospitalaria. Sus lectores " +"podrían no compartir su edad, su género, su formación o su cultura, pero " +"tienen el mismo derecho que usted a aprender sobre el empaquetamiento." + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" +"Sobre todo, tenga en mente que no todas las personas que utilizan Python se " +"autodescriben como programadoras. La audiencia de esta guía incluye " +"astrónomos y pintores y estudiantes, no solo desarrolladores profesionales " +"de programas informáticos." + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "Voz y tono" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" +"Aunque posea todas las respuestas, al escribir esta guía procure utilizar un " +"tono de voz humilde y accesible." + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" +"Imagine que está trabajando en un proyecto de Python con alguien que usted " +"considera listo y hábil. Usted disfruta trabajar con esa persona y esa " +"persona disfruta trabajar con usted. Esa persona le ha preguntado algo y " +"usted conoce la respuesta. ¿Cómo le responde? *Así* es como usted debe " +"escribir esta guía." + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" +"He aquí una verificación rápida: intente leer en voz alta para darse una " +"idea de la voz y el tono. ¿Suena como algo que diría o suena como si " +"estuviera actuando o dando un discurso? Siéntase libre de usar contracciones " +"y no se preocupe por seguir reglar gramaticales quisquillosas. Por la " +"presente se le concede permiso para terminar una oración con una " +"preposición, si eso es con lo que desea terminarla." + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" +"Cuando escriba esta guía, ajuste su tono a la seriedad y dificultad del " +"tema. Si está escribiendo un tutorial introductorio, está bien hacer un " +"chiste, pero si está cubriendo una recomendación de seguridad delicada, " +"quizá prefiera evitar por completo los chistes." + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "Convenciones y mecánicas" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "**Escriba dirigiéndose a quien lee**" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" +"Al dar recomendaciones o pasos que seguir, diríjase de *usted* a la " +"audiencia lectora o utilice el modo imperativo." + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "Incorrecto: Para instalarlo, el usuario ejecuta…" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "Correcto: Puede instalarlo ejecutando…" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "Correcto: Para instalarlo, ejecute…" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "**Declarar nuestras suposiciones**" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" +"Evite hacer suposiciones sin antes declararlas. Leer en la web significa que " +"cualquier página de la guía puede ser la primer página de la guía que un " +"usuario ve. Si va a hacer alguna suposición, diga qué suposiciones hará." + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "**Use referencias cruzadas extensivamente**" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" +"La primera vez que mencione una herramienta o práctica, agregue un vínculo a " +"la parte de la guíe que lo cubre, o un vínculo a la documentación externa " +"relevante. Evite al usuario una búsqueda." + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "**Respete las prácticas al nombrar**" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" +"Cuando nombre herramientas, sitios, personas, y otros nombres propios, haga " +"uso de mayúsculas y minúsculas de la manera que éstos prefieren." + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "Incorrecto: Pip utiliza…" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "Correcto: pip utiliza…" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "Incorrecto: … se aloja en github." + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "Correcto: … se aloja en GitHub." + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "**Utilice un estilo que no marque géneros innecesariamente**" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" +"Frecuentemente, se dirigirá a sus lectores con *usted*, *suyo* y *de usted*. " +"Si no, use los pronombres neutros o evite los pronombres por completo." + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "Mal: Un responsable carga un archivo. Entonces él…" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "Bien: Un responsable carga un archivo. Entonces elle…" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "Bien: Un responsable carga un archivo. Entonces el responsable…" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "**Títulos**" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" +"Escriba los encabezados usando palabras que el lector está buscando. Una " +"buena manera de hacer que el encabezado complete una pregunta implícita. Por " +"ejemplo, un lector puede querer saber *Cómo instalo MyLibrary?* así que un " +"buen encabezado podría ser *Instalar MyLibrary*." + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" +"En los encabezados de secciones, use mayúsculas y minúsculas de manera " +"normal. En otras palabras, escriba los encabezados como escribiría una " +"oración típica." + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "Incorrecto: Cosas Que Debe Saber Acerca de Python" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "Correcto: Cosas que debe saber acerca de Python" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "**Números**" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" +"En el cuerpo del texto, escriba los números del uno al nueve con palabras. " +"Para otros números o números dentro de tablas, use caracteres numerales." + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "Desplegando aplicaciones de Python" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "Estado de página" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "Incompleta" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "Última revisión" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "2021-8-24" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "Visión de conjunto" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "Compatibilidad con múltiples plataformas de hardware" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "Empaquetamiento para sistemas operativos e instaladores" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "Windows" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" +"`Pynsist `__ es una herramienta que " +"conjunta programas de Python junto con un intérprete de Python en un solo " +"instalador basado en NSIS. En la mayoría de los casos, empaquetar sólo " +"requiere que el usuario elija una versión del intérprete de Python y declare " +"las dependencias del programa. La herramienta descarga el intérprete " +"especificado para Windows y lo empaqueta con todas las dependencias en un " +"único instalador ejecutable en Windows." + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" +"El programa instalado puede ser iniciado desde un acceso directo que el " +"instalado agrega al menú de inicio. Utiliza el intérprete de Python " +"instalado dentro de su directorio de aplicación, de manera independiente a " +"cualquier otra instalación de Python en la computadora." + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" +"Una gran ventaja de Pynsist es que los paquetes para Windows se pueden crear " +"en Linux. Existen varios ejemplos para diferentes tipos de programas " +"(consola, interfaz gráfica) en la :any:`documentación `. La " +"herramienta se encuentra publicada bajo la licencia MIT." + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "\"Bundles\" de aplicación" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" +"`py2exe `__ es una extensión de distutils " +"que permite convertir scripts de Python en programas ejecutables para " +"Windows (32-bit y 64-bit). Las versiones de Python incluidas en el ciclo de " +"desarrollo oficial son compatibles (se refiere a `Status of Python " +"branches`__). py2exe puede construir ejecutables de consolas y ventanas " +"ejecutables (GUI). Construir servicios de ventana así como servidores DLL/" +"EXE COM puede funcionar pero no tiene soporte activo. La extensión de " +"distutils es publicada bajo la MIT-license y la Mozilla Public License 2.0." + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" +"`py2app `__ es un comando de setuptools de " +"Python que le permite crear paquetes de aplicaciones de macOS y plugins a " +"partir de scripts de Python. Note que py2app DEBE ser usado en macOS para " +"crear las aplicaciones, no puede crear aplicaciones de Mac desde otras " +"plataformas. py2app es publicado bajo la MIT-license." + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "Unix (incluyendo Linux y macOS)" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "pex" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" +"`pex `__ es una librería para generar " +"archivos .pex (\"Python EXecutable\") que son entornos de Python ejecutables " +"similares a los virtualenvs. pex es una expansión de las ideas expuestas " +"en :pep:`441` y hace el despliegue de aplicaciones de Python tan sencillo " +"como un comando cp. Los archivos pex pueden incluir múltiples distribuciones " +"de Python para plataformas específicas, lo que significa que un solo archivo " +"pex puede funcionar en Linux y macOS. pex está publicado bajo la licencia " +"Apache License 2.0." + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "Administración de la configuración" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "Paquete de Distribución vs. paquete importable" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" +"Un número de conceptos diferentes son comúnmente referidos por la palabra " +"\"paquete\". Esta página clarifica las diferencias entre dos significados " +"distintos pero relacionados del empaquetado de Python, \"paquete de " +"distribución\" y \"paquete importable\"." + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "¿Qué es un paquete de distribución?" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" +"Un Paquete de Distribución es una pieza de software que se puede instalar. " +"Muchas de las veces, este es un sinónimo de \"proyecto\". Cuando usted " +"ejecuta ``pip install pkg`` o escribe ``dependencies=[\"pkg\"]`` en su " +"``pyproject.toml``, ``pkg`` es el nombre de un paquete de distribución. Al " +"buscar o navegar en PyPI_, la fuente para instalar librerías y herramientas " +"de Python más conocido, lo que ve es una lista de paquetes de distribución. " +"Alternativamente, el término \"paquete de distribución\" se puede usar para " +"referirse a un archivo específico que contiene una versión específica de un " +"proyecto." + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" +"Note la diferencia al significado del mundo de Linux, donde un \"paquete de " +"distribución\", el cual también se llama \"paquete distro\" o solo " +"\"paquete\", se refiere a algo proveído por el gestor de paquetes del " +"sistema de la `distribución de Linux `_." + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "¿Qué es un paquete importable?" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" +"Un paquete importable es un módulo de Python. Cuando escribe ``import pkg`` " +"o ``from pkg import func`` en su código Python, ``pkg`` es el nombre de un " +"paquete importable. Además, los paquetes importables pueden contener " +"submódulos. Por ejemplo, el paquete ``numpy`` contiene los módulos " +"``numpy.linalg`` y ``numpy.fft``. Los paquetes importables suelen " +"encontrarse en el sistema de archivos como directorios que contiene módulos " +"en archivos ``.py`` y submódulos en subdirectorios." + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" +"Se puede usar un paquete importable después de instalar un paquete de " +"distribución que lo provee." + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" +"¿Cuál es la relación entre paquetes de distribución y paquetes importables?" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" +"Por lo general, un paquete de distribución provee un solo paquete importable " +"(o módulo que no es un paquete) de nombre idéntico. Por ejemplo, ``pip " +"install numpy`` le permite ``import numpy``." + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" +"Pero, esto es solo una convención. PyPI y otros índices de paquetes *no " +"requieren ninguna relación* entre el nombre de un paquete de distribución y " +"los paquetes importables que provee. (En consecuencia, no debería instalar " +"el paquete ``foo`` tan solo porque aparece ``import foo``; se podría " +"instalar un paquete no deseado, el cual también podría ser malicioso.)" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" +"Un paquete de distribución puede proveer un paquete importable con un nombre " +"alternativo. Por ejemplo, considere la biblioteca popular de procesamiento " +"de imágenes Pillow_. Su nombre de distribución es ``Pillow``, per provee el " +"paquete importable ``PIL``. Esta distinción se basa la historia de Pillow: " +"originó como una bifurcación de la biblioteca PIL, y por eso ha retenido el " +"nombre importable de PIL para que los usuarios existentes de PIL podría " +"cambiar sin lío. En general, este tipo de bifurcación es un motivo común " +"para una diferencia entre el nombre de la distribución y el del paquete." + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" +"En un índice de paquetes especifico (como PyPI), los nombres de paquetes de " +"distribución deben ser únicos. Por lo contrario, los paquetes importables no " +"tienen este requisito. Varios paquetes de distribución pueden proveer " +"paquetes importables con el mismo nombre. Las bifurcaciones motivan esto " +"también." + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" +"Por otro lado, un paquete de distribución puede proveer varios paquetes " +"importables, aunque es menos común. Por ejemplo, el paquete de distribución " +"attrs_ provee tanto el paquete importable ``attrs`` con un API nuevo como el " +"paquete importable ``attr`` con otro API apoyado, pero más antigua." + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" +"¿Cómo se comparan los nombres de paquetes de distribución y los de paquetes " +"importables?" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" +"Los nombres de paquetes importables deberían ser identificadores válidos de " +"Python (las :ref:`reglas específicas ` se encuentran en " +"la documentación de Python) [#non-identifier-mod-name]_. En particular, " +"tales nombres emplean barras bajas ``_`` para separar palabras y son " +"sensibles a las mayúsculas y minúsculas." + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" +"Al otro lado, los nombres de paquetes de distribución pueden contener " +"guiónes ``-`` o barras bajas ``_``. También pueden contener puntos ``.``, " +"los cuales se usan a veces para empaquetear un subpaquete de " +"un :ref:`paquete de espacio de nombres `. Por " +"lo general, las diferencias de mayúscula y entre ``-`` vs.. ``_``no " +"importan, e.g., ``pip install Paquete_Fenomenal`` es idéntico a ``pip " +"install paquete-fenomenal`` (las reglas específicas se encuentran en " +"la :ref:`especificación de la normalización de nombres `)." + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" +"Aunque es técnicamente posible importar paquetes/módulos con nombres que no " +"son identificadores válidos de Python por medio de :doc:`importlib " +"`, es muy poco común y no se aconseja." + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "Facilitar empaquetado posterior" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "Borrador" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "2025-?" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" +"Aunque PyPI y herramientas de empaquetamiento de Python como :ref:`pip` son " +"los medios principales para distribuir paquetes de Python, también forman " +"parte de otros ecosistemas de empaquetamiento. Estos esfuerzos de " +"reempaquetamiento se conocen como empaquetamiento *posterior* (sus propios " +"esfuerzos se llaman empaquetamiento *anterior*), y incluyen proyectos como " +"distribuciones de Linux, Conda, Homebrew y MacPorts. En general, tienen la " +"meta de proveer apoyo adicional a usos no facilitados por solo las " +"herramientas de empaquetamiento de Python, como integración nativa con un " +"sistema operativo especifico, o seguros de compatibilidad con versiones " +"específicas de software no-Python." + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" +"Esta guía busca explicar los métodos típicos del empaquetamiento posterior y " +"los desafíos adicionales enfrentados por empaquetadores posteriores. Busca " +"enseñar unas recomendaciones no difíciles para mantenedores de proyectos " +"anteriores que facilitan el empaquetamiento posterior en gran manera. Estas " +"recomendaciones no son de tipo \"todo o nada\" — cada una por si misma " +"resulta beneficioso. Los mantenedores posteriores también están dispuestos a " +"compartir revisiones para resolver estos desafíos. La integración de estas " +"revisiones posteriores en el proyecto anterior también ayuda mucho a reducir " +"la dificultad de mantener y rebasar revisiones similares, pero quizás " +"incompatibles, en cada distribución posterior." + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" +"El establecer una relación buena entre mantenedores de software y " +"empaquetadores posteriores puede resultar en beneficios mutuos. Los " +"posteriores suelen estar dispuestos a compartir su experiencia, tiempo y " +"hardware al mejoro del paquete. A veces pueden ver más claramente el uso " +"práctico del paquete y ofrecen información sobre sus relaciones con otros " +"paquetes que sería difícil de obtener de otra manera. Los empaquetadores " +"también encuentran errores antes de que lleguen a los sistemas de producción " +"de sus usuarios, proveen informes de errores de alta calidad, y comparten " +"revisiones cuando les resulta posible. Por ejemplo, cuando se lanza una " +"version nueva de Python, se esfuerzan por asegurar que los paquetes que " +"redistribuyen están actualizados para ser compatibles." + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" +"Por favor, note que además de redistribución de binarios, las compilaciones " +"posteriores incluyen compilaciones de código fuente realizada en los " +"sistemas de los usuarios (como las distribuciones con preferencia a código " +"fuente como Gentoo Linux)." + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "Proveer distribuciones completas de código fuente" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "¿Por qué?" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" +"La gran mayoría de empaquetadores posteriors prefieren compilar paquetes del " +"código fuente, en lugar de los binarios proveídos por el anterior. En " +"algunos casos, la distribución requiere el código fuente para incluir un " +"paquete. Esto también aplica a paquetes de Python puro que proveen wheels " +"universales. Las razones por usar distribuciones de código fuente incluyen:" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "La opción de auditar el código fuente de cada paquete." + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "La opción de ejecutar los tests y compilar documentación." + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" +"La opción de aplicar revisiones fácilmente, incluso adaptando revisiones del " +"repositorio del proyecto para versiones más antiguas y compartiendo " +"revisiones al proyecto anterior." + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" +"La opción de compilar en una plataforma no apoyada por las compilaciones " +"anteriores." + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" +"La opción de compilar con versiones específicas de bibliotecas de sistema." + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" +"La normalización del proceso de compilación por todos los paquetes de Python." + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" +"Aunque suele ser posible compilar paquetes desde un repositorio de Git, hay " +"unas motivaciones importantes para proveer en archivo estático:" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" +"Obtener un solo archivo suele ser más eficiente, fiable, y apoyado que hacer " +"un Git clone. También ayuda a usuarios con Internet de baja calidad." + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" +"Los posteriores suelen emplear un hash para verificar la autenticidad de " +"archivos fuentes en compilaciones futuras, el cual requiere que se mantienen " +"idénticos bit por bit. Por ejemplo, los archivos generados de Git no tienen " +"esta garantía porque los datos comprimidos pueden cambiar después de una " +"actualización de gzip." + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" +"Los archivos se pueden reflejar a otros servidores, el cual ahorra ancho de " +"banda anterior y posterior. Las compilaciones también se pueden realizar " +"tras cortafuegos o en entornos sin acceso al internet, que solo tienen " +"acceso a los archivos proveídos por el reflejo local o redistribuido " +"previamente." + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" +"La creación y publicación de archivos fuentes puede asegurar que los datos " +"que normalmente se almacenan en el sistema de control de versiones están " +"incorporados. Por ejemplo, los archivos generados automáticamente de Git no " +"incluyen las etiquetas de revisiones, el cual podría resultar en la " +"comunicación de detalles incorrectas de la versión en compilaciones futuras." + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "¿Cómo?" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" +"**Una distribución de formato archivo fuente que se publica en PyPI debería " +"incluir todos los archivos de repositorio de Git del paquete** que son " +"necesarios para compilar el paquete, ejecutar sus verificaciones, compilar e " +"instalar su documentación, y los demás archivos que pueden ser útiles para " +"usuarios, como autocompletado del shell, archivos para facilitar editores, " +"etc." + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" +"Además, se considera una buena práctica indicar límites inferiores o " +"superiores." + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "Archivos de requisitos" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" + +#: ../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 "" +"Esta página discute los formatos de archivo que son usado para distribuir " +"paquetes de Python y las diferencias entre ellos." + +#: ../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 +msgid "What is a source distribution?" +msgstr "¿Qué es una distribución de origen?" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "" + +#: ../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 "Sí" + +#: ../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 "No" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Installation format" +msgstr "Formato de instalación" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "'Flat' packages with :file:`egg-info` metadata." +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../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 "" + +#: ../source/discussions/setup-py-deprecated.rst:25 +#: ../source/discussions/setup-py-deprecated.rst:39 +#: ../source/guides/modernize-setup-py-project.rst:36 +#, fuzzy +msgid "``python setup.py sdist``" +msgstr "Versión de Python" + +#: ../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 "" + +#: ../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 +#, fuzzy +msgid "Recommendation" +msgstr "Recomendaciones de herramientas" + +#: ../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 "" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +#, fuzzy +msgid "``python setup.py test``" +msgstr "Versión de Python" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "``python -m twine check --strict dist/*``" + +#: ../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/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "``python -m twine upload dist/*``" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +#, fuzzy +msgid "``python setup.py --version``" +msgstr "Versión de Python" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "``python -m setuptools_scm``" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "``build``" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "``easy_install``" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "``install_data``" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "``install_egg_info``" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "``install_headers``" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "``install_lib``" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "``install_scripts``" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "``rotate``" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "``saveopts``" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "``setopt``" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "``upload_docs``" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "¿Qué pasa con los comandos personalizados?" + +#: ../source/discussions/setup-py-deprecated.rst:158 +msgid "" +"Likewise, custom :file:`setup.py` commands are deprecated. The " +"recommendation is to migrate those custom commands to a task runner tool or " +"any other similar tool. Some examples of such tools are: chuy, make, nox or " +"tox, pydoit, pyinvoke, taskipy, and thx." +msgstr "" +"Del mismo modo, los comandos personalizados :file:`setup.py` están " +"obsoletos. La recomendación es migrar esos comandos personalizados a una " +"herramienta de ejecución de tareas o cualquier otra herramienta similar. " +"Algunos ejemplos de estas herramientas son: chuy, make, nox o tox, pydoit, " +"pyinvoke, taskipy, y thx." + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "¿Qué pasa con los pasos de construcción personalizados?" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr "" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +#, fuzzy +msgid "Complete" +msgstr "Incompleta" + +#: ../source/discussions/single-source-version.rst:8 +#, fuzzy +msgid "2024-10-07" +msgstr "2021-8-24" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:56 +#, fuzzy +msgid "`Hatchling `_" +msgstr "`Poetry `_" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +#, fuzzy +msgid "Versioning" +msgstr "Versión" + +#: ../source/discussions/versioning.rst:8 +#, fuzzy +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" +"Esta sección describe los pasos que hay que seguir antes de instalar otros " +"paquetes de Python." + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +#, fuzzy +msgid "Calendar versioning" +msgstr "Versión" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +#, fuzzy +msgid "Other schemes" +msgstr "Otras fuentes" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:60 +msgid "The configuration file" +msgstr "El archivo de configuración" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 ../source/flow.rst:143 +msgid "" +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../source/glossary.rst:3 +msgid "Glossary" +msgstr "" + +#: ../source/glossary.rst:8 +msgid "Binary Distribution" +msgstr "Distribución Binaria" + +#: ../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 :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../source/glossary.rst:44 +msgid "Built Distribution" +msgstr "Distribución Construida" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +#, fuzzy +msgid "Core Metadata" +msgstr "Configuración de los metadatos" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +#, fuzzy +msgid "Distribution Archive" +msgstr "Paquete de Distribución" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "Paquete de Distribución" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "Paquete importable" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +#, fuzzy +msgid "Installed Project" +msgstr "Instalador" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "Módulo" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "Índice de paquetes" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "Índice por proyecto" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "Proyecto" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +#, fuzzy +msgid "Project Root Directory" +msgstr "Nombre de proyecto" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "" + +#: ../source/glossary.rst:257 +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:260 +#, fuzzy +msgid "Pyproject Metadata" +msgstr "Nombre de proyecto" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +#, fuzzy +msgid "Pyproject Metadata Key" +msgstr "Nombre de proyecto" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "Archivo de requisitos" + +#: ../source/glossary.rst:344 +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:348 +#, fuzzy +msgid "Root License Directory" +msgstr "Nombre de proyecto" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "Archivo Fuente" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "Paquete de sistema" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" +"Un paquete provisto en un formato nativo del sistema operativo, por ejemplo, " +"un archivo de RPM o de APT." + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "Entorno virtual" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +#, fuzzy +msgid "Wheel Format" +msgstr "Formato de archivo" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +#, fuzzy +msgid "Wheel Project" +msgstr "Proyecto" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "Análisis de las descargas de los paquetes de PyPI" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "Trasfondo" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" +"Existen varias razones por las cuales PyPI no muestra estadísticas de " +"descargas: [#]_" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "Paquetes no hospedados en PyPI (para comparar)" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "Conjunto de datos público" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "Puesta en marcha" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "Cree un proyecto nuevo." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "Columna" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "Descripción" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "Ejemplos" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "Fecha y hora" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "Nombre de proyecto" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "Versión del paquete" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "Instalador" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "Versión de Python" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "Consultas prácticas" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "Contar las descargas del paquete" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" +"La consulta siguiente devuelve el recuento total de descargas para el " +"proyecto «pytest»." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "26190085" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "Descargas del paquete conforme avanza el tiempo" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "" +"https://files.pythonhosted.org/packages/eb/" +"45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" +"sampleproject-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "" +"https://files.pythonhosted.org/packages/56/0a/" +"178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" +"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +msgid "" +"https://files.pythonhosted.org/packages/" +"63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" +"sampleproject_nomura-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +#, fuzzy +msgid "Creating the package" +msgstr "Creación de los archivos del paquete" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +#, fuzzy +msgid "``pyproject.toml``" +msgstr "Creación de pyproject.toml" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +#, fuzzy +msgid "Installing the package with ``pipx``" +msgstr "Instalación de paquetes" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +msgid "Conclusion" +msgstr "Conclusión" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "Crear cuenta" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +#, fuzzy +msgid "1. Install twine" +msgstr "Formato de instalación" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +#, fuzzy +msgid "4. Publishing the package" +msgstr "Uso de otro índice de paquetes" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +#, fuzzy +msgid "Dropping a Python version" +msgstr "Versión de Python" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:57 +#: ../source/guides/index-mirrors-and-caches.rst:47 +#, fuzzy +msgid "Existing projects" +msgstr "Un proyecto sencillo" + +#: ../source/guides/hosting-your-own-index.rst:63 +#, fuzzy +msgid "Package upload" +msgstr "Índice de paquetes" + +#: ../source/guides/hosting-your-own-index.rst:64 +msgid "PyPI fall-through [2]_" +msgstr "" + +#: ../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 +#, fuzzy +msgid ":ref:`devpi`" +msgstr ":ref:`pip`" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +#, fuzzy +msgid ":ref:`simpleindex`" +msgstr ":ref:`pip`" + +#: ../source/guides/hosting-your-own-index.rst:78 +#, fuzzy +msgid ":ref:`pypiserver`" +msgstr ":ref:`pip`" + +#: ../source/guides/hosting-your-own-index.rst:83 +#, fuzzy +msgid ":ref:`pypiprivate`" +msgstr ":ref:`pip`" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +#, fuzzy +msgid ":ref:`pypicloud`" +msgstr ":ref:`pip`" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +#, fuzzy +msgid ":ref:`pywharf`" +msgstr ":ref:`pip`" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +#, fuzzy +msgid ":ref:`pulppython`" +msgstr ":ref:`pip`" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +#, fuzzy +msgid ":ref:`pip2pi`" +msgstr ":ref:`pip`" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +#, fuzzy +msgid ":ref:`dumb-pypi`" +msgstr ":ref:`pip`" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +#, fuzzy +msgid "`Apache `_" +msgstr "`Poetry `_" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +#, fuzzy +msgid ":ref:`proxpi`" +msgstr ":ref:`pip`" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +#, fuzzy +msgid ":ref:`flaskpypiproxy`" +msgstr ":ref:`pip`" + +#: ../source/guides/index-mirrors-and-caches.rst:105 +#, fuzzy +msgid "unmaintained" +msgstr "Responsable" + +#: ../source/guides/installing-scientific-packages.rst:5 +msgid "Installing scientific packages" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:8 +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." +msgstr "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "Por ejemplo:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:108 +msgid "openSUSE" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:118 +msgid "Debian/Ubuntu and derivatives" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +#, fuzzy +msgid "Install packages in a virtual environment using pip and venv" +msgstr "Instalación de paquetes" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:8 +#, fuzzy +msgid "Create and activate a virtual environment" +msgstr "Facultativamente, cree un entorno virtual" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:9 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:153 +msgid "Prepare pip" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +#, fuzzy +msgid "Use and create a requirements file" +msgstr "Archivos de requisitos" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:32 +#, fuzzy +msgid "Create and Use Virtual Environments" +msgstr "Entorno virtual" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:35 +#, fuzzy +msgid "Create a new virtual environment" +msgstr "Facultativamente, cree un entorno virtual" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:37 +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." +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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +#, fuzzy +msgid "Activate a virtual environment" +msgstr "Facultativamente, cree un entorno virtual" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +#, fuzzy +msgid "Deactivate a virtual environment" +msgstr "Facultativamente, cree un entorno virtual" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +#, fuzzy +msgid "Reactivate a virtual environment" +msgstr "Facultativamente, cree un entorno virtual" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +#, fuzzy +msgid "Install packages using pip" +msgstr "Instalación de paquetes" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +#, fuzzy +msgid "Install a package" +msgstr "Instalación de paquetes" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "Instalar una versión específica del paquete" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +#, fuzzy +msgid "Install extras" +msgstr "Instalando \"Extras\"" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +#, fuzzy +msgid "Install a package from source" +msgstr "Instalación de paquetes para su proyecto" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:347 +#, fuzzy +msgid "Install from version control systems" +msgstr "Instalación a partir de otras fuentes" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:349 +msgid "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +#, fuzzy +msgid "Install from local archives" +msgstr "Instalación a partir de otras fuentes" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +#, fuzzy +msgid "Install from other package indexes" +msgstr "Instalación a partir de otros índices" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +#, fuzzy +msgid "Using a requirements file" +msgstr "Archivos de requisitos" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +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/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +#, fuzzy +msgid "Installing packages using virtualenv" +msgstr "Instalación de paquetes" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +#, fuzzy +#| msgid "Examples" +msgid "Licensing Examples" +msgstr "Ejemplos" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +#, fuzzy +msgid "Basic example" +msgstr "Por ejemplo:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +#, fuzzy +msgid "Advanced example" +msgstr "Por ejemplo:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +#, fuzzy +msgid "Expression examples" +msgstr "Por ejemplo:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "``setuptools`` 27.0.0" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +#, fuzzy +msgid ":ref:`distributing-packages`" +msgstr "Paquete de Distribución" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../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/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +#, fuzzy +msgid ":ref:`pyproject-toml-spec`" +msgstr "Nombre de proyecto" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "Extensiones binarias para Linux" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "Extensiones binarias para macOS" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "Publicación de extensiones binarias" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:374 +msgid "Weak linking" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:379 +msgid "Additional resources" +msgstr "Recursos adicionales" + +#: ../source/guides/packaging-binary-extensions.rst:381 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +#, fuzzy +msgid "Legacy namespace packages" +msgstr "Utilización de paquetes instalados" + +#: ../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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +#, fuzzy +msgid "Installation" +msgstr "Formato de instalación" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "Dependencias externas" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "Secuencias de apoyo" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:233 +msgid "``appveyor-sample/build.cmd``" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:5 +msgid "Tool recommendations" +msgstr "Recomendaciones de herramientas" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:20 +#, fuzzy +msgid "Virtual environments" +msgstr "Entorno virtual" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +#, fuzzy +msgid "Installing packages" +msgstr "Instalación de paquetes" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +#, fuzzy +msgid "Building distributions" +msgstr "Distribución Construida" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +#, fuzzy +msgid ":ref:`Flit`," +msgstr ":ref:`pip`" + +#: ../source/guides/tool-recommendations.rst:180 +#, fuzzy +msgid ":ref:`Hatch`," +msgstr ":ref:`pip`" + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +#, fuzzy +msgid ":ref:`PDM`," +msgstr ":ref:`pip`" + +#: ../source/guides/tool-recommendations.rst:183 +#, fuzzy +msgid ":ref:`Pipenv`," +msgstr ":ref:`pip`" + +#: ../source/guides/tool-recommendations.rst:184 +#, fuzzy +msgid ":ref:`Poetry`," +msgstr ":ref:`pip`" + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +#, fuzzy +msgid "Writing your ``pyproject.toml``" +msgstr "Creación de pyproject.toml" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +#, fuzzy +msgid "Put the version of your project." +msgstr "Añada palabras clave que describan su proyecto." + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +#, fuzzy +msgid "Dependencies and requirements" +msgstr "Archivos de requisitos" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +#, fuzzy +msgid "Creating executable scripts" +msgstr "Creación de los archivos del paquete" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +#, fuzzy +msgid "``license`` and ``license-files``" +msgstr "Dependencias externas" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:313 +#, fuzzy +#| msgid "``setuptools`` 27.0.0" +msgid "setuptools" +msgstr "``setuptools`` 27.0.0" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:317 +msgid "uv-build" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +#, fuzzy +msgid "``license-files``" +msgstr "Dependencias externas" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "Ejemplo completo" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "Manual de uso del empaquetamiento de Python" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" + +#: ../source/index.rst:36 +#, fuzzy +msgid "Overview and Flow" +msgstr "Visión de conjunto" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "empaquetado" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "" + +#: ../source/key_projects.rst:546 +#, fuzzy +msgid "`GitHub `__" +msgstr "`pip-tools `_" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:582 +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 es una herramienta para generar archivos :file:`.pex` (Python " +"EXecutable), entornos Python independientes en el espíritu " +"de :ref:`virtualenv`. Los archivos PEX son :doc:`zipapps ` que hacen que el despliegue de aplicaciones Python sea tan sencillo " +"como ``cp``. Un único archivo PEX puede soportar múltiples plataformas de " +"destino y puede ser creado a partir de requisitos estándar :ref:`pip`-" +"resolubles, un lockfile generado con ``pex3 lock ...`` o incluso otro PEX. " +"Los archivos PEX pueden tener opcionalmente herramientas incrustadas que " +"permiten convertir el archivo PEX en un venv estándar, dibujar dependencias " +"y más." + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +#, fuzzy +msgid "`Kivy `_" +msgstr "`Poetry `_" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "Seguridad" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +#, fuzzy +#| msgid "Project name" +msgid "Subdirectory name" +msgstr "Nombre de proyecto" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#, fuzzy +msgid "``licenses``" +msgstr "Dependencias externas" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +#, fuzzy +msgid "``license_files``" +msgstr "Dependencias externas" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +#, fuzzy +msgid "Example" +msgstr "Ejemplos" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "Especificación" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Project" +msgid "*object*" +msgstr "Proyecto" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Package version" +msgid "Schema version." +msgstr "Versión del paquete" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Examples" +msgid "examples" +msgstr "Ejemplos" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Version" +msgid "**version**" +msgstr "Versión" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +msgid "version\\_info" +msgstr "Versión" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "**Numbers**" +msgid "*number*" +msgstr "**Números**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Additional resources" +msgid "additionalProperties" +msgstr "Recursos adicionales" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +msgid "**implementation**" +msgstr "Tipos de documentación" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "**Headings**" +msgid "**flags**" +msgstr "**Títulos**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +msgid "extensions" +msgstr "Versión" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "**Numbers**" +msgid "**headers**" +msgstr "**Números**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "Nombre" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "Versión" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "Responsable" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +#, fuzzy +msgid "Requires" +msgstr "Archivo de requisitos" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +#, fuzzy +msgid "Package Building" +msgstr "Índice de paquetes" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +#, fuzzy +#| msgid "Installing \"Extras\"" +msgid "Installing Dependency Groups & Extras" +msgstr "Instalando \"Extras\"" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +#, fuzzy +msgid "Validation and Compatibility" +msgstr "Etiquetas de compatibilidad con plataformas" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +#, fuzzy +msgid "Reference Implementation" +msgstr "Tipos de documentación" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +#, fuzzy +msgid "Names" +msgstr "Nombre" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +#, fuzzy +msgid "Versions" +msgstr "Versión" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:248 +#, fuzzy +msgid "Python equivalent" +msgstr "Versión de Python" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:282 +#, fuzzy +msgid "``python_version``" +msgstr "Versión de Python" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +msgid ":ref:`Version `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:286 +#, fuzzy +msgid "``python_full_version``" +msgstr "Versión de Python" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +#, fuzzy +msgid "``toml``" +msgstr "Creación de pyproject.toml" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +#, fuzzy +msgid "``dependency_groups``" +msgstr "Dependencias externas" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +#, fuzzy +msgid "``pip install app``" +msgstr "Sírvase de ``pip`` para instalar Sphinx:" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "Formato de archivo" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +#, fuzzy +msgid "Externally Managed Environments" +msgstr "Entorno virtual" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +#, fuzzy +msgid "package" +msgstr "empaquetado" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "Gestor de paquetes específico de Python" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "Esta especificación tiene dos partes." + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +#, fuzzy +msgid "Guide users towards virtual environments" +msgstr "Facultativamente, cree un entorno virtual" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +#, fuzzy +msgid "Implementation Notes" +msgstr "Tipos de documentación" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "``pip install``" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "``pip install --prefix=/some/path``" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "``pip install --user``" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +#, fuzzy +msgid "Installers" +msgstr "Instalador" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +#, fuzzy +msgid "Reference implementation in Python" +msgstr "Tipos de documentación" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "Especificaciones de PyPA" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +#, fuzzy +msgid "Attestation objects" +msgstr "Un proyecto sencillo" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +#, fuzzy +msgid "Inline script metadata" +msgstr "Configuración de los metadatos" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +#, fuzzy +msgid "Recommendations" +msgstr "Recomendaciones de herramientas" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +#, fuzzy +msgid "Names and normalization" +msgstr "Versión del paquete" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +#, fuzzy +msgid "Name format" +msgstr "Formato de archivo" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +#, fuzzy +msgid "Name normalization" +msgstr "Traducciones" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "Etiquetas de compatibilidad con plataformas" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"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:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +#, fuzzy +msgid "``manylinux``" +msgstr "Responsable" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "Herramienta" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +#, fuzzy +msgid "``musllinux``" +msgstr "Responsable" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +#, fuzzy +#| msgid "``install``" +msgid "``intel``" +msgstr "``install``" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +#, fuzzy +msgid "Project Status Markers" +msgstr "Nombre de proyecto" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +#, fuzzy +msgid "Installer semantics: none." +msgstr "Formato de instalación" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +#, fuzzy +msgid "Installer semantics:" +msgstr "Instalador" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +#, fuzzy +msgid "``deprecated``" +msgstr "Dependencias externas" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +#, fuzzy +#| msgid "Specification" +msgid "``pylock.toml`` Specification" +msgstr "Especificación" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +#, fuzzy +#| msgid "Name" +msgid "File Name" +msgstr "Nombre" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +#, fuzzy +msgid "``lock-version``" +msgstr "Versión de Python" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +#, fuzzy +msgid "**Required?**: yes" +msgstr "Archivo de requisitos" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +#, fuzzy +msgid "``environments``" +msgstr "Entorno virtual" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +#, fuzzy +msgid "``dependency-groups``" +msgstr "Dependencias externas" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +#, fuzzy +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "Nombre de proyecto" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +#, fuzzy +#| msgid "" +#| "``INSTALLER``: records the name of the tool used to install the project." +msgid "Records the name of the tool used to create the lock file." +msgstr "" +"``INSTALLER``: registra el nombre de la herramienta utilizada para instalar " +"el proyecto." + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +#, fuzzy +msgid "``[[packages]]``" +msgstr "empaquetado" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +#, fuzzy +#| msgid "Package version" +msgid "``packages.version``" +msgstr "Versión del paquete" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +#, fuzzy +msgid "The version of the package." +msgstr "Creación de los archivos del paquete" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +#, fuzzy +msgid "``[[packages.dependencies]]``" +msgstr "Dependencias externas" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +#, fuzzy +msgid "The type of version control system used." +msgstr "Instalación a partir de otras fuentes" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +#, fuzzy +#| msgid "Where the guide is deployed" +msgid "The time the file was uploaded." +msgstr "A dónde es desplegada la guía" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +#, fuzzy +#| msgid "Package Index" +msgid "``packages.index``" +msgstr "Índice de paquetes" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +#, fuzzy +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "Nombre de proyecto" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "El archivo :file:`.pypirc`" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +#, fuzzy +#| msgid "The :file:`.pypirc` file" +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "El archivo :file:`.pypirc`" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" +"El formato (definido originalmente por el paquete :ref:`distutils`) es:" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "Configuraciones habituales" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "Uso de una ficha de PyPI" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "Uso de otro índice de paquetes" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:136 +#, fuzzy +msgid "``dependencies``" +msgstr "Dependencias externas" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +msgid "``import-names``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +#, fuzzy +msgid "``maintainers``" +msgstr "Responsable" + +#: ../source/specifications/pyproject-toml.rst:148 +#, fuzzy +msgid "``optional-dependencies``" +msgstr "Dependencias externas" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" +"La descripción resumida del proyecto en una línea. Las herramientas PUEDEN " +"producir un error si esto incluye varias líneas." + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +#, fuzzy +#| msgid "PyPA specifications" +msgid "Legacy specification" +msgstr "Especificaciones de PyPA" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +#, fuzzy +msgid "Examples:" +msgstr "Ejemplos" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +#, fuzzy +msgid "Example:" +msgstr "Ejemplos" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +#, fuzzy +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" +"El directorio ``.dist-info`` puede contener los archivos que se describen a " +"detalle a continuación:" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "``METADATA``: contiene metadatos sobre el proyecto" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "``RECORD``: registra la lista de archivos instalados." + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" +"``INSTALLER``: registra el nombre de la herramienta utilizada para instalar " +"el proyecto." + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +#, fuzzy +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" +"El directorio ``.dist-info`` puede contener los archivos que se describen a " +"detalle a continuación:" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "El archivo METADATA" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "El archivo RECORD" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "delimitador de campos: ``,`` (coma)," + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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 "" +"Está *fuertemente desaconsejado* que un paquete instalado se modifique a sí " +"mismo (por ejemplo, almacenar archivos de caché bajo su espacio de nombres " +"en ``site-packages``). Los cambios dentro de ``site-packages`` deben dejarse " +"a herramientas de instalación especializadas como pip. Si un paquete es " +"modificado de esta manera, entonces el ``RECORD`` debe ser actualizado, de " +"lo contrario la desinstalación del paquete dejará archivos no listados en su " +"lugar (posiblemente resultando en un paquete de espacio de nombres zombie)." + +#: ../source/specifications/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "El archivo INSTALLER" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +msgid "PyPA schemas" +msgstr "" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../source/specifications/section-distribution-formats.rst:3 +msgid "Package Distribution File Formats" +msgstr "Formatos de archivo de distribución de paquetes" + +#: ../source/specifications/section-distribution-metadata.rst:3 +msgid "Package Distribution Metadata" +msgstr "Metadatos de distribución de paquetes" + +#: ../source/specifications/section-installation-metadata.rst:3 +#, fuzzy +msgid "Package Installation Metadata" +msgstr "Metadatos de distribución de paquetes" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "Interfaces del Índice de paquetes" + +#: ../source/specifications/section-python-description-formats.rst:3 +#, fuzzy +#| msgid "Package Distribution File Formats" +msgid "Python Description Formats" +msgstr "Formatos de archivo de distribución de paquetes" + +#: ../source/specifications/section-reproducible-environments.rst:3 +#, fuzzy +#| msgid "Virtual Environment" +msgid "Reproducible Environments" +msgstr "Entorno virtual" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +#, fuzzy +msgid "Normalized Names" +msgstr "Traducciones" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +#, fuzzy +msgid "Clients" +msgstr "Contenido" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +#, fuzzy +msgid "HTML Serialization" +msgstr "Traducciones" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +#, fuzzy +msgid "Project List" +msgstr "Proyecto" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +#, fuzzy +msgid "Project Detail" +msgstr "Nombre de proyecto" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +#, fuzzy +msgid "Backwards Compatibility" +msgstr "Etiquetas de compatibilidad con plataformas" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +#, fuzzy +msgid "JSON Serialization" +msgstr "Traducciones" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +#, fuzzy +msgid "As an example:" +msgstr "Por ejemplo:" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +#, fuzzy +msgid "Content-Types" +msgstr "Contenido" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +#, fuzzy +msgid "Version + Format Selection" +msgstr "Versión" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +#, fuzzy +msgid "Endpoint Configuration" +msgstr "Configuraciones habituales" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +#, fuzzy +msgid "Source distribution archive features" +msgstr "Formatos de archivo de distribución de paquetes" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +#, fuzzy +msgid "Definitions" +msgstr "Especificaciones" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +#, fuzzy +msgid "Version scheme" +msgstr "Versión" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "Por ejemplo::" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +msgid "Pre-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +#, fuzzy +msgid "Version epochs" +msgstr "Versión" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +#, fuzzy +msgid "Normalization" +msgstr "Traducciones" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +#, fuzzy +msgid "Integer Normalization" +msgstr "Traducciones" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +#, fuzzy +msgid "Version matching" +msgstr "Versión" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +#, fuzzy +msgid "Version exclusion" +msgstr "Versión" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +#, fuzzy +msgid "Remote URL examples::" +msgstr "Por ejemplo::" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +#, fuzzy +msgid "Python Virtual Environments" +msgstr "Entorno virtual" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +#, fuzzy +msgid "Runtime detection of virtual environments" +msgstr "Facultativamente, cree un entorno virtual" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +#, fuzzy +msgid "Well-known Project URLs in Metadata" +msgstr "Nombre de proyecto" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +#, fuzzy +msgid "Label normalization" +msgstr "Traducciones" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +#, fuzzy +msgid "Normalized" +msgstr "Traducciones" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +#, fuzzy +msgid "``documentation`` (Documentation)" +msgstr "Creación de documentación" + +#: ../source/specifications/well-known-project-urls.rst:124 +#, fuzzy +msgid "The project's online documentation" +msgstr "Creación de documentación" + +#: ../source/specifications/well-known-project-urls.rst:125 +#, fuzzy +msgid "``docs``" +msgstr "``upload_docs``" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +#, fuzzy +msgid "Funding Information" +msgstr "Configuraciones habituales" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +#, fuzzy +msgid "Example behavior" +msgstr "Ejemplos" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "Cómo obtener asistencia" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"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/creating-documentation.rst:4 +#, fuzzy +msgid "Creating documentation" +msgstr "Creación de documentación" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "Instalación de paquetes" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "Requisitos para instalar paquetes" + +#: ../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: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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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: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:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +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 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "Instalación a partir de PyPI" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "Para instalar una versión específica:" + +#: ../source/tutorials/installing-packages.rst:339 +msgid "To install greater than or equal to one version and less than another:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +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 `." +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 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +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 +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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "Instalando \"Extras\"" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +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 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../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 "" +"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/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):" +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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +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:" +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." +msgstr "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "Empaquetamiento de proyectos Python" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../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: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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "Creación de los archivos del paquete" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "Creación de un directorio de pruebas" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "Configuración de los metadatos" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" +"Se le pedirá un token de API. Utilice el valor del token, incluido el " +"prefijo ``pypi-``. Ten en cuenta que la entrada estará oculta, así que " +"asegúrate de pegarla correctamente." + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "Una vez completado el comando, debería ver una salida similar a ésta:" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" +"Una vez subido, su paquete debería ser visible en TestPyPI; por ejemplo: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "Instalación de su paquete recién cargado" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" + +#, fuzzy +#~ msgid "**Inspiration**: :ref:` pyproject-tool-table`" +#~ msgstr "Nombre de proyecto" + +#, fuzzy +#~ msgid "Signing the distribution packages" +#~ msgstr "Paquete de Distribución" + +#~ msgid "Give a short and long description for your project." +#~ msgstr "Brinde una descripción breve y una larga del proyecto." + +#~ msgid "Give a homepage URL for your project." +#~ msgstr "Proporcione un URL de página principal del proyecto." + +#~ msgid "List keywords that describe your project." +#~ msgstr "Añada palabras clave que describan su proyecto." + +#, fuzzy +#~ msgid ":ref:`declaring-build-dependencies`" +#~ msgstr "Dependencias externas" + +#, fuzzy +#~ msgid "Current recommendation" +#~ msgstr "Recomendaciones de herramientas" + +#~ msgid "Installing Sphinx" +#~ msgstr "Instalación de Sphinx" + +#~ msgid "Use ``pip`` to install Sphinx:" +#~ msgstr "Sírvase de ``pip`` para instalar Sphinx:" + +#~ msgid "Getting Started With Sphinx" +#~ msgstr "Primeros pasos con Sphinx" + +#~ msgid "" +#~ "Create a ``docs`` directory inside your project to hold your " +#~ "documentation:" +#~ msgstr "" +#~ "Cree un directorio denominado ``docs`` en el proyecto; allí se almacenará " +#~ "su documentación:" + +#~ msgid "Run ``sphinx-quickstart`` inside the ``docs`` directory:" +#~ msgstr "Ejecute ``sphinx-quickstart`` dentro del directorio ``docs``:" + +#~ msgid "Platform tags for Windows" +#~ msgstr "Etiquetas de plataforma para Windows" + +#~ msgid "Platform tags for macOS (Mac OS X)" +#~ msgstr "Etiquetas de plataforma para macOS (Mac OS X)" + +#~ msgid "Platform tags for common Linux distributions" +#~ msgstr "Etiquetas de plataforma para distribuciones Linux comunes" + +#~ msgid "" +#~ "When ``pipenv`` does not meet your use case, consider other tools like:" +#~ msgstr "" +#~ "Si ``pipenv`` no se ajusta a sus necesidades, considere utilizar otras " +#~ "herramientas, como:" + +#~ msgid "For Python 2.7" +#~ msgstr "Para Python 2.7" + +#~ msgid "For Python 3.4" +#~ msgstr "Para Python 3.4" + +#~ msgid "For Python 3.5" +#~ msgstr "Para Python 3.5" diff --git a/locales/fa/LC_MESSAGES/messages.po b/locales/fa/LC_MESSAGES/messages.po new file mode 100644 index 000000000..5e032a89d --- /dev/null +++ b/locales/fa/LC_MESSAGES/messages.po @@ -0,0 +1,26852 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# xashayar kml , 2022. +# Arsalan Dehghani , 2023. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: 2023-02-15 07:52+0000\n" +"Last-Translator: Arsalan Dehghani \n" +"Language-Team: Persian \n" +"Language: fa\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=2; plural=n > 1;\n" +"X-Generator: Weblate 4.16-dev\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "مشارکت در این راهنما" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "مطالعه‌ی راهنما و ارسال بازخورد" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "بررسی مشارکت‌های جدید" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "بازنگری محتوای موجود" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "نوشتن مطالب جدید" + +#: ../source/contribute.rst:14 +#, fuzzy +#| msgid "Translate the guide" +msgid "Translating the guide" +msgstr "ترجمه‌ی راهنما" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "راهنماها" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "بحث‌ها" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "مشخصات" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "ترجمه‌ها" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "افزودن یک زبان" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "ساخت راهنما به صورت محلی" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "" + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "" + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "اشتباه : پیپ استفاده میکند از .…" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "" + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "**شماره‌ها**" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "ناقص" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "" + +#: ../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 +msgid "What is a source distribution?" +msgstr "" + +#: ../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 +msgid "What about eggs?" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python setup.py install``" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python -m pip install --editable .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:104 +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr "" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +#, fuzzy +#| msgid "Incomplete" +msgid "Complete" +msgstr "ناقص" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +#, fuzzy +msgid "Versioning" +msgstr "ترجمه‌ها" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +#, fuzzy +msgid "Calendar versioning" +msgstr "ترجمه‌ها" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +#, fuzzy +msgid "Other schemes" +msgstr "ترجمه‌ها" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 ../source/flow.rst:143 +msgid "" +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../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 :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +#, fuzzy +#| msgid "Translations" +msgid "Installed Project" +msgstr "ترجمه‌ها" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +msgid "Project Root Directory" +msgstr "" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "ماژول خالص" + +#: ../source/glossary.rst:257 +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:260 +msgid "Pyproject Metadata" +msgstr "" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +msgid "Pyproject Metadata Key" +msgstr "" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "" + +#: ../source/glossary.rst:344 +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:348 +msgid "Root License Directory" +msgstr "" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +msgid "Wheel Project" +msgstr "" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "" +"https://files.pythonhosted.org/packages/eb/" +"45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" +"sampleproject-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "" +"https://files.pythonhosted.org/packages/56/0a/" +"178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" +"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +msgid "" +"https://files.pythonhosted.org/packages/" +"63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" +"sampleproject_nomura-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +#, fuzzy +#| msgid "Translations" +msgid "Creating the package" +msgstr "ترجمه‌ها" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +msgid "``pyproject.toml``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +#, fuzzy +#| msgid "Translations" +msgid "Installing the package with ``pipx``" +msgstr "ترجمه‌ها" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +#, fuzzy +msgid "Conclusion" +msgstr "ترجمه‌ها" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +#, fuzzy +#| msgid "Translations" +msgid "1. Install twine" +msgstr "ترجمه‌ها" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +msgid "Dropping a Python version" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:108 +msgid "openSUSE" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:118 +msgid "Debian/Ubuntu and derivatives" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +msgid "Install packages in a virtual environment using pip and venv" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +msgid "Install packages using pip" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +#, fuzzy +#| msgid "Translations" +msgid "Install extras" +msgstr "ترجمه‌ها" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +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/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python -m build``" +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:126 +msgid "``python -m build --no-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:127 +msgid "``python -m pip install --no-build-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../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 "" +"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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +#, fuzzy +#| msgid "Translations" +msgid "Installation" +msgstr "ترجمه‌ها" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:233 +msgid "``appveyor-sample/build.cmd``" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:5 +msgid "Tool recommendations" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +#, fuzzy +#| msgid "Translations" +msgid "Installing packages" +msgstr "ترجمه‌ها" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +#, fuzzy +#| msgid "Reviewing new contributions" +msgid "Building distributions" +msgstr "بررسی مشارکت‌های جدید" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:313 +msgid "setuptools" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:317 +msgid "uv-build" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +msgid "`Kivy `_" +msgstr "" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "Subdirectory name" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +msgid "``licenses``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*object*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Schema version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "examples" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +msgid "**version**" +msgstr "ترجمه‌ها" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +msgid "version\\_info" +msgstr "ترجمه‌ها" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "**Numbers**" +msgid "*number*" +msgstr "**شماره‌ها**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**implementation**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**flags**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +msgid "extensions" +msgstr "ترجمه‌ها" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "**Numbers**" +msgid "**headers**" +msgstr "**شماره‌ها**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +msgid "Package Building" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +#, fuzzy +msgid "Versions" +msgstr "ترجمه‌ها" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +msgid ":ref:`Version `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +msgid "``toml``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +msgid "``dependency_groups``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +#, fuzzy +#| msgid "Translations" +msgid "Installers" +msgstr "ترجمه‌ها" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +msgid "Reference implementation in Python" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +#, fuzzy +msgid "Names and normalization" +msgstr "ترجمه‌ها" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +#, fuzzy +msgid "Name normalization" +msgstr "ترجمه‌ها" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +msgid "Project Status Markers" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +#, fuzzy +#| msgid "Translations" +msgid "Installer semantics: none." +msgstr "ترجمه‌ها" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +#, fuzzy +#| msgid "Translations" +msgid "Installer semantics:" +msgstr "ترجمه‌ها" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +msgid "``deprecated``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +#, fuzzy +#| msgid "Specifications" +msgid "``pylock.toml`` Specification" +msgstr "مشخصات" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +msgid "``lock-version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +msgid "**Required?**: yes" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +msgid "``environments``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +msgid "``dependency-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +msgid "``[[packages]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +msgid "``packages.version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +#, fuzzy +#| msgid "Translations" +msgid "The version of the package." +msgstr "ترجمه‌ها" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +msgid "``[[packages.dependencies]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +msgid "The time the file was uploaded." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +msgid "``packages.index``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +msgid "``import-names``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +#, fuzzy +#| msgid "Specifications" +msgid "Legacy specification" +msgstr "مشخصات" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +msgid "Examples:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +msgid "Example:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +msgid "PyPA schemas" +msgstr "" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +msgid "Python Description Formats" +msgstr "" + +#: ../source/specifications/section-reproducible-environments.rst:3 +msgid "Reproducible Environments" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +#, fuzzy +msgid "Normalized Names" +msgstr "ترجمه‌ها" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +#, fuzzy +msgid "HTML Serialization" +msgstr "ترجمه‌ها" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +msgid "Project List" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +msgid "Project Detail" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +#, fuzzy +msgid "JSON Serialization" +msgstr "ترجمه‌ها" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +msgid "Content-Types" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +#, fuzzy +msgid "Version + Format Selection" +msgstr "ترجمه‌ها" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +#, fuzzy +#| msgid "Specifications" +msgid "Definitions" +msgstr "مشخصات" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +#, fuzzy +msgid "Version scheme" +msgstr "ترجمه‌ها" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +msgid "Pre-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +#, fuzzy +msgid "Version epochs" +msgstr "ترجمه‌ها" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +#, fuzzy +msgid "Normalization" +msgstr "ترجمه‌ها" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +#, fuzzy +msgid "Integer Normalization" +msgstr "ترجمه‌ها" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +#, fuzzy +msgid "Version exclusion" +msgstr "ترجمه‌ها" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +msgid "Well-known Project URLs in Metadata" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +#, fuzzy +msgid "Label normalization" +msgstr "ترجمه‌ها" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +#, fuzzy +msgid "Normalized" +msgstr "ترجمه‌ها" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"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/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "" + +#: ../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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "" + +#: ../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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" diff --git a/locales/fil/LC_MESSAGES/messages.po b/locales/fil/LC_MESSAGES/messages.po new file mode 100644 index 000000000..e851b4f09 --- /dev/null +++ b/locales/fil/LC_MESSAGES/messages.po @@ -0,0 +1,26795 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# John Lester L. Licayan , 2022. +# RedFurrFox , 2022. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: 2022-11-19 08:28+0000\n" +"Last-Translator: RedFurrFox \n" +"Language-Team: Filipino \n" +"Language: fil\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=2; plural=n != 1 && n != 2 && n != 3 && (n % 10 == 4 " +"|| n % 10 == 6 || n % 10 == 9);\n" +"X-Generator: Weblate 4.15-dev\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "" + +#: ../source/contribute.rst:14 +msgid "Translating the guide" +msgstr "" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +#, fuzzy +msgid "Tutorials" +msgstr "Tutoryal" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "" + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "" + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "" + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "" + +#: ../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 +msgid "What is a source distribution?" +msgstr "" + +#: ../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 +msgid "What about eggs?" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python setup.py install``" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python -m pip install --editable .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:104 +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr "" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +msgid "Complete" +msgstr "" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +msgid "Versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +msgid "Calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +msgid "Other schemes" +msgstr "" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 ../source/flow.rst:143 +msgid "" +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../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 :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +msgid "Installed Project" +msgstr "" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +msgid "Project Root Directory" +msgstr "" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "" + +#: ../source/glossary.rst:257 +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:260 +msgid "Pyproject Metadata" +msgstr "" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +msgid "Pyproject Metadata Key" +msgstr "" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "" + +#: ../source/glossary.rst:344 +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:348 +msgid "Root License Directory" +msgstr "" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +msgid "Wheel Project" +msgstr "" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "" +"https://files.pythonhosted.org/packages/eb/" +"45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" +"sampleproject-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "" +"https://files.pythonhosted.org/packages/56/0a/" +"178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" +"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +msgid "" +"https://files.pythonhosted.org/packages/" +"63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" +"sampleproject_nomura-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +msgid "Creating the package" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +msgid "``pyproject.toml``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +msgid "Installing the package with ``pipx``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +msgid "Conclusion" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +msgid "1. Install twine" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +msgid "Dropping a Python version" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:108 +msgid "openSUSE" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:118 +msgid "Debian/Ubuntu and derivatives" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +msgid "Install packages in a virtual environment using pip and venv" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +msgid "Install packages using pip" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +msgid "Install extras" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +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/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python -m build``" +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:126 +msgid "``python -m build --no-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:127 +msgid "``python -m pip install --no-build-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../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 "" +"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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +msgid "Installation" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:233 +msgid "``appveyor-sample/build.cmd``" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:5 +msgid "Tool recommendations" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +msgid "Installing packages" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +msgid "Building distributions" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:313 +msgid "setuptools" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:317 +msgid "uv-build" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +msgid "`Kivy `_" +msgstr "" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "Subdirectory name" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +msgid "``licenses``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*object*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Schema version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "examples" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "version\\_info" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*number*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**implementation**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**flags**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**headers**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +msgid "Package Building" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +msgid ":ref:`Version `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +msgid "``toml``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +msgid "``dependency_groups``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +msgid "Installers" +msgstr "" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +msgid "Reference implementation in Python" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +msgid "Names and normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +msgid "Name normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +msgid "Project Status Markers" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +msgid "Installer semantics: none." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +msgid "Installer semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +msgid "``deprecated``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +msgid "``pylock.toml`` Specification" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +msgid "``lock-version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +msgid "**Required?**: yes" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +msgid "``environments``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +msgid "``dependency-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +msgid "``[[packages]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +msgid "``packages.version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +msgid "The version of the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +msgid "``[[packages.dependencies]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +msgid "The time the file was uploaded." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +msgid "``packages.index``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +msgid "``import-names``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +msgid "Legacy specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +msgid "Examples:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +msgid "Example:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +msgid "PyPA schemas" +msgstr "" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +msgid "Python Description Formats" +msgstr "" + +#: ../source/specifications/section-reproducible-environments.rst:3 +msgid "Reproducible Environments" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +msgid "Normalized Names" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +msgid "HTML Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +msgid "Project List" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +msgid "Project Detail" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +msgid "JSON Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +msgid "Content-Types" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +msgid "Version + Format Selection" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +msgid "Definitions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +msgid "Version scheme" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +msgid "Pre-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +msgid "Version epochs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +msgid "Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +msgid "Integer Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +msgid "Version exclusion" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +msgid "Well-known Project URLs in Metadata" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +msgid "Label normalization" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +msgid "Normalized" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"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/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "" + +#: ../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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "" + +#: ../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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" diff --git a/locales/fr/LC_MESSAGES/messages.po b/locales/fr/LC_MESSAGES/messages.po new file mode 100644 index 000000000..836200722 --- /dev/null +++ b/locales/fr/LC_MESSAGES/messages.po @@ -0,0 +1,27553 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# Nathan , 2021, 2022, 2026. +# Abdur-Rahmaan Janhangeer , 2021. +# Matthieu Darbois , 2022. +# Rafael Fontenelle , 2024. +# Pierre PETAT , 2024. +# Laurent FAVOLE , 2024. +# Bruno Alla , 2025. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: 2026-01-20 00:01+0000\n" +"Last-Translator: Nathan \n" +"Language-Team: French \n" +"Language: fr\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=2; plural=n > 1;\n" +"X-Generator: Weblate 5.16-dev\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "Contribuer à ce guide" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "" +"La |PyPUG| accueille les contributeurs ! Il existe de nombreuses façons de " +"contribuer, notamment :" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "Lire le guide et envoyer des commentaires" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "Passer en revue les nouvelles contributions" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "Réviser le contenu existant" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "Rédiger du nouveau contenu" + +#: ../source/contribute.rst:14 +msgid "Translating the guide" +msgstr "Traduire le guide" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" +"La plupart du travail sur |PyPUG| prend place sur le `dépôt GitHub du " +"projet`__. Pour commencer, consultez la liste des `open issues`__ et des " +"`pull requests`__. Si vous avez l'intention de rédiger ou modifier le guide, " +"veuillez lire le :ref:`style guide `" + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" +"En contribuant à la |PyPUG|, vous devez respecter le `Code de conduite`__ de " +"la PSF." + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "Types de documentation" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" +"Ce projet consiste en quatre types de documentation utilisés à des fins " +"spécifiques. Le projet aspire à suivre le `processus de Diátaxis`_ pour " +"créer une documentation de qualité. Lorsque vous proposez des nouveaux " +"ajouts au projet, veuillez sélectionner le type de documentation approprié." + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "Tutoriels" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" +"Les tutoriels se concentrent à enseigner de nouveaux concepts par accomplir " +"un but. Ils sont opinés et vont pas à pas. Ils n'excluent pas informations " +"et avertissement étrangers. `example tutorial-style document`_." + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "Guides" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "Discussions" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "Spécifications" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "Traductions" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" +"Si vous faites face a des problèmes lors de vos travaux de traductions, " +"veuillez ouvrir un ticket sur `GitHub`_." + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" +"Chaque traduction sur ce projet doit suivre la syntax`reStructuredText " +"syntax`_." + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "Ajouter une langue" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "**Ne traduisez pas le texte dans les références directement**" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "" +"Quand vous traduisez le texte dans une référence, veuillez ne pas le " +"traduire directement." + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "Mauvais : Traduire le texte suivant directement :" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" +"Bon : Traduire le texte suivant dans votre propre langue et ajouter la " +"référence originale :" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "Compiler le guide localement" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" +"Même si ce n'est pas nécessaire pour effectuer des contributions, il peut " +"être utile de compiler le guide localement afin de test vos modifications. " +"Afin de compiler ce guide localement, vous aurez besoin de :" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" +":doc:`Nox `. Vous pouvez installer ou mettre à jour nox en " +"utilisant ``pip`` :" + +#: ../source/contribute.rst:136 +#, fuzzy +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" +"Python 3.8. Nos scripts de compilation sont conçus pour fonctionner avec " +"Python 3.8 uniquement. Consultez le `Guide de l'auto-stoppeur pour Python : " +"Installer Python correctement`_ pour installer Python 3.8 sur votre système " +"d'exploitation." + +#: ../source/contribute.rst:140 +#, fuzzy +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" +"Pour compiler le guide, exécutez la commande bash suivante dans le dossier " +"source :" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" +"Une fois le processus terminé vous pouvez retrouver le résultat au format " +"HTML dans le dossier ``./build/html``. Vous pouvez ouvrir le fichier " +"``index.html`` pour visualiser le guide dans votre navigateur, mais il est " +"recommandé de déployer le guide sur un serveur HTTP." + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" +"Vous pouvez compiler le guide et le déployer sur un serveur HTTP en " +"utilisant la commande suivante :" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "Le guide pourra être consulté à l'adresse http://localhost:8000." + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "Où le guide est-il déployé ?" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" +"Ce guide est déployé à l'aide de ReadTheDocs et sa configuration est " +"disponible à https://readthedocs.org/projects/python-packaging-user-guide/. " +"Il est servi à partir d'un domaine personnalisé et présenté par Fast.ly." + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "Guide de conception" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "Objectif" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" +"L'objectif du |PyPUG| est d'être la ressource officielle sur la façon " +"d'empaqueter, publier, et installer des projets Python en utilisant des " +"outils courants." + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "Portée" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" +"Le guide a pour but de répondre aux questions et de résoudre les problèmes " +"par des recommandations précises et ciblées." + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" +"Ce guide n'a pas pour but d'être exhaustif et de remplacer la documentation " +"des projets individuels. Par exemple, pip possède des dizaines de commandes, " +"d'options et de paramètres. La documentation de pip décrit chacun d'entre " +"eux en détail, alors que ce guide ne décrit que les parties de pip qui sont " +"nécessaires pour accomplir les tâches spécifiques décrites dans ce guide." + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "Public cible" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "" +"Le public visé par ce guide est toute personne qui utilise Python avec des " +"paquets." + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" +"N'oubliez pas que la communauté Python est grande et accueillante. Les " +"lecteurs n'ont peut-être pas le même âge, le même genre, le même niveau " +"d'éducation, la même culture et bien d'autres choses encore, mais ils " +"méritent autant que vous d'apprendre à connaître le paquetage." + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" +"En particulier, gardez à l'esprit que toutes les personnes qui utilisent " +"Python ne se considèrent pas comme des développeurs. Le public de ce guide " +"comprend aussi bien des astronomes, des peintres ou des étudiants que des " +"développeurs de logiciels professionnels." + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "Tonalité" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" +"Lorsque vous rédigez ce guide, tâchez d'écrire avec un ton accessible et " +"simple, même si vous connaissez toutes les solutions." + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" +"Imaginez que vous travaillez sur un projet Python avec une personne que vous " +"savez intelligente et compétente. Vous aimez travailler avec elle et elle " +"aime travailler avec vous. Cette personne vous pose une question et vous " +"connaissez la réponse. Comment répondre ? C'est *ainsi* que vous devriez " +"écrire ce guide." + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" +"Voici une méthode de vérification rapide : essayez de lire à haute voix pour " +"vous faire une idée de la tonalité de votre texte. Est-ce que cela ressemble " +"à ce que vous diriez ou est-ce que vous avez l'impression de jouer un rôle " +"ou de faire un discours ? N'hésitez pas à utiliser des contractions et ne " +"vous souciez pas de respecter des règles de grammaire strictes. Vous avez la " +"permission de terminer une phrase par une préposition, si nécessaire." + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" +"Lorsque vous rédigez le guide, adaptez votre ton au sérieux et à la " +"difficulté du sujet. Si vous rédigez un didacticiel d'introduction, vous " +"pouvez faire une blague, mais si vous traitez d'une recommandation de " +"sécurité sensible, il est préférable d'éviter toute plaisanterie." + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "Conventions et mécanismes" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "**Écrivez au lecteur**" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" +"Lorsque vous donnez des recommandations ou des étapes à suivre, adressez-" +"vous directement au lecteur en disant *vous* ou utilisez l'impératif." + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "Mauvais : Pour l'installer, l'utilisateur exécute…" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "Correct : Vous pouvez l'installer en exécutant…" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "Correct : Pour l'installer, exécutez…" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" +"La première fois que vous mentionnez un outil ou une pratique, ajoutez un " +"lien vers la page ou le guide concerné, ou ajoutez un lien vers tout " +"document pertinent. Économisez une recherche au lecteur." + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "**Respectez les conventions de nommage**" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" +"Lorsque vous nommez des outils, sites, personnes ou autres noms propres, " +"respectez leur casse." + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "Mauvais : Pip utilise…" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "Correct : pip utilise…" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "Mauvais : …hébergé sur github." + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "Correct : …hébergé sur GitHub." + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "**Adoptez un style neutre et non genré**" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" +"Souvent, vous vous adresserez au lecteur directement avec *vous*, *votre* et " +"*vos*. Utilisez dans la mesure du possible des formes non genrées, sinon " +"adoptez l'écriture inclusive." + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "Mauvais : Un mainteneur met en ligne le fichier. Puis il…" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "Correct : Un·e mainteneur·euse met en ligne le fichier. Puis…" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "Correct : Un mainteneur téléverse le fichier. Puis le mainteneur…" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "**Titres**" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" +"Rédigez des titres qui utilisent les mots recherchés par le lecteur ou la " +"lectrice. Un bon moyen d'y parvenir est de faire en sorte que votre titre " +"réponde à une question implicite. Par exemple, un lecteur ou une lectrice " +"pourrait vouloir savoir *Comment installer MaBibliothèque ?* et un bon titre " +"pourrait être *Installer MaBibliothèque*." + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" +"Dans les titres de section, employez la casse des phrases. En d'autres " +"termes, rédigez les titres comme vous le feriez pour une phrase classique." + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "Mauvais : Les Choses Que Vous Devez Savoir À Propos de Python" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "Correct : Les choses que vous devez savoir à propos de Python" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "**Nombres**" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" +"Dans le corps du texte, écrivez les chiffres de un à neuf comme des mots. " +"Pour les autres chiffres ou les chiffres des tableaux, utilisez des " +"caractères numériques." + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "Déployer des applications Python" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "État de la page" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "Incomplet" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "Dernière révision" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "24/08/2021" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "Aperçu" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "Prendre en charge plusieurs plateformes matérielles" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" +"Le programme installé peut être lancé à partir d'un raccourci que " +"l'installateur ajoute au menu démarrer. Il utilise un interpréteur Python " +"installé dans son répertoire racine, indépendamment de toute autre " +"installation de Python sur l'ordinateur." + +#: ../source/discussions/deploying-python-applications.rst:71 +#, fuzzy +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" +"L'un des gros avantages de Pynsist est que les paquets Windows peuvent être " +"compilés sous Linux. Il y a plusieurs exemples pour différents types de " +"programmes (console, interface graphique) dans la `documentation " +"`. L'outil est publié sous licence MIT." + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "Paquets d'applications" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "py2exe" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "macOS" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "py2app" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "Unix (en incluant Linux et macOS)" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "pex" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "Gestion de la configuration" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +#, fuzzy +msgid "What's a distribution package?" +msgstr "Paqueter et distribuer des projets" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:51 +#, fuzzy +#| msgid "Source distributions" +msgid "Provide complete source distributions" +msgstr "Distributions sources" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +#, fuzzy +msgid "Aim for stable releases" +msgstr "Version" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" +"Les **discussions** ont pour but de fournir une information complète sur un " +"sujet spécifique. Si vous essayez seulement de mener à bien vos tâches, " +"consultez :doc:`/guides/index`." + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "Fichiers requirements vs install_requires" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" +"``install_requires`` est un mot-clé de :ref:`setuptools` :file:`setup.py` " +"qui doit être utilisé pour spécifier ce dont un projet à besoin *au minimum* " +"pour s'exécuter correctement. Lorsque le projet est installé par :ref:`pip`, " +"c'est cette spécification qui est utilisée pour installer ses dépendances." + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" +"Par exemple, si le projet nécessite A et B, votre ``install_requires`` " +"ressemblerait à ceci :" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" +"En outre, il est préférable d'indiquer toute limite inférieure ou supérieure " +"connue." + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" +"Par exemple, on peut savoir que votre projet nécessite au moins la v1 de " +"« A » et la v2 de « B », ce qui donne le résultat suivant :" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +#, fuzzy +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" +"On peut également savoir que le projet A respecte le système de version " +"sémantique, et que la v2 de « A » indique une rupture de compatibilité, il " +"est donc logique de ne pas autoriser la version 2 :" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" + +#: ../source/discussions/package-formats.rst:5 +#, fuzzy +msgid "Package Formats" +msgstr "Version du paquet" + +#: ../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 "Paqueter et distribuer des projets" + +#: ../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 +msgid "What about eggs?" +msgstr "" + +#: ../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 "pip vs easy_install" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "" + +#: ../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 "Oui" + +#: ../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 "Non" + +#: ../source/discussions/pip-vs-easy-install.rst:30 +msgid "Uninstall Packages" +msgstr "Désinstaller des paquets" + +#: ../source/discussions/pip-vs-easy-install.rst:30 +msgid "Yes (``python -m pip uninstall``)" +msgstr "Oui (``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 "Oui (:ref:`Requirements Files `)" + +#: ../source/discussions/pip-vs-easy-install.rst:35 +msgid "List Installed Packages" +msgstr "Lister les paquets installés" + +#: ../source/discussions/pip-vs-easy-install.rst:35 +msgid "Yes (``python -m pip list`` and ``python -m pip freeze``)" +msgstr "Oui (``python -m pip list`` et ``python -m pip freeze``)" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Installation format" +msgstr "Format d'installation" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "'Flat' packages with :file:`egg-info` metadata." +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "Oui [1]_" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr "" + +#: ../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 "Seulement dans virtualenv" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "Oui, via setup.cfg" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +#, fuzzy +msgid "``python setup.py install``" +msgstr "Oui (``python -m pip uninstall``)" + +#: ../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 "" + +#: ../source/discussions/setup-py-deprecated.rst:25 +#: ../source/discussions/setup-py-deprecated.rst:39 +#: ../source/guides/modernize-setup-py-project.rst:36 +#, fuzzy +msgid "``python setup.py sdist``" +msgstr "Version de Python" + +#: ../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 "" + +#: ../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 "Obsolète" + +#: ../source/discussions/setup-py-deprecated.rst:33 +#: ../source/guides/modernize-setup-py-project.rst:30 +#, fuzzy +msgid "Recommendation" +msgstr "Types de documentation" + +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +#, fuzzy +msgid "``python -m pip install .``" +msgstr "Oui (``python -m pip uninstall``)" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +#, fuzzy +msgid "``python -m pip install --editable .``" +msgstr "Oui (``python -m pip uninstall``)" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +#, fuzzy +msgid "``python setup.py test``" +msgstr "Version de Python" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "``python -m twine check --strict dist/*``" + +#: ../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/setup-py-deprecated.rst:105 +#, fuzzy +msgid "``python -m twine upload dist/*``" +msgstr "Oui (``python -m pip uninstall``)" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +#, fuzzy +msgid "``python setup.py --version``" +msgstr "Version de Python" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +#, fuzzy +msgid "``python -m setuptools_scm``" +msgstr "Oui (``python -m pip uninstall``)" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +#, fuzzy +msgid "``build``" +msgstr "Oui (``python -m pip uninstall``)" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +#, fuzzy +msgid "``dist_info``" +msgstr "``pypinfo``" + +#: ../source/discussions/setup-py-deprecated.rst:141 +#, fuzzy +msgid "``easy_install``" +msgstr "Oui (``python -m pip uninstall``)" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +#, fuzzy +msgid "``egg_info``" +msgstr "``pypinfo``" + +#: ../source/discussions/setup-py-deprecated.rst:144 +#, fuzzy +msgid "``install_data``" +msgstr "Oui (``python -m pip uninstall``)" + +#: ../source/discussions/setup-py-deprecated.rst:145 +#, fuzzy +msgid "``install_egg_info``" +msgstr "Oui (``python -m pip uninstall``)" + +#: ../source/discussions/setup-py-deprecated.rst:146 +#, fuzzy +msgid "``install_headers``" +msgstr "Oui (``python -m pip uninstall``)" + +#: ../source/discussions/setup-py-deprecated.rst:147 +#, fuzzy +msgid "``install_lib``" +msgstr "Oui (``python -m pip uninstall``)" + +#: ../source/discussions/setup-py-deprecated.rst:148 +#, fuzzy +msgid "``install_scripts``" +msgstr "Oui (``python -m pip uninstall``)" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +#, fuzzy +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "pyproject.toml" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr "" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +#, fuzzy +msgid "Complete" +msgstr "Incomplet" + +#: ../source/discussions/single-source-version.rst:8 +#, fuzzy +msgid "2024-10-07" +msgstr "2017-08-01" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +#, fuzzy +msgid "Versioning" +msgstr "Traductions" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +#, fuzzy +msgid "Calendar versioning" +msgstr "Traductions" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +#, fuzzy +msgid "Other schemes" +msgstr "Traductions" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:60 +#, fuzzy +msgid "The configuration file" +msgstr "Gestion de la configuration" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 ../source/flow.rst:143 +msgid "" +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +#, fuzzy +msgid "The built distributions (wheels)" +msgstr "Distribution compilée" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../source/glossary.rst:3 +msgid "Glossary" +msgstr "Glossaire" + +#: ../source/glossary.rst:8 +msgid "Binary Distribution" +msgstr "Distribution binaire" + +#: ../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 :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../source/glossary.rst:44 +msgid "Built Distribution" +msgstr "Distribution compilée" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +#, fuzzy +msgid "Distribution Archive" +msgstr "Distribution compilée" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "Egg" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "Module d'extension" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +#, fuzzy +msgid "Installed Project" +msgstr "Installateur" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +#, fuzzy +#| msgid "``classifiers``" +msgid "License Classifier" +msgstr "``classifiers``" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "Module" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "Projet" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +#, fuzzy +msgid "Project Root Directory" +msgstr "Nom du projet" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "Module pur" + +#: ../source/glossary.rst:257 +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:260 +#, fuzzy +msgid "Pyproject Metadata" +msgstr "Nom du projet" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +#, fuzzy +msgid "Pyproject Metadata Key" +msgstr "pyproject.toml" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "Index des Paquets Python (PyPI)" + +#: ../source/glossary.rst:298 +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 `_ est l':term:`Index de Paquets ` " +"par défaut pour la communauté Python. Il est ouvert à tous les développeurs " +"Python pour qu'ils utilisent et distribuent leurs paquets." + +#: ../source/glossary.rst:301 +msgid "pypi.org" +msgstr "pypi.org" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "pyproject.toml" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "Version" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" +"Une image d'un :term:`Projet` à un certain moment dans le temps, défini par " +"un numéro de version." + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "Dépendance" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "" + +#: ../source/glossary.rst:344 +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:348 +#, fuzzy +msgid "Root License Directory" +msgstr "Nom du projet" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "setup.py" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "setup.cfg" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "Paquet système" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" +"Un paquet fourni dans un format natif au système d'exploitation, par ex. un " +"fichier rpm ou dpkg." + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "Environnement virtuel" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "Wheel" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +#, fuzzy +msgid "Wheel Project" +msgstr "Projet" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "Contexte" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "Jeu de données public" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "Créer un nouveau projet." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "Schéma de données" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "Colonne" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "Description" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "Exemples" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "Date et heure" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "Nom du projet" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "Version du paquet" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "Installateur" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "Version de Python" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "Requêtes utiles" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "Téléchargements de paquets au cours du temps" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "1956741" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "2344692" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "2017-12-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "1730398" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "2017-11-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "2047310" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "2017-10-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "1744443" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "2017-09-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "1916952" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "2017-08-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "Versions de Python au cours du temps" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" +"Extraie la version de Python à partir de la colonne ``details.python``. " +"Attention : Cette requête traite plus de 500 Go de données." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "python" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "3.7" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "18051328726" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "3.6" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "9635067203" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "3.8" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "7781904681" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "2.7" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "6381252241" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "2026630299" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "3.5" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "1894153540" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "url" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +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/analyzing-pypi-package-downloads.rst:246 +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/analyzing-pypi-package-downloads.rst:248 +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/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "Inconvénients" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "Outils supplémentaires" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" +"En plus de l'utilisation de la console BigQuery, il existe quelques outils " +"supplémentaires qui peuvent être utiles pour analyser les statistiques de " +"téléchargement." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "``google-cloud-bigquery``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "``pypinfo``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "Installez `pypinfo`_ à l'aide de pip." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "Usage :" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "``pandas-gbq``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "Références" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "Créer et découvrir des extensions" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "En utilisant les métadonnées du paquet" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +#, fuzzy +msgid "Creating and packaging command-line tools" +msgstr "Créer et découvrir des extensions" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +#, fuzzy +msgid "Creating the package" +msgstr "Désinstaller des paquets" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +#, fuzzy +msgid "``pyproject.toml``" +msgstr "pyproject.toml" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +#, fuzzy +msgid "Installing the package with ``pipx``" +msgstr "Installez `pypinfo`_ à l'aide de pip." + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +#, fuzzy +msgid "Conclusion" +msgstr "Traductions" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "Paqueter et distribuer des projets" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +#, fuzzy +msgid "2023-12-14" +msgstr "2017-12-01" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "Installez « twine » [1]_ :" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:52 +msgid "Configuring your project" +msgstr "Configurer votre projet" + +#: ../source/guides/distributing-packages-using-setuptools.rst:56 +msgid "Initial files" +msgstr "Fichiers initiaux" + +#: ../source/guides/distributing-packages-using-setuptools.rst:61 +msgid "" +"The most important file is :file:`setup.py` which exists at the root of your " +"project directory. For an example, see the `setup.py `_ " +"in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "README.rst / README.md" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "MANIFEST.in" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "LICENSE.txt" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "arguments pour setup()" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "``packages``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +msgstr "``py_modules``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:198 +msgid "" +"If your project contains any single-file Python modules that aren't part of " +"a package, set ``py_modules`` to a list of the names of the modules (minus " +"the ``.py`` extension) in order to make :ref:`setuptools` aware of them." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "``package_data``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "``data_files``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "Distributions sources" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "Wheels" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "Créer un compte" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "Dépendances" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +#, fuzzy +msgid "1. Install twine" +msgstr "Format d'installation" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +#, fuzzy +msgid "Dropping a Python version" +msgstr "Version de Python" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "Dépôt \"manuel\"" + +#: ../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 "" + +#: ../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 "" + +#: ../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 +#, fuzzy +msgid "Package upload" +msgstr "Version du paquet" + +#: ../source/guides/hosting-your-own-index.rst:64 +msgid "PyPI fall-through [2]_" +msgstr "" + +#: ../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 "Notes supplémentaires" + +#: ../source/guides/hosting-your-own-index.rst:67 +#: ../source/guides/index-mirrors-and-caches.rst:58 +msgid ":ref:`devpi`" +msgstr "" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:5 +msgid "Package index mirrors and caches" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:8 +#, fuzzy +msgid "2023-11-08" +msgstr "2017-12-01" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "Installateurs Windows" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "Distributions SciPy" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "Spack" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +#, fuzzy +msgid "For example:" +msgstr "Exemples" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "26/07/2021" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "Fedora" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "CentOS / RHEL" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../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 "" + +#: ../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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "Arch Linux" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +msgid "Install packages in a virtual environment using pip and venv" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +#, fuzzy +msgid "Use and create a requirements file" +msgstr "Fichiers requirements vs install_requires" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:32 +#, fuzzy +msgid "Create and Use Virtual Environments" +msgstr "Environnement virtuel" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:35 +#, fuzzy +msgid "Create a new virtual environment" +msgstr "Environnement virtuel" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:37 +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." +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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +#, fuzzy +msgid "Activate a virtual environment" +msgstr "Environnement virtuel" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +#, fuzzy +msgid "Deactivate a virtual environment" +msgstr "Environnement virtuel" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +#, fuzzy +msgid "Reactivate a virtual environment" +msgstr "Environnement virtuel" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +#, fuzzy +msgid "Install packages using pip" +msgstr "Installez `pypinfo`_ à l'aide de pip." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +#, fuzzy +msgid "Install a package" +msgstr "Désinstaller des paquets" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +#, fuzzy +msgid "Install extras" +msgstr "Format d'installation" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "Mise à jour des paquets" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +#, fuzzy +msgid "Using a requirements file" +msgstr "Fichiers requirements vs install_requires" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +msgstr "Gel des dépendances" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:480 +msgid "" +"Pip can export a list of all installed packages and their versions using the " +"``freeze`` command:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 +msgid "Which will output a list of package specifiers such as:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +#, fuzzy +#| msgid "Examples" +msgid "Licensing Examples" +msgstr "Exemples" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +#, fuzzy +msgid "Basic example" +msgstr "Exemples" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +#, fuzzy +msgid "Advanced example" +msgstr "Exemples" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +#, fuzzy +msgid "Expression examples" +msgstr "Exemples" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "texte brut" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../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/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 "Obsolète" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:16 +#, fuzzy +msgid "Publishing releases" +msgstr "Publication des versions" + +#: ../source/guides/migrating-to-pypi-org.rst:18 +msgid "``pypi.org`` is the default upload platform as of September 2016." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "Utilisation de TestPyPI" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "Navigation dans les paquets" + +#: ../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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:134 +msgid "Downloading packages" +msgstr "Téléchargement de paquets" + +#: ../source/guides/migrating-to-pypi-org.rst:136 +msgid "``pypi.org`` is the default host for downloading packages." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +#, fuzzy +msgid "Should ``pyproject.toml`` be added?" +msgstr "pyproject.toml" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:36 +#, fuzzy +msgid "``python -m build``" +msgstr "Oui (``python -m pip uninstall``)" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +#, fuzzy +msgid ":ref:`distributing-packages`" +msgstr "Paqueter et distribuer des projets" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:126 +#, fuzzy +msgid "``python -m build --no-isolation``" +msgstr "Oui (``python -m pip uninstall``)" + +#: ../source/guides/modernize-setup-py-project.rst:127 +#, fuzzy +msgid "``python -m pip install --no-build-isolation``" +msgstr "Oui (``python -m pip uninstall``)" + +#: ../source/guides/modernize-setup-py-project.rst:135 +#, fuzzy +msgid "How to handle packaging metadata?" +msgstr "En utilisant les métadonnées du paquet" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +#, fuzzy +msgid ":ref:`pyproject-toml-spec`" +msgstr "pyproject.toml" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +#, fuzzy +msgid "Multi-version installs" +msgstr "Installations multi-versions" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "08/12/2013" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +#, fuzzy +msgid "Use cases" +msgstr "Cas d'utilisation" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "Désavantages" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +#, fuzzy +msgid "Extension module lifecycle" +msgstr "Module d'extension" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:374 +msgid "Weak linking" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:379 +msgid "Additional resources" +msgstr "Ressources supplémentaires" + +#: ../source/guides/packaging-binary-extensions.rst:381 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:25 +#, fuzzy +#| msgid "Configuring trusted publishing" +msgid "Configuring Trusted Publishing" +msgstr "Configuration de Trusted Publishing" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:27 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "Hébergement" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +#, fuzzy +msgid "Installation" +msgstr "Format d'installation" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "24/12/2014" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "03/12/2015" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +msgstr "Configuration" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "appveyor.yml" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "Script d'aide" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "``DISTUTILS_USE_SDK``" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "``MSSdk``" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "``INCLUDE``" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +msgstr "``LIB``" + +#: ../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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "Dépendances externes" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "Scripts d'aide" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../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 "Recommandations d'outils" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:20 +#, fuzzy +msgid "Virtual environments" +msgstr "Environnement virtuel" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +#, fuzzy +msgid "Installing packages" +msgstr "Désinstaller des paquets" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +#, fuzzy +msgid "Building distributions" +msgstr "Distribution compilée" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" +"Depuis novembre 2024, PyPI supporte les plateformes suivantes comme " +"fournisseurs Trusted Publishing :" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "GitLab CI/CD (sur ``https://gitlab.com``)" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +#, fuzzy +msgid "Writing your ``pyproject.toml``" +msgstr "pyproject.toml" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "``name``" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +#, fuzzy +msgid "Put the version of your project." +msgstr "Configurer votre projet" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +#, fuzzy +msgid "Dependencies and requirements" +msgstr "Fichiers requirements vs install_requires" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "``dependencies`` / ``optional-dependencies``" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "``requires-python``" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +#, fuzzy +msgid "About your project" +msgstr "Configurer votre projet" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "``authors`` / ``maintainers``" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "``description``" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "``readme``" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +#, fuzzy +#| msgid "``license``" +msgid "``license`` and ``license-files``" +msgstr "``license``" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +#, fuzzy +#| msgid "hatch" +msgid "hatchling" +msgstr "hatch" + +#: ../source/guides/writing-pyproject-toml.rst:313 +#, fuzzy +#| msgid "pip-tools" +msgid "setuptools" +msgstr "pip-tools" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +#, fuzzy +#| msgid "poetry" +msgid "poetry-core" +msgstr "poetry" + +#: ../source/guides/writing-pyproject-toml.rst:317 +#, fuzzy +#| msgid "build" +msgid "uv-build" +msgstr "build" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "``license``" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +#, fuzzy +#| msgid "``license``" +msgid "``license-files``" +msgstr "``license``" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "``keywords``" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "``classifiers``" + +#: ../source/guides/writing-pyproject-toml.rst:411 +#, fuzzy +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" +"Renseignez une liste de classifieurs qui catégorisent votre projet. Pour la " +"liste complète, consultez https://pypi.org/classifiers/." + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "``urls``" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +#, fuzzy +msgid "A full example" +msgstr "Exemples" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "Guide d'utilisation des paquets Python" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" + +#: ../source/index.rst:36 +#, fuzzy +msgid "Overview and Flow" +msgstr "Aperçu" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +#, fuzzy +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "Déployer des applications Python" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr ":doc:`discussions/pip-vs-easy-install`" + +#: ../source/index.rst:89 +#, fuzzy +msgid "Reference" +msgstr "Références" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "Résumé des projets" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "Projets PyPA" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "bandersnatch" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Documentation `__ | `Problèmes " +"`__ | `GitHub `__ | `PyPI `__" + +#: ../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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "build" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +":any:`Documentation ` | `Problèmes `__ | `GitHub `__ | `PyPI " +"`__" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "cibuildwheel" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" +"`Documentation `__ | `Problèmes " +"`__ | `GitHub `__ | `PyPI `__ | `Discussions `__ | `Discord #cibuildwheel `__" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "distlib" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +":doc:`Documentation ` | `Problèmes `__ | `GitHub `__ | `PyPI " +"`__" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +msgstr "distutils" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "flit" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" +"`Documentation `__ | `Problèmes " +"`__ | `PyPI `__" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "hatch" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Documentation `__ | `GitHub `__ | `PyPI `__" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "paquetage" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +":doc:`Documentation ` | `Problèmes `__ | `GitHub `__ | " +"`PyPI `__" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "pip" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Documentation `__ | `Problèmes `__ | `GitHub `__ | `PyPI " +"`__" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "Pipenv" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +msgstr "" +":doc:`Documentation ` | `Code source `__ | `Problèmes `__ | `PyPI " +"`__" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "Pipfile" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "`Code source `__" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "pipx" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" +"`Documentation `__ | `GitHub `__ | `PyPI `__" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" +":doc:`Documentation ` | `Problèmes `__ | `GitHub `__" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "Ce guide !" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "readme_renderer" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" +"`GitHub et documentation `__ | " +"`PyPI `__" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Documentation `__ | " +"`Problèmes `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "trove-classifiers" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" +"`Problèmes `__ | `GitHub " +"`__ | `PyPI `__" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "twine" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Documentation `__ | `Problèmes " +"`__ | `GitHub `__ | `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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "virtualenv" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Documentation `__ | " +"`Problèmes `__ | `GitHub `__ | `PyPI `__" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "Warehouse" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" +"`Documentation `__ | `Problèmes `__ | `GitHub `__" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "wheel" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Documentation `__ | `Problèmes " +"`__ | `GitHub `__ | `PyPI `__" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "Projets non-PyPA" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "buildout" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" +"`Documentation `__ | `Problèmes `__ | `PyPI `__ | `GitHub `__" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "conda" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "devpi" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" +"`GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "enscons" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "Hashdist" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" +"`Documentation `__ | `GitHub " +"`__" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "Maturin" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" +"`Documentation `__ | `GitHub `__" + +#: ../source/key_projects.rst:521 +#, fuzzy +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" +"Maturin est un backend de build pour des modules d'extension Rust, et il est " +"aussi écrit en Rust. Il peut créer des wheels pour python 3.7+ sur Windows, " +"Linux, macOS et FreeBSD, peut les téléverser sur PyPI et a un support PyPy " +"et GraalPy basique." + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "meson-python" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" +"`Documentation `__ | `GitHub " +"`__" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "multibuild" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "pdm" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Documentation `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Documentation `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "pip-tools" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Documentation `__ | `GitHub " +"`__ | `PyPI `__" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "piwheels" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" +"`Site web `__ | :doc:`Documentation " +"` | `GitHub `__" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "poetry" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Documentation `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +#, fuzzy +msgid "Pulp-python" +msgstr "python" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "pypiserver" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" +"`GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "PyScaffold" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Documentation `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "scikit-build" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Documentation `__ | `GitHub " +"`__ | `PyPI `__" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "scikit-build-core" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" +"`Documentation `__ | " +"`GitHub `__ | `PyPI " +"`__" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "shiv" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Documentation `__ | `GitHub " +"`__ | `PyPI `__" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" +":doc:`Documentation ` | `GitHub `__ | `Document `__ | `Diapositives `__" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "zest.releaser" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Documentation `__ | `GitHub " +"`__ | `PyPI `__" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "ensurepip" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "venv" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" +"`Documentation `__ | `Problèmes " +"`__" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "Actualités" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "Septembre 2019" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "Août 2019" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "Juillet 2019" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" +"Mise à jour de la version de Sphinx et suppression de pypa.io intersphinx. " +"(:pr: `625`)" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "Juin 2019" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "Mai 2019" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "Avril 2019" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "Mars 2019" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "Février 2019" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" +"Ajout des instructions pour installer des applications Python CLI. " +"(:pr:`594`)" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "Janvier 2019" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "Décembre 2018" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "Novembre 2018" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "Octobre 2018" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "Septembre 2018" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "Ajout d'une section sur la vérification du balisage RST. (:pr:`554`)" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "Août 2018" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "Juillet 2018" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "Juin 2018" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "Correction des catégories du PEP interop pour pypa.io. (:pr:`527`)" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "Mai 2018" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +#, fuzzy +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" +"Mise à jour de la description de la section licence pour être complet. " +"(:pr:`492`)" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "Avril 2018" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" +"Mise à jour des instructions et de l'état pour le lancement de PyPI. " +"(:pr:`475`)" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "Mars 2018" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" +"Clarification d'un long classifier de version sur pypi.org. (:pr:`456`)" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "Février 2018" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "Janvier 2018" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "Décembre 2017" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "Novembre 2017" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "Octobre 2017" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "Septembre 2017" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "Août 2017" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "Juillet 2017" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "Juin 2017" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "Mai 2017" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "Avril 2017" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "Mars 2017" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "Février 2017" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "Modules Python" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "Plateformes de service" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +msgid "`Kivy `_" +msgstr "" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "Sécurité" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "Détails" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:29 +msgid "Unpack." +msgstr "Dépaqueter." + +#: ../source/specifications/binary-distribution-format.rst:31 +msgid "Parse ``distribution-1.0.dist-info/WHEEL``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +#, fuzzy +msgid "Spread." +msgstr "Répandre." + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "distribution" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +#, fuzzy +#| msgid "Project name" +msgid "Subdirectory name" +msgstr "Nom du projet" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#, fuzzy +#| msgid "``license``" +msgid "``licenses``" +msgstr "``license``" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +#, fuzzy +#| msgid "``license``" +msgid "``license_files``" +msgstr "``license``" + +#: ../source/specifications/binary-distribution-format.rst:266 +#, fuzzy +#| msgid "``LIB``" +msgid "``LICENSES``" +msgstr "``LIB``" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "Foire aux questions" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "Historique" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +#, fuzzy +#| msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" +"Mars 2001 : Les métadonnées de base 1.0 ont été approuvées grâce " +"au :pep:`241`." + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "Annexe" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "Exemple" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "Spécification" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +#, fuzzy +#| msgid "JSON Schema" +msgid "Schema" +msgstr "Schéma JSON" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Project" +msgid "*object*" +msgstr "Projet" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Package version" +msgid "Schema version." +msgstr "Version du paquet" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "enscons" +msgid "const" +msgstr "enscons" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Examples" +msgid "examples" +msgstr "Exemples" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "python" +msgid "bin/python" +msgstr "python" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Service platforms" +msgid "System platform string." +msgstr "Plateformes de service" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "linux_x86_64" +msgid "linux-x86\\_64" +msgstr "linux_x86_64" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Versions" +msgid "**version**" +msgstr "Versions" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +msgid "version\\_info" +msgstr "Traductions" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Release" +msgid "releaselevel" +msgstr "Version" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Mercurial" +msgid "serial" +msgstr "Mercurial" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "**Numbers**" +msgid "*number*" +msgstr "**Nombres**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Additional notes" +msgid "additionalProperties" +msgstr "Notes supplémentaires" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +msgid "**implementation**" +msgstr "Types de documentation" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "python" +msgid "cpython" +msgstr "python" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "**Headings**" +msgid "**flags**" +msgstr "**Titres**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Versions" +msgid "extensions" +msgstr "Versions" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "python" +msgid "libpython" +msgstr "python" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "``dynamic``" +msgid "dynamic" +msgstr "``dynamic``" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "**Numbers**" +msgid "**headers**" +msgstr "**Nombres**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "``Name``" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "Metadata-Version" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "Exemple ::" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "Exemples::" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "Description-Content-Type" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "Format ::" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "``text/plain``" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "``text/x-rst``" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "``text/markdown``" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "Mots-clés" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "Author" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" +"Une chaîne contenant le nom de l'auteur au minimum ; des informations de " +"contact supplémentaires peuvent être fournies." + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "Author-email" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" +"Une chaîne contenant l'adresse mail de l'auteur. Elle peut contenir un nom " +"et une adresse mail dans les formes légales pour un en-tête ``From:`` " +"RFC-822." + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" +"Selon la RFC-822, ce champ peut contenir plusieurs adresses mails séparées " +"par une virgule ::" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "Maintainer" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "Maintainer-email" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "License" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "Home-page" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "Download-URL" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "Requires" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "Provides" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "Obsoletes" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" +"Mars 2001 : Les métadonnées de base 1.0 ont été approuvées grâce " +"au :pep:`241`." + +#: ../source/specifications/core-metadata.rst:1039 +#, fuzzy +#| msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" +"Mars 2001 : Les métadonnées de base 1.0 ont été approuvées grâce " +"au :pep:`241`." + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "Restreint les noms supplémentaires à être normalisés." + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +#, fuzzy +#| msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" +"Mars 2001 : Les métadonnées de base 1.0 ont été approuvées grâce " +"au :pep:`241`." + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +#, fuzzy +msgid "Package Building" +msgstr "Version du paquet" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +#, fuzzy +msgid "Installing Dependency Groups & Extras" +msgstr "Format d'installation" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +#, fuzzy +msgid "Reference Implementation" +msgstr "Types de documentation" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +#, fuzzy +#| msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" +"Mars 2001 : Les métadonnées de base 1.0 ont été approuvées grâce " +"au :pep:`241`." + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "Concepts" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "Grammaire" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "Espace blanc" + +#: ../source/specifications/dependency-specifiers.rst:128 +msgid "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "Noms" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "Extras" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "Versions" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "Marqueur" + +#: ../source/specifications/dependency-specifiers.rst:248 +#, fuzzy +msgid "Python equivalent" +msgstr "Version de Python" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "``os_name``" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "``sys_platform``" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "``platform_machine``" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "``x86_64``" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "``platform_python_implementation``" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "``platform_release``" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "``platform_system``" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "``platform_version``" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "``python_version``" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "``'.'.join(platform.python_version_tuple()[:2])``" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +msgid ":ref:`Version `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "``python_full_version``" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "``implementation_name``" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "``cpython``" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "``implementation_version``" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "``extra``" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +#, fuzzy +msgid "``toml``" +msgstr "pyproject.toml" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +#, fuzzy +#| msgid "``extra``" +msgid "``extras``" +msgstr "``extra``" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +#, fuzzy +#| msgid "``dependencies``" +msgid "``dependency_groups``" +msgstr "``dependencies``" + +#: ../source/specifications/dependency-specifiers.rst:312 +#, fuzzy +#| msgid "``test``" +msgid "``{\"test\"}``" +msgstr "``test``" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "Git" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "https://git-scm.com/" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "git" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "Mercurial" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "https://www.mercurial-scm.org/" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "hg" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "Bazaar" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "https://www.breezy-vcs.org/" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "bzr" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "svn" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "Schéma JSON" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +#, fuzzy +msgid "Externally Managed Environments" +msgstr "Environnement virtuel" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +#, fuzzy +msgid "package" +msgstr "``packages``" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +#, fuzzy +msgid "Guide users towards virtual environments" +msgstr "Environnement virtuel" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +#, fuzzy +msgid "Implementation Notes" +msgstr "Types de documentation" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "``pip install``" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +#, fuzzy +msgid "``pip install --user``" +msgstr "Oui (``python -m pip uninstall``)" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "Copyright" + +#: ../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/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +#, fuzzy +msgid "This specification was originally defined in :pep:`592`." +msgstr "Cette spécification a été originellement définie dans la :pep: `740`." + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +#, fuzzy +msgid "Installers" +msgstr "Installateur" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +#, fuzzy +msgid "Reference implementation in Python" +msgstr "Types de documentation" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +#, fuzzy +msgid "This specification was originally defined in :pep:`740`." +msgstr "Cette spécification a été originellement définie dans la :pep: `740`." + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "Objets de provenance" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" +"``attestation_bundles`` est un tableau JSON **obligatoire**, contenant un ou " +"plusieurs \"bundles\" d'attestations. Chaque bundle correspond à une " +"identité de signature (comme une identité Trusted Publishing) et contient un " +"ou plusieurs objets d'attestations." + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +#, fuzzy +msgid "Changes to provenance objects" +msgstr "Changements aux objets de provenance" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +#, fuzzy +msgid "Names and normalization" +msgstr "Version du paquet" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +#, fuzzy +msgid "Name normalization" +msgstr "Traductions" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../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 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +#, fuzzy +msgid "python tag" +msgstr "python" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +#, fuzzy +msgid "Python Tag" +msgstr "python" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +#, fuzzy +msgid "cp: CPython" +msgstr "python" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +#, fuzzy +msgid "ip: IronPython" +msgstr "python" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +#, fuzzy +msgid "jy: Jython" +msgstr "python" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "win32" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "linux_i386" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "linux_x86_64" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "``manylinux``" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "Outil" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "``manylinux1``" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "``manylinux2010``" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "``manylinux2014``" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "``manylinux_x_y``" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "``>=8.1.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "``>=19.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "``>=19.3``" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "``>=20.3``" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "auditwheel" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "``>=1.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "``>=2.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "``>=3.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +#, fuzzy +#| msgid "" +#| "The value of ``x`` and ``y`` correspond to the major and minor version " +#| "number of the iOS release, respectively. They must both be positive " +#| "integers. The version number always includes a major *and* minor version, " +#| "even if Apple's official version numbering only refers to the major " +#| "value. For example, a ``ios_13_0_arm64_iphonesimulator`` indicates " +#| "compatibility with iOS 13 or later." +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" +"Les valeurs de ``x`` et ``y`` correspondent respectivement au numéro de " +"version majeur et mineur de la version iOS. Elles doivent toutes deux être " +"des entiers positifs. Le numéro de version comprend toujours une version " +"majeure *et* mineure, même si la numérotation officielle des versions " +"d'Apple ne fait référence qu'à la valeur majeure. Par exemple, " +"``ios_13_0_arm64_iphonesimulator`` indique la compatibilité avec iOS 13 ou " +"une version ultérieure." + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "``arm64``, ``x86_64``" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "``universal``" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "``intel``" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "``i386``, ``x86_64``" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "``fat64``" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "``ppc64``, ``x86_64``" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" +"La version minimale prise en charge de macOS peut également être limitée par " +"l'architecture. Par exemple, macOS 11 (Big Sur) a été la première version à " +"prendre en charge arm64. Ces contraintes supplémentaires sont appliquées de " +"manière transparente par les outils de compilation macOS lors de la création " +"de binaires prenant en charge des architectures multiples." + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "Android" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" +"Android utilise le schéma :file:`android_{apilevel}_{abi}`, indiquant la " +"compatibilité avec le niveau d'API Android donné ou supérieur, sur l'ABI " +"donné. Par exemple, ``android_27_arm64_v8a`` indique la prise en charge du " +"niveau d'API 27 ou supérieur, sur les appareils ``arm64_v8a``. Android ne " +"fait aucune distinction entre les appareils physiques et les appareils " +"émulés." + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" +"Le niveau d'API doit être un entier positif. Ce n'est *pas* la même chose " +"que la version Android destinée aux utilisateurs. Par exemple, la version " +"connue sous le nom d'Android 12 (nom de code « Snow Cone ») utilise le " +"niveau d'API 31 ou 32, selon la version Android spécifique utilisée. La " +"documentation de la version d'Android contient la `liste complète des " +"versions d'Android et de leurs niveaux d'API correspondants `__." + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" +"Il existe 4 `ABI pris en charge `__. Normalisés selon les règles ci-dessus, ils sont :" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "``x86``" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" +"Pratiquement tous les appareils physiques actuels utilisent l'une des " +"architectures ARM. ``x86`` et ``x86_64`` sont pris en charge pour une " +"utilisation dans l'émulateur. ``x86`` n'est plus pris en charge en tant que " +"plateforme de développement depuis 2020, et aucune nouvelle image " +"d'émulateur n'a été publiée depuis." + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "iOS" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" +"iOS utilise le schéma :file:`ios_{x}_{y}_{arch}_{sdk}`, indiquant la " +"compatibilité avec iOS ``x.y`` ou version ultérieure, sur l'architecture " +"``arch``, en utilisant le SDK ``sdk``." + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" +"Les valeurs de ``x`` et ``y`` correspondent respectivement au numéro de " +"version majeur et mineur de la version iOS. Elles doivent toutes deux être " +"des entiers positifs. Le numéro de version comprend toujours une version " +"majeure *et* mineure, même si la numérotation officielle des versions " +"d'Apple ne fait référence qu'à la valeur majeure. Par exemple, " +"``ios_13_0_arm64_iphonesimulator`` indique la compatibilité avec iOS 13 ou " +"une version ultérieure." + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" +"La valeur de ``arch`` doit correspondre à la valeur " +"de :py:func:`platform.machine()` sur le système." + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +#, fuzzy +msgid "Use" +msgstr "Usage :" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "cp33-cp33m-linux_x86_64" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "cp33-abi3-linux_x86_64" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "cp3-abi3-linux_x86_64" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "cp33-none-linux_x86_64*" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "cp3-none-linux_x86_64*" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "py33-none-linux_x86_64*" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "py3-none-linux_x86_64*" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "cp33-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "cp3-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "py33-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "py3-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "py32-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "py31-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "py30-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +#, fuzzy +#| msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" +"Mars 2001 : Les métadonnées de base 1.0 ont été approuvées grâce " +"au :pep:`241`." + +#: ../source/specifications/platform-compatibility-tags.rst:451 +#, fuzzy +#| msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" +"Mars 2001 : Les métadonnées de base 1.0 ont été approuvées grâce " +"au :pep:`241`." + +#: ../source/specifications/project-status-markers.rst:5 +#, fuzzy +#| msgid "Project Summaries" +msgid "Project Status Markers" +msgstr "Résumé des projets" + +#: ../source/specifications/project-status-markers.rst:9 +#, fuzzy +msgid "This specification was originally defined in :pep:`792`." +msgstr "Cette spécification a été originellement définie dans la :pep: `740`." + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +#, fuzzy +msgid "Installer semantics: none." +msgstr "Format d'installation" + +#: ../source/specifications/project-status-markers.rst:45 +#, fuzzy +#| msgid "``packages``" +msgid "``archived``" +msgstr "``packages``" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +#, fuzzy +msgid "Installer semantics:" +msgstr "Installateur" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +#, fuzzy +#| msgid "Deprecated" +msgid "``deprecated``" +msgstr "Obsolète" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +#, fuzzy +msgid "``pylock.toml`` Specification" +msgstr "pyproject.toml" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +#, fuzzy +msgid "This specification was originally defined in :pep:`751`." +msgstr "Cette spécification a été originellement définie dans la :pep: `740`." + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +#, fuzzy +#| msgid "``platform_version``" +msgid "``lock-version``" +msgstr "``platform_version``" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +#, fuzzy +#| msgid "Requires" +msgid "**Required?**: yes" +msgstr "Requires" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +#, fuzzy +#| msgid "``entry-points``" +msgid "``environments``" +msgstr "``entry-points``" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +#, fuzzy +#| msgid "``dependencies``" +msgid "``dependency-groups``" +msgstr "``dependencies``" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +#, fuzzy +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "pyproject.toml" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +#, fuzzy +#| msgid "``packages``" +msgid "``[[packages]]``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.name``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.version``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +#, fuzzy +msgid "The version of the package." +msgstr "Désinstaller des paquets" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.marker``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +#, fuzzy +#| msgid "``requires-python``" +msgid "``packages.requires-python``" +msgstr "``requires-python``" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +#, fuzzy +#| msgid "``dependencies``" +msgid "``[[packages.dependencies]]``" +msgstr "``dependencies``" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +#, fuzzy +#| msgid "``packages``" +msgid "``[packages.vcs]``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.vcs.type``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:306 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.vcs.url``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.vcs.path``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.vcs.commit-id``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +#, fuzzy +#| msgid "``packages``" +msgid "``[packages.directory]``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +#, fuzzy +#| msgid "``package_data``" +msgid "``packages.directory.path``" +msgstr "``package_data``" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +#, fuzzy +#| msgid "``packages``" +msgid "``[packages.archive]``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.archive.url``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.archive.path``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.archive.size``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +#, fuzzy +#| msgid "Where the guide is deployed" +msgid "The time the file was uploaded." +msgstr "Où le guide est-il déployé ?" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.index``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +#, fuzzy +#| msgid "``packages``" +msgid "``[packages.sdist]``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +#, fuzzy +#| msgid "``package_data``" +msgid "``packages.sdist.name``" +msgstr "``package_data``" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +#, fuzzy +#| msgid "``package_data``" +msgid "``packages.sdist.upload-time``" +msgstr "``package_data``" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.sdist.url``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +#, fuzzy +#| msgid "``package_data``" +msgid "``packages.sdist.path``" +msgstr "``package_data``" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.sdist.size``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +#, fuzzy +#| msgid "``package_data``" +msgid "``packages.sdist.hashes``" +msgstr "``package_data``" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +#, fuzzy +#| msgid "``packages``" +msgid "``[[packages.wheels]]``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.wheels.name``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.wheels.url``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:647 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.wheels.path``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:655 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.wheels.size``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:663 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.wheels.hashes``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +#, fuzzy +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "pyproject.toml" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +#, fuzzy +#| msgid "``packages``" +msgid "``[packages.tool]``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +#, fuzzy +msgid "``pyproject.toml`` specification" +msgstr "pyproject.toml" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "Déclarer les métadonnées d'un projet : la table ``[project]``" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" +"La table ``[project]`` spécifie les :ref:`métadonnées de base ` du projet." + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" +"La liste complète des clés autorisées dans la table ``[project]`` est :" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "``authors``" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "``dependencies``" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "``dynamic``" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "``entry-points``" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "``gui-scripts``" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +#, fuzzy +#| msgid "``name``" +msgid "``import-names``" +msgstr "``name``" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "``maintainers``" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "``optional-dependencies``" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +#, fuzzy +#| msgid "Specification" +msgid "Legacy specification" +msgstr "Spécification" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +#, fuzzy +msgid "Examples:" +msgstr "Exemples" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +#, fuzzy +#| msgid "Example::" +msgid "Example:" +msgstr "Exemple ::" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "Configuration arbitraire d'outils : la table ``[tool]``" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +#, fuzzy +#| msgid "Data schema" +msgid "PyPA schemas" +msgstr "Schéma de données" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 "Format d'installation" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +#, fuzzy +#| msgid "Python versions over time" +msgid "Python Description Formats" +msgstr "Versions de Python au cours du temps" + +#: ../source/specifications/section-reproducible-environments.rst:3 +#, fuzzy +#| msgid "Virtual Environment" +msgid "Reproducible Environments" +msgstr "Environnement virtuel" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +#, fuzzy +msgid "Normalized Names" +msgstr "Traductions" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +#, fuzzy +#| msgid "This would end up looking like::" +msgid "This would end up looking like:" +msgstr "Cela ressemblerait à ::" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +#, fuzzy +msgid "Clients" +msgstr "Contenu" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +#, fuzzy +msgid "HTML Serialization" +msgstr "Traductions" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +#, fuzzy +msgid "Project List" +msgstr "Projet" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +#, fuzzy +msgid "Project Detail" +msgstr "Nom du projet" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +#, fuzzy +msgid "JSON Serialization" +msgstr "Traductions" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +#, fuzzy +msgid "As an example:" +msgstr "Exemples" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +#, fuzzy +msgid "Content-Types" +msgstr "Contenu" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +#, fuzzy +msgid "Version + Format Selection" +msgstr "Traductions" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +#, fuzzy +#| msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" +"Mars 2001 : Les métadonnées de base 1.0 ont été approuvées grâce " +"au :pep:`241`." + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +#, fuzzy +msgid "Definitions" +msgstr "Spécifications" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +#, fuzzy +msgid "Version scheme" +msgstr "Traductions" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +#, fuzzy +msgid "Pre-releases" +msgstr "Version" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +#, fuzzy +msgid "Post-releases" +msgstr "Version" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +#, fuzzy +msgid "Version epochs" +msgstr "Traductions" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +#, fuzzy +msgid "Normalization" +msgstr "Traductions" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +#, fuzzy +msgid "Integer Normalization" +msgstr "Traductions" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +#, fuzzy +msgid "Version exclusion" +msgstr "Traductions" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +#, fuzzy +msgid "Remote URL examples::" +msgstr "Exemples" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +#, fuzzy +msgid "Python Virtual Environments" +msgstr "Environnement virtuel" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +#, fuzzy +msgid "Well-known Project URLs in Metadata" +msgstr "Nom du projet" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +#, fuzzy +msgid "Label normalization" +msgstr "Traductions" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +#, fuzzy +msgid "Normalized" +msgstr "Traductions" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +#, fuzzy +msgid "Funding Information" +msgstr "Outils supplémentaires" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +#, fuzzy +msgid "Example behavior" +msgstr "Exemples" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"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/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "" + +#: ../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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "" + +#: ../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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +#, fuzzy +msgid "Installing \"Extras\"" +msgstr "Format d'installation" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" + +#~ msgid "See" +#~ msgstr "Voir" + +#~ msgid "https://datatracker.ietf.org/doc/html/rfc7515" +#~ msgstr "https://datatracker.ietf.org/doc/html/rfc7515" + +#~ msgid "" +#~ "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" +#~ "serialization-01" +#~ msgstr "" +#~ "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" +#~ "serialization-01" + +#~ msgid "https://datatracker.ietf.org/doc/html/rfc7517" +#~ msgstr "https://datatracker.ietf.org/doc/html/rfc7517" + +#~ msgid "" +#~ "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" +#~ msgstr "" +#~ "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" + +#, fuzzy +#~ msgid "**Inspiration**: :ref:` pyproject-tool-table`" +#~ msgstr "pyproject.toml" + +#, fuzzy +#~ msgid "Signing the distribution packages" +#~ msgstr "Paqueter et distribuer des projets" + +#, fuzzy +#~ msgid "Additional file information" +#~ msgstr "Outils supplémentaires" + +#~ msgid "Wheel vs Egg" +#~ msgstr "Wheel vs Egg" + +#~ msgid "Give a short and long description for your project." +#~ msgstr "Renseignez une description courte et longue pour votre projet." + +#~ msgid "Give a homepage URL for your project." +#~ msgstr "Renseignez une URL pour la page d'accueil de votre projet." + +#~ msgid "Provide details about the author." +#~ msgstr "Renseignez des informations sur l'auteur." + +#~ msgid "" +#~ "Provide a list of classifiers that categorize your project. For a full " +#~ "listing, see https://pypi.org/classifiers/." +#~ msgstr "" +#~ "Renseignez une liste de classifieurs qui catégorisent votre projet. Pour " +#~ "la liste complète, consultez https://pypi.org/classifiers/." + +#~ msgid "List keywords that describe your project." +#~ msgstr "Listez les mots-clés qui décrivent votre projet." + +#~ msgid "And so on." +#~ msgstr "Et ainsi de suite." + +#~ msgid "" +#~ "It may also be known that project A follows semantic versioning, and that " +#~ "v2 of 'A' will indicate a break in compatibility, so it makes sense to " +#~ "not allow v2:" +#~ msgstr "" +#~ "On peut également savoir que le projet A respecte le système de version " +#~ "sémantique, et que la v2 de « A » indique une rupture de compatibilité, " +#~ "il est donc logique de ne pas autoriser la version 2 :" + +#~ msgid "2014-11-11" +#~ msgstr "2014-11-11" diff --git a/locales/frc/LC_MESSAGES/messages.po b/locales/frc/LC_MESSAGES/messages.po new file mode 100644 index 000000000..c78eb9324 --- /dev/null +++ b/locales/frc/LC_MESSAGES/messages.po @@ -0,0 +1,26789 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# Monzer Ghannam , 2022. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: Automatically generated\n" +"Language-Team: none\n" +"Language: frc\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "" + +#: ../source/contribute.rst:14 +msgid "Translating the guide" +msgstr "" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "" + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "" + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "" + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "" + +#: ../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 +msgid "What is a source distribution?" +msgstr "" + +#: ../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 +msgid "What about eggs?" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python setup.py install``" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python -m pip install --editable .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:104 +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr "" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +msgid "Complete" +msgstr "" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +msgid "Versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +msgid "Calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +msgid "Other schemes" +msgstr "" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 ../source/flow.rst:143 +msgid "" +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../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 :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +msgid "Installed Project" +msgstr "" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +msgid "Project Root Directory" +msgstr "" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "" + +#: ../source/glossary.rst:257 +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:260 +msgid "Pyproject Metadata" +msgstr "" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +msgid "Pyproject Metadata Key" +msgstr "" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "" + +#: ../source/glossary.rst:344 +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:348 +msgid "Root License Directory" +msgstr "" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +msgid "Wheel Project" +msgstr "" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "" +"https://files.pythonhosted.org/packages/eb/" +"45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" +"sampleproject-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "" +"https://files.pythonhosted.org/packages/56/0a/" +"178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" +"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +msgid "" +"https://files.pythonhosted.org/packages/" +"63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" +"sampleproject_nomura-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +msgid "Creating the package" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +msgid "``pyproject.toml``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +msgid "Installing the package with ``pipx``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +msgid "Conclusion" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +msgid "1. Install twine" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +msgid "Dropping a Python version" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:108 +msgid "openSUSE" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:118 +msgid "Debian/Ubuntu and derivatives" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +msgid "Install packages in a virtual environment using pip and venv" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +msgid "Install packages using pip" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +msgid "Install extras" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +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/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python -m build``" +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:126 +msgid "``python -m build --no-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:127 +msgid "``python -m pip install --no-build-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../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 "" +"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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +msgid "Installation" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:233 +msgid "``appveyor-sample/build.cmd``" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:5 +msgid "Tool recommendations" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +msgid "Installing packages" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +msgid "Building distributions" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:313 +msgid "setuptools" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:317 +msgid "uv-build" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +msgid "`Kivy `_" +msgstr "" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "Subdirectory name" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +msgid "``licenses``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*object*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Schema version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "examples" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "version\\_info" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*number*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**implementation**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**flags**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**headers**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +msgid "Package Building" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +msgid ":ref:`Version `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +msgid "``toml``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +msgid "``dependency_groups``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +msgid "Installers" +msgstr "" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +msgid "Reference implementation in Python" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +msgid "Names and normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +msgid "Name normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +msgid "Project Status Markers" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +msgid "Installer semantics: none." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +msgid "Installer semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +msgid "``deprecated``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +msgid "``pylock.toml`` Specification" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +msgid "``lock-version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +msgid "**Required?**: yes" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +msgid "``environments``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +msgid "``dependency-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +msgid "``[[packages]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +msgid "``packages.version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +msgid "The version of the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +msgid "``[[packages.dependencies]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +msgid "The time the file was uploaded." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +msgid "``packages.index``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +msgid "``import-names``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +msgid "Legacy specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +msgid "Examples:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +msgid "Example:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +msgid "PyPA schemas" +msgstr "" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +msgid "Python Description Formats" +msgstr "" + +#: ../source/specifications/section-reproducible-environments.rst:3 +msgid "Reproducible Environments" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +msgid "Normalized Names" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +msgid "HTML Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +msgid "Project List" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +msgid "Project Detail" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +msgid "JSON Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +msgid "Content-Types" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +msgid "Version + Format Selection" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +msgid "Definitions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +msgid "Version scheme" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +msgid "Pre-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +msgid "Version epochs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +msgid "Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +msgid "Integer Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +msgid "Version exclusion" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +msgid "Well-known Project URLs in Metadata" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +msgid "Label normalization" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +msgid "Normalized" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"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/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "" + +#: ../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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "" + +#: ../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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" diff --git a/locales/gl/LC_MESSAGES/messages.po b/locales/gl/LC_MESSAGES/messages.po new file mode 100644 index 000000000..d8e81abc8 --- /dev/null +++ b/locales/gl/LC_MESSAGES/messages.po @@ -0,0 +1,26789 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# Nuno André , 2022. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: Automatically generated\n" +"Language-Team: none\n" +"Language: gl\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "" + +#: ../source/contribute.rst:14 +msgid "Translating the guide" +msgstr "" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "" + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "" + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "" + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "" + +#: ../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 +msgid "What is a source distribution?" +msgstr "" + +#: ../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 +msgid "What about eggs?" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python setup.py install``" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python -m pip install --editable .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:104 +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr "" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +msgid "Complete" +msgstr "" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +msgid "Versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +msgid "Calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +msgid "Other schemes" +msgstr "" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 ../source/flow.rst:143 +msgid "" +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../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 :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +msgid "Installed Project" +msgstr "" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +msgid "Project Root Directory" +msgstr "" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "" + +#: ../source/glossary.rst:257 +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:260 +msgid "Pyproject Metadata" +msgstr "" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +msgid "Pyproject Metadata Key" +msgstr "" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "" + +#: ../source/glossary.rst:344 +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:348 +msgid "Root License Directory" +msgstr "" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +msgid "Wheel Project" +msgstr "" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "" +"https://files.pythonhosted.org/packages/eb/" +"45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" +"sampleproject-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "" +"https://files.pythonhosted.org/packages/56/0a/" +"178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" +"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +msgid "" +"https://files.pythonhosted.org/packages/" +"63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" +"sampleproject_nomura-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +msgid "Creating the package" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +msgid "``pyproject.toml``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +msgid "Installing the package with ``pipx``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +msgid "Conclusion" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +msgid "1. Install twine" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +msgid "Dropping a Python version" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:108 +msgid "openSUSE" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:118 +msgid "Debian/Ubuntu and derivatives" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +msgid "Install packages in a virtual environment using pip and venv" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +msgid "Install packages using pip" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +msgid "Install extras" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +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/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python -m build``" +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:126 +msgid "``python -m build --no-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:127 +msgid "``python -m pip install --no-build-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../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 "" +"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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +msgid "Installation" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:233 +msgid "``appveyor-sample/build.cmd``" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:5 +msgid "Tool recommendations" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +msgid "Installing packages" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +msgid "Building distributions" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:313 +msgid "setuptools" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:317 +msgid "uv-build" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +msgid "`Kivy `_" +msgstr "" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "Subdirectory name" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +msgid "``licenses``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*object*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Schema version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "examples" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "version\\_info" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*number*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**implementation**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**flags**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**headers**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +msgid "Package Building" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +msgid ":ref:`Version `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +msgid "``toml``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +msgid "``dependency_groups``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +msgid "Installers" +msgstr "" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +msgid "Reference implementation in Python" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +msgid "Names and normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +msgid "Name normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +msgid "Project Status Markers" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +msgid "Installer semantics: none." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +msgid "Installer semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +msgid "``deprecated``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +msgid "``pylock.toml`` Specification" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +msgid "``lock-version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +msgid "**Required?**: yes" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +msgid "``environments``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +msgid "``dependency-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +msgid "``[[packages]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +msgid "``packages.version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +msgid "The version of the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +msgid "``[[packages.dependencies]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +msgid "The time the file was uploaded." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +msgid "``packages.index``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +msgid "``import-names``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +msgid "Legacy specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +msgid "Examples:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +msgid "Example:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +msgid "PyPA schemas" +msgstr "" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +msgid "Python Description Formats" +msgstr "" + +#: ../source/specifications/section-reproducible-environments.rst:3 +msgid "Reproducible Environments" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +msgid "Normalized Names" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +msgid "HTML Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +msgid "Project List" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +msgid "Project Detail" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +msgid "JSON Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +msgid "Content-Types" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +msgid "Version + Format Selection" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +msgid "Definitions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +msgid "Version scheme" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +msgid "Pre-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +msgid "Version epochs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +msgid "Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +msgid "Integer Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +msgid "Version exclusion" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +msgid "Well-known Project URLs in Metadata" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +msgid "Label normalization" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +msgid "Normalized" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"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/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "" + +#: ../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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "" + +#: ../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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" diff --git a/locales/gmh/LC_MESSAGES/messages.po b/locales/gmh/LC_MESSAGES/messages.po new file mode 100644 index 000000000..f65e599ab --- /dev/null +++ b/locales/gmh/LC_MESSAGES/messages.po @@ -0,0 +1,26789 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# Emr , 2024. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: Automatically generated\n" +"Language-Team: none\n" +"Language: gmh\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "" + +#: ../source/contribute.rst:14 +msgid "Translating the guide" +msgstr "" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "" + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "" + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "" + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "" + +#: ../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 +msgid "What is a source distribution?" +msgstr "" + +#: ../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 +msgid "What about eggs?" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python setup.py install``" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python -m pip install --editable .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:104 +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr "" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +msgid "Complete" +msgstr "" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +msgid "Versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +msgid "Calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +msgid "Other schemes" +msgstr "" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 ../source/flow.rst:143 +msgid "" +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../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 :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +msgid "Installed Project" +msgstr "" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +msgid "Project Root Directory" +msgstr "" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "" + +#: ../source/glossary.rst:257 +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:260 +msgid "Pyproject Metadata" +msgstr "" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +msgid "Pyproject Metadata Key" +msgstr "" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "" + +#: ../source/glossary.rst:344 +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:348 +msgid "Root License Directory" +msgstr "" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +msgid "Wheel Project" +msgstr "" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "" +"https://files.pythonhosted.org/packages/eb/" +"45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" +"sampleproject-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "" +"https://files.pythonhosted.org/packages/56/0a/" +"178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" +"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +msgid "" +"https://files.pythonhosted.org/packages/" +"63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" +"sampleproject_nomura-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +msgid "Creating the package" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +msgid "``pyproject.toml``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +msgid "Installing the package with ``pipx``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +msgid "Conclusion" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +msgid "1. Install twine" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +msgid "Dropping a Python version" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:108 +msgid "openSUSE" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:118 +msgid "Debian/Ubuntu and derivatives" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +msgid "Install packages in a virtual environment using pip and venv" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +msgid "Install packages using pip" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +msgid "Install extras" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +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/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python -m build``" +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:126 +msgid "``python -m build --no-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:127 +msgid "``python -m pip install --no-build-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../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 "" +"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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +msgid "Installation" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:233 +msgid "``appveyor-sample/build.cmd``" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:5 +msgid "Tool recommendations" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +msgid "Installing packages" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +msgid "Building distributions" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:313 +msgid "setuptools" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:317 +msgid "uv-build" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +msgid "`Kivy `_" +msgstr "" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "Subdirectory name" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +msgid "``licenses``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*object*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Schema version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "examples" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "version\\_info" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*number*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**implementation**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**flags**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**headers**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +msgid "Package Building" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +msgid ":ref:`Version `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +msgid "``toml``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +msgid "``dependency_groups``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +msgid "Installers" +msgstr "" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +msgid "Reference implementation in Python" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +msgid "Names and normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +msgid "Name normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +msgid "Project Status Markers" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +msgid "Installer semantics: none." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +msgid "Installer semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +msgid "``deprecated``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +msgid "``pylock.toml`` Specification" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +msgid "``lock-version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +msgid "**Required?**: yes" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +msgid "``environments``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +msgid "``dependency-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +msgid "``[[packages]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +msgid "``packages.version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +msgid "The version of the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +msgid "``[[packages.dependencies]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +msgid "The time the file was uploaded." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +msgid "``packages.index``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +msgid "``import-names``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +msgid "Legacy specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +msgid "Examples:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +msgid "Example:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +msgid "PyPA schemas" +msgstr "" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +msgid "Python Description Formats" +msgstr "" + +#: ../source/specifications/section-reproducible-environments.rst:3 +msgid "Reproducible Environments" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +msgid "Normalized Names" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +msgid "HTML Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +msgid "Project List" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +msgid "Project Detail" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +msgid "JSON Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +msgid "Content-Types" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +msgid "Version + Format Selection" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +msgid "Definitions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +msgid "Version scheme" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +msgid "Pre-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +msgid "Version epochs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +msgid "Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +msgid "Integer Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +msgid "Version exclusion" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +msgid "Well-known Project URLs in Metadata" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +msgid "Label normalization" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +msgid "Normalized" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"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/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "" + +#: ../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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "" + +#: ../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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" diff --git a/locales/hi/LC_MESSAGES/messages.po b/locales/hi/LC_MESSAGES/messages.po new file mode 100644 index 000000000..3ef5f19e7 --- /dev/null +++ b/locales/hi/LC_MESSAGES/messages.po @@ -0,0 +1,26885 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# Aryan 'Ba3a' Kumar , 2022. +# kumar Shivam , 2024. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: 2024-09-16 10:09+0000\n" +"Last-Translator: kumar Shivam \n" +"Language-Team: Hindi \n" +"Language: hi\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=2; plural=n > 1;\n" +"X-Generator: Weblate 5.8-dev\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "इस गाइड में योगदान करें" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "|पाइपयूजी| योगदानकर्ताओं का स्वागत है! मदद करने के कई तरीके हैं, जिनमें शामिल हैं:" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "गाइड पढ़ना और प्रतिक्रिया देना" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "नए योगदानों की समीक्षा करना" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "मौजूदा सामग्री को संशोधित करना" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "नई सामग्री लिखना" + +#: ../source/contribute.rst:14 +#, fuzzy +#| msgid "Translate the guide" +msgid "Translating the guide" +msgstr "मार्गदर्शक" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" +"अधिकांश कार्य |PyPUG| पर `प्रोजेक्ट के GitHub रिपॉजिटरी`__ पर होता है। आरंभ करने के " +"लिए, `खुले मुद्दे`__ और `पुल अनुरोध`__ की सूची देखें। यदि आप गाइड लिखने या संपादित करने की " +"योजना बना रहे हैं, तो कृपया :ref:`स्टाइल गाइड ` पढ़ें।" + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" +"|PyPUG| में योगदान देकर, आपसे PSF की `आचार संहिता`__ का पालन करने की अपेक्षा की जाती " +"है।" + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "दस्तावेज़ीकरण प्रकार" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "" + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "दायरा" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "" + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "" + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "" + +#: ../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 +msgid "What is a source distribution?" +msgstr "" + +#: ../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 +msgid "What about eggs?" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python setup.py install``" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/setup-py-deprecated.rst:25 +#: ../source/discussions/setup-py-deprecated.rst:39 +#: ../source/guides/modernize-setup-py-project.rst:36 +#, fuzzy +msgid "``python setup.py sdist``" +msgstr "पाइथॉन संस्करण" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python -m pip install --editable .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +#, fuzzy +msgid "``python setup.py test``" +msgstr "पाइथॉन संस्करण" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +#, fuzzy +msgid "``python -m twine check --strict dist/*``" +msgstr "पाइथॉन संस्करण" + +#: ../source/discussions/setup-py-deprecated.rst:104 +#, fuzzy +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "पाइथॉन संस्करण" + +#: ../source/discussions/setup-py-deprecated.rst:105 +#, fuzzy +msgid "``python -m twine upload dist/*``" +msgstr "पाइथॉन संस्करण" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +#, fuzzy +msgid "``python setup.py --version``" +msgstr "पाइथॉन संस्करण" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +#, fuzzy +msgid "``python -m setuptools_scm``" +msgstr "पाइथॉन संस्करण" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr "" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +msgid "Complete" +msgstr "" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +msgid "Versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +msgid "Calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +msgid "Other schemes" +msgstr "" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 ../source/flow.rst:143 +msgid "" +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../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 :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +#, fuzzy +#| msgid "Installing packages" +msgid "Installed Project" +msgstr "पैकेज प्रतिष्ठापन" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +#, fuzzy +#| msgid "Project name" +msgid "Project Root Directory" +msgstr "परियोजना" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "" + +#: ../source/glossary.rst:257 +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:260 +#, fuzzy +#| msgid "Project name" +msgid "Pyproject Metadata" +msgstr "परियोजना" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +#, fuzzy +#| msgid "Project name" +msgid "Pyproject Metadata Key" +msgstr "परियोजना" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "" + +#: ../source/glossary.rst:344 +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:348 +#, fuzzy +#| msgid "Project name" +msgid "Root License Directory" +msgstr "परियोजना" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +msgid "Wheel Project" +msgstr "" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "परियोजना" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "पाइथॉन संस्करण" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "" +"https://files.pythonhosted.org/packages/eb/" +"45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" +"sampleproject-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "" +"https://files.pythonhosted.org/packages/56/0a/" +"178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" +"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +msgid "" +"https://files.pythonhosted.org/packages/" +"63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" +"sampleproject_nomura-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +#, fuzzy +#| msgid "Installing packages" +msgid "Creating the package" +msgstr "पैकेज प्रतिष्ठापन" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +#, fuzzy +#| msgid "Project name" +msgid "``pyproject.toml``" +msgstr "परियोजना" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +#, fuzzy +#| msgid "Installing packages" +msgid "Installing the package with ``pipx``" +msgstr "पैकेज प्रतिष्ठापन" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +msgid "Conclusion" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "खाता" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +#, fuzzy +#| msgid "Installing packages" +msgid "1. Install twine" +msgstr "पैकेज प्रतिष्ठापन" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +#, fuzzy +#| msgid "Python version" +msgid "Dropping a Python version" +msgstr "पाइथॉन संस्करण" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:108 +msgid "openSUSE" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:118 +msgid "Debian/Ubuntu and derivatives" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +#, fuzzy +#| msgid "Installing packages" +msgid "Install packages in a virtual environment using pip and venv" +msgstr "पैकेज प्रतिष्ठापन" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +#, fuzzy +#| msgid "Installing packages" +msgid "Install packages using pip" +msgstr "पैकेज प्रतिष्ठापन" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +#, fuzzy +#| msgid "Installing packages" +msgid "Install a package" +msgstr "पैकेज प्रतिष्ठापन" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +#, fuzzy +#| msgid "Installing packages" +msgid "Install a specific package version" +msgstr "पैकेज प्रतिष्ठापन" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +#, fuzzy +#| msgid "Installing packages" +msgid "Install extras" +msgstr "पैकेज प्रतिष्ठापन" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +#, fuzzy +#| msgid "Installing packages" +msgid "Install a package from source" +msgstr "पैकेज प्रतिष्ठापन" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +#, fuzzy +#| msgid "Installing packages" +msgid "Install from other package indexes" +msgstr "पैकेज प्रतिष्ठापन" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +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/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +#, fuzzy +#| msgid "Installing packages" +msgid "Installing packages using virtualenv" +msgstr "पैकेज प्रतिष्ठापन" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python -m build``" +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:126 +msgid "``python -m build --no-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:127 +msgid "``python -m pip install --no-build-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +#, fuzzy +#| msgid "Project name" +msgid ":ref:`pyproject-toml-spec`" +msgstr "परियोजना" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../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 "" +"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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +msgid "Installation" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:233 +msgid "``appveyor-sample/build.cmd``" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:5 +msgid "Tool recommendations" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +#, fuzzy +#| msgid "Installing packages" +msgid "Installing packages" +msgstr "पैकेज प्रतिष्ठापन" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +msgid "Building distributions" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:313 +msgid "setuptools" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:317 +msgid "uv-build" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +msgid "`Kivy `_" +msgstr "" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +#, fuzzy +#| msgid "Project name" +msgid "Subdirectory name" +msgstr "परियोजना" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +msgid "``licenses``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*object*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Python version" +msgid "Schema version." +msgstr "पाइथॉन संस्करण" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "examples" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "version\\_info" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*number*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**implementation**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**flags**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**headers**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +msgid "Package Building" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:248 +#, fuzzy +msgid "Python equivalent" +msgstr "पाइथॉन संस्करण" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:282 +#, fuzzy +msgid "``python_version``" +msgstr "पाइथॉन संस्करण" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +msgid ":ref:`Version `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:286 +#, fuzzy +msgid "``python_full_version``" +msgstr "पाइथॉन संस्करण" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +#, fuzzy +#| msgid "Project name" +msgid "``toml``" +msgstr "परियोजना" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +msgid "``dependency_groups``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +#, fuzzy +#| msgid "Installing packages" +msgid "Python-specific package manager" +msgstr "पैकेज प्रतिष्ठापन" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +#, fuzzy +#| msgid "Installing packages" +msgid "Installers" +msgstr "पैकेज प्रतिष्ठापन" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +msgid "Reference implementation in Python" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +msgid "Names and normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +msgid "Name normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +#, fuzzy +#| msgid "Project name" +msgid "Project Status Markers" +msgstr "परियोजना" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +msgid "Installer semantics: none." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +#, fuzzy +#| msgid "Installing packages" +msgid "Installer semantics:" +msgstr "पैकेज प्रतिष्ठापन" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +msgid "``deprecated``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +msgid "``pylock.toml`` Specification" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +#, fuzzy +msgid "``lock-version``" +msgstr "पाइथॉन संस्करण" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +msgid "**Required?**: yes" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +msgid "``environments``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +msgid "``dependency-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +#, fuzzy +#| msgid "Project name" +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "परियोजना" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +msgid "``[[packages]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +#, fuzzy +msgid "``packages.version``" +msgstr "पाइथॉन संस्करण" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +#, fuzzy +#| msgid "Installing packages" +msgid "The version of the package." +msgstr "पैकेज प्रतिष्ठापन" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +msgid "``[[packages.dependencies]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +msgid "The time the file was uploaded." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +msgid "``packages.index``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +#, fuzzy +#| msgid "Project name" +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "परियोजना" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +msgid "``import-names``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +msgid "Legacy specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +msgid "Examples:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +msgid "Example:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +msgid "PyPA schemas" +msgstr "" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +#, fuzzy +#| msgid "Python version" +msgid "Python Description Formats" +msgstr "पाइथॉन संस्करण" + +#: ../source/specifications/section-reproducible-environments.rst:3 +msgid "Reproducible Environments" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +msgid "Normalized Names" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +msgid "HTML Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +#, fuzzy +#| msgid "Project name" +msgid "Project List" +msgstr "परियोजना" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +#, fuzzy +#| msgid "Project name" +msgid "Project Detail" +msgstr "परियोजना" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +msgid "JSON Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +msgid "Content-Types" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +msgid "Version + Format Selection" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +msgid "Definitions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +msgid "Version scheme" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +msgid "Pre-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +msgid "Version epochs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +msgid "Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +msgid "Integer Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +msgid "Version exclusion" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +#, fuzzy +#| msgid "Project name" +msgid "Well-known Project URLs in Metadata" +msgstr "परियोजना" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +msgid "Label normalization" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +msgid "Normalized" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"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/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "" + +#: ../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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "" + +#: ../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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" + +#, fuzzy +#~| msgid "Project name" +#~ msgid "**Inspiration**: :ref:` pyproject-tool-table`" +#~ msgstr "परियोजना" diff --git a/locales/id/LC_MESSAGES/messages.po b/locales/id/LC_MESSAGES/messages.po new file mode 100644 index 000000000..b06586903 --- /dev/null +++ b/locales/id/LC_MESSAGES/messages.po @@ -0,0 +1,26892 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# Syahmin Sukhairi , 2022. +# ravihidayat , 2022. +# SimpleXtra , 2022. +# Rafael Fontenelle , 2024. +# oon arfiandwi , 2024. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: 2024-10-17 21:16+0000\n" +"Last-Translator: oon arfiandwi \n" +"Language-Team: Indonesian \n" +"Language: id\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=1; plural=0;\n" +"X-Generator: Weblate 5.8-rc\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "Ikut berkontribusi pada panduan ini" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "" +"|PyPUG| menyambut kontributor! Banyak yang dapat dilakukan, diantaranya:" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "Baca panduan dan berikan umpan balik" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "Tinjau kontribusi baru" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "Revisi konten yang ada" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "Tulis konten baru" + +#: ../source/contribute.rst:14 +#, fuzzy +#| msgid "Translate the guide" +msgid "Translating the guide" +msgstr "Alih bahasa panduan" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" +"Sebagian besar pekerjaan di |PyPUG| terdapat di `project's GitHub " +"repository`__. Untuk memulai, silakan tinjau senarai `open issues`__ dan " +"`pull requests`__. Jika anda berencana untuk menulis atau menyunting " +"panduan, dimohon untuk membaca :ref:`style guide ` " +"terlebih dahulu." + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" +"Dengan berkontribusi ke |PyPUG|, Anda diharapkan untuk mematuhi `Code of " +"Conduct`__ dari PSF." + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "Jenis-jenis dokumentasi" + +#: ../source/contribute.rst:34 +#, fuzzy +#| msgid "" +#| "This project consists of four distinct documentation types with specific " +#| "purposes. When proposing new additions to the project please pick the " +#| "appropriate documentation type." +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" +"Proyek ini mengandung empat jenis dokumentasi berbeda dengan tujuan " +"spesifik. Ketika dokumentasi baru akan ditambahkan, dimohon untuk memilih " +"jenis dokumentasi yang sesuai." + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "Tutorial" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "Panduan" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "Diskusi" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "Spesifikasi" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "Penerjemahan" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" +"Kami menggunakan `Weblate`_ untuk mengelola penerjemahan proyek ini. " +"Silahkan kunjungi proyek `packaging.python.org`_ di Weblate untuk " +"berkontribusi." + +#: ../source/contribute.rst:80 +#, fuzzy +#| msgid "" +#| "If you are experiencing issues while you are working on translations, " +#| "please open an issue on `Github`_." +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" +"Apabila Anda mengalami masalah selama Anda mengerjakan penerjemahan, tolong " +"buka issue di `Github`_." + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "Menambahkan suatu bahasa" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" +"Apabila Anda belum terbiasa dengan sintaks reStructuredText (RST), harap " +"baca `panduan ini`_ sebelum menerjemahkan di Weblate." + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "" + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "Cakupan" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "" + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "" + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +#, fuzzy +#| msgid "and import the package:" +msgid "What's an import package?" +msgstr "dan *import* package tersebut:" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "" + +#: ../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 +msgid "What is a source distribution?" +msgstr "" + +#: ../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 +msgid "What about eggs?" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python setup.py install``" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 +#, fuzzy +#| msgid "Documentation types" +msgid "Recommendation" +msgstr "Jenis-jenis dokumentasi" + +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python -m pip install .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python -m pip install --editable .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:104 +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "Apakah ``setup.py`` perlu dihapus?" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "Apakah ``pyproject.toml`` wajib?" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +#, fuzzy +#| msgid "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr ":doc:`setuptools:deprecated/commands`" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +msgid "Complete" +msgstr "Selesai" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "2024-10-07" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "Secara umum, pilihannya adalah:" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" +"Jika kode berada dalam sistem kontrol versi (VCS), seperti Git, maka versi " +"dapat diekstrak dari VCS." + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +#, fuzzy +msgid "Versioning" +msgstr "Penerjemahan" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +#, fuzzy +msgid "Calendar versioning" +msgstr "Penerjemahan" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +#, fuzzy +msgid "Other schemes" +msgstr "Penerjemahan" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 ../source/flow.rst:143 +msgid "" +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../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 :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +#, fuzzy +#| msgid "Translations" +msgid "Installed Project" +msgstr "Penerjemahan" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +msgid "Project Root Directory" +msgstr "" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "" + +#: ../source/glossary.rst:257 +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:260 +msgid "Pyproject Metadata" +msgstr "" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +msgid "Pyproject Metadata Key" +msgstr "" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "" + +#: ../source/glossary.rst:344 +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:348 +msgid "Root License Directory" +msgstr "" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +msgid "Wheel Project" +msgstr "" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "" +"https://files.pythonhosted.org/packages/eb/" +"45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" +"sampleproject-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "" +"https://files.pythonhosted.org/packages/56/0a/" +"178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" +"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +msgid "" +"https://files.pythonhosted.org/packages/" +"63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" +"sampleproject_nomura-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +#, fuzzy +#| msgid "and import the package:" +msgid "Creating the package" +msgstr "dan *import* package tersebut:" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +msgid "``pyproject.toml``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +#, fuzzy +#| msgid "Translations" +msgid "Installing the package with ``pipx``" +msgstr "Penerjemahan" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +#, fuzzy +msgid "Conclusion" +msgstr "Penerjemahan" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +#, fuzzy +#| msgid "Translations" +msgid "1. Install twine" +msgstr "Penerjemahan" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +msgid "Dropping a Python version" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:108 +msgid "openSUSE" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:118 +msgid "Debian/Ubuntu and derivatives" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +msgid "Install packages in a virtual environment using pip and venv" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +msgid "Install packages using pip" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +#, fuzzy +#| msgid "Translations" +msgid "Install extras" +msgstr "Penerjemahan" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +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/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python -m build``" +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:126 +msgid "``python -m build --no-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:127 +msgid "``python -m pip install --no-build-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../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 "" +"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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +#, fuzzy +#| msgid "Translations" +msgid "Installation" +msgstr "Penerjemahan" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:233 +msgid "``appveyor-sample/build.cmd``" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:5 +msgid "Tool recommendations" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +#, fuzzy +#| msgid "Translations" +msgid "Installing packages" +msgstr "Penerjemahan" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +#, fuzzy +#| msgid "Reviewing new contributions" +msgid "Building distributions" +msgstr "Tinjau kontribusi baru" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:313 +msgid "setuptools" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:317 +msgid "uv-build" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +msgid "`Kivy `_" +msgstr "" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "Subdirectory name" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +msgid "``licenses``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "Spesifikasi" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*object*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Schema version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "examples" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +msgid "**version**" +msgstr "Penerjemahan" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +msgid "version\\_info" +msgstr "Penerjemahan" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*number*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Documentation types" +msgid "**implementation**" +msgstr "Jenis-jenis dokumentasi" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**flags**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +msgid "extensions" +msgstr "Penerjemahan" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**headers**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +msgid "Package Building" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +#, fuzzy +#| msgid "Documentation types" +msgid "Reference Implementation" +msgstr "Jenis-jenis dokumentasi" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +#, fuzzy +msgid "Versions" +msgstr "Penerjemahan" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +msgid ":ref:`Version `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +msgid "``toml``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +msgid "``dependency_groups``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +#, fuzzy +#| msgid "Documentation types" +msgid "Implementation Notes" +msgstr "Jenis-jenis dokumentasi" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +#, fuzzy +#| msgid "Translations" +msgid "Installers" +msgstr "Penerjemahan" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +#, fuzzy +#| msgid "Documentation types" +msgid "Reference implementation in Python" +msgstr "Jenis-jenis dokumentasi" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +#, fuzzy +msgid "Names and normalization" +msgstr "Penerjemahan" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +#, fuzzy +msgid "Name normalization" +msgstr "Penerjemahan" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +msgid "Project Status Markers" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +#, fuzzy +#| msgid "Translations" +msgid "Installer semantics: none." +msgstr "Penerjemahan" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +#, fuzzy +#| msgid "Translations" +msgid "Installer semantics:" +msgstr "Penerjemahan" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +msgid "``deprecated``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +#, fuzzy +#| msgid "Specification" +msgid "``pylock.toml`` Specification" +msgstr "Spesifikasi" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +msgid "``lock-version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +msgid "**Required?**: yes" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +msgid "``environments``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +msgid "``dependency-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +msgid "``[[packages]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +msgid "``packages.version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +#, fuzzy +#| msgid "and import the package:" +msgid "The version of the package." +msgstr "dan *import* package tersebut:" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +msgid "``[[packages.dependencies]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +msgid "The time the file was uploaded." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +msgid "``packages.index``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +msgid "``import-names``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +#, fuzzy +#| msgid "Specification" +msgid "Legacy specification" +msgstr "Spesifikasi" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +msgid "Examples:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +msgid "Example:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +msgid "PyPA schemas" +msgstr "" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +msgid "Python Description Formats" +msgstr "" + +#: ../source/specifications/section-reproducible-environments.rst:3 +msgid "Reproducible Environments" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +#, fuzzy +msgid "Normalized Names" +msgstr "Penerjemahan" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +#, fuzzy +msgid "HTML Serialization" +msgstr "Penerjemahan" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +msgid "Project List" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +msgid "Project Detail" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +#, fuzzy +msgid "JSON Serialization" +msgstr "Penerjemahan" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +msgid "Content-Types" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +#, fuzzy +msgid "Version + Format Selection" +msgstr "Penerjemahan" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +#, fuzzy +#| msgid "Specifications" +msgid "Definitions" +msgstr "Spesifikasi" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +#, fuzzy +msgid "Version scheme" +msgstr "Penerjemahan" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +msgid "Pre-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +#, fuzzy +msgid "Version epochs" +msgstr "Penerjemahan" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +#, fuzzy +msgid "Normalization" +msgstr "Penerjemahan" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +#, fuzzy +msgid "Integer Normalization" +msgstr "Penerjemahan" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +#, fuzzy +msgid "Version exclusion" +msgstr "Penerjemahan" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +msgid "Well-known Project URLs in Metadata" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +#, fuzzy +msgid "Label normalization" +msgstr "Penerjemahan" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +#, fuzzy +msgid "Normalized" +msgstr "Penerjemahan" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"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/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "" + +#: ../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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "" + +#: ../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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "Membuat sebuah LICENSE" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "dan *import* package tersebut:" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" diff --git a/locales/ja/LC_MESSAGES/messages.po b/locales/ja/LC_MESSAGES/messages.po new file mode 100644 index 000000000..d79849b73 --- /dev/null +++ b/locales/ja/LC_MESSAGES/messages.po @@ -0,0 +1,39623 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# moto kawasaki , 2021, 2022, 2023, 2024, 2025, 2026. +# tsutsu3 , 2023. +# nikkie , 2023. +# Rafael Fontenelle , 2024. +# "Takanori Suzuki (takanory)" , 2025. +# Xianpeng Shen , 2025. +# Lenas Sha , 2025. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: 2026-03-12 08:09+0000\n" +"Last-Translator: moto kawasaki \n" +"Language-Team: Japanese \n" +"Language: ja\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=1; plural=0;\n" +"X-Generator: Weblate 5.17-dev\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "このガイド文書に貢献する" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "|PyPUG| は貢献者を歓迎します！さまざまな貢献方法があります。例えば:" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "このガイド文書を読んでフィードバックを伝える" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "新しい貢献内容を査読する" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "既存の文書を修正する" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "新しく文書を書くこと" + +#: ../source/contribute.rst:14 +msgid "Translating the guide" +msgstr "ガイド文書を翻訳する" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" +"|PyPUG| のほとんどの作業は `project's GitHub repository`__ で行われます。手始" +"めに `open issues`__ のリストをチェックアウトして `pull requests`__ を送って" +"ください。もしあなたがこのガイドに何かを書き加えたり編集したりするつもりな" +"ら、 :ref:`スタイルガイド ` を読みましょう。" + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" +"|PyPUG| に貢献を行うことによって、あなたがPSFの `Code of Conduct`__ に従うこ" +"とが期待されています。" + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "文書の類型" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" +"本プロジェクトは、特定の目的に合わせた四つの別個の文書類型で成り立っていま" +"す。本プロジェクトでは、文書化の品質向上のために `Diátaxis process`_ に従うこ" +"とを強く希望します。新たに追加することを提案する場合には、いずれかの適切な文" +"書類型を選択してください。" + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "チュートリアル型文書" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" +"チュートリアルは目標を達成することで読者に新しい概念を教えることに注力してい" +"ます。こうするべきだという意見に従ったステップバイステップのガイドになってい" +"ます。大筋に無関係な警告や情報は省略されています。 `example tutorial-style " +"document`_ 。" + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "ガイド型文書" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" +"ガイドは特定のタスクを達成することに力点を置いていて、前提となる知識のレベル" +"をある程度仮定することができます。ガイドはチュートリアルと似ていますが、しか" +"しガイドはもっと狭い分野に明確に焦点を当てるものであり、必要に応じて多数の注" +"意書きを行ったり追加的な情報を盛り込んだりすることができます。ガイドでは、そ" +"のタスクを達成するための複数のやり方を議論することもできます。:doc:`ガイド型" +"文書の例 `." + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "議論型文書" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" +"議論型文書では、理解促進と情報提供に重点を置きます。議論型文書では、特定の" +"ゴールを念頭に置くことなく、ある特定の話題について深く探求します。:doc:`議論" +"型文書の例 `." + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "仕様型文書" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" +"仕様型文書は、パッケージングツール間で相互運用のためのインターフェイスとして" +"合意された事項について網羅的に文書化することに重点を置く参照用の文書で" +"す。:doc:`仕様型文書の例 `." + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "翻訳" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" +"我々は本プロジェクトの翻訳を管理するために `Weblate`_ を使用しています。 翻訳" +"で貢献するには、Weblate上の `packaging.python.org`_ プロジェクトをご覧くださ" +"い。" + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" +"翻訳作業中になにか問題を感じたら、`GitHub`_ で issue を新規登録してください。" + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" +"本プロジェクトの翻訳はすべて、 `reStructuredText syntax`_ に従わなければなり" +"ません。" + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "言語を追加する" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" +"もしあなたの使う言語が `packaging.python.org`_ のリストに掲載されていなけれ" +"ば、言語一覧の下にある :guilabel:`新しい翻訳を始める ` ボタンをクリックして、あなたが翻訳したい言語を追加してくださ" +"い。" + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "reStructuredText文法に従う" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" +"もしあなたがreStructuredText(RST)の書き方に慣れていないのであれば、Weblateで" +"翻訳作業をする前に `this guide`_ を読んでください。" + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "**参照リンクのテキストをそのまま翻訳することはやめてください**" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "" +"参照リンクのテキストを翻訳する時、単純に翻訳文で置き換えることはやめて下さ" +"い。" + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "誤: 次のテキストを単純に翻訳する:" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" +"正: 次のテキストをあなた自身の言語に翻訳して、さらに元の参照リンクを残す:" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "この文書を手元でビルドするには" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" +"貢献寄与をするために必須というわけではありませんが、この文書を手元でビルドす" +"ることはあなたが行った変更をテストするのに役に立ちます。この文書を手元でビル" +"ドするには：" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" +":doc:`Nox ` 。 ``pip`` を用いてnoxをインストールまたはアップグレー" +"ドできます:" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" +"Python 3.11。我々のビルドスクリプトは、通常、Python 3.11でのみ試験されてい" +"る。あなたの使っているOSにPython 3.11をインストールする方法について" +"は、 :doc:`Python のインストール指南のためのヒッチハッカーズガイド ` を見てほしい。" + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" +"この文書をビルドするには、以下のシェルコマンドをプロジェクトのルートディレク" +"トリで実行してください:" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" +"処理が終わると、``./build/html`` の下にHTMLの出力ファイルが見つかるはずです。" +"ここの ``index.html`` をブラウザで開くことでこの文書を閲覧することができます" +"が、HTTPサーバを使って文書を提供する方がお勧めです。" + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "HTTPサーバを用いてこの文書を提供するには、以下のコマンドを使います。:" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "この文書は、 http://localhost:8000 から閲覧できます。" + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "この文書が展開される場所" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" +"この文書は ReadTheDocs を通じて展開されていて、 https://readthedocs.org/" +"projects/python-packaging-user-guide/ から読めるようになっています。また、 " +"Fast.ly から独自のドメイン名から提供されるようになっています(第二文はここだけ" +"では意味が取れない)。" + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "スタイルガイド" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" +"このスタイルガイドは、あなたがどのように |PyPUG| を書くべきかについて推奨事項" +"を与えます。あなたが書き始める前に目を通してください。スタイルガイドに従うこ" +"とであなたの貢献がまとまりのある全体の中の一部として追加され、あなたの貢献が" +"プロジェクトによって受け入れられやすくなります。" + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "目的" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" +"|PyPUG| の目的は、現在のツール群を用いてPythonプロジェクトをパッケージし、公" +"開し、インストールする方法に関して権威ある参照先となることです。" + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "スコープ" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" +"この文書は、正確で的を射た推奨事項を添えた形で疑問に答え問題を解決することを" +"意図しています。" + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" +"この文書は網羅的であることを目指してはおらず、それぞれのプロジェクトのドキュ" +"メントを置き換えることも意図していません。例えば、pipにはたくさんのコマンドや" +"オプションや設定事項があります。pipのドキュメントはその一つ一つについて詳細に" +"記述していますが、この文書ではこの文書に記述されたタスクを完了するために必要" +"となる部分に限ってpipに触れています。" + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "想定される読者" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "この文書の読者として想定されるのは、Pythonのパッケージを扱う方です。" + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" +"Pythonコミュニティが巨大で温かいコミュニティであることを忘れないでください。" +"読者は年齢・性別・教育程度・文化やその他諸々の点であなたと同じではないかもし" +"れませんが、しかし、あなたがあなたにできる限りパッケージングについて学ぶこと" +"を称賛します。" + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" +"とりわけ、Pythonを使う人なら誰でも自分をプログラマーだと思っているというわけ" +"ではないことを覚えておいてください。この文書の想定される読者には、ソフトウェ" +"ア開発を職業としているプロだけでなく、宇宙飛行士や画家あるいは学生も含まれる" +"のです。" + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "口調や語調" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" +"この文書を書く時には、たとえあなたが答えを全部わかっていたとしても親しみやす" +"く控えめな語調で書くように努力してください。" + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" +"頭が良くてスキルのある人たちと一緒にPythonのプロジェクトをやるところを思い描" +"いてください。あなたは彼らと働くのが好きだし、彼らもあなたと働くのが好きなの" +"です。そんな人があなたに質問をして、あなたが答えを知っていたとしましょう。あ" +"なたはどんな風に応対しますか？ *それ* こそが、あなたがこの文書を書く時のやり" +"方なのです。" + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" +"簡単な確認方法：あなたが書いたものを声に出して読めば、その口調や語調の感じが" +"わかります。それはあなたが言いたかった感じに響きましたか、それとも、演説の一" +"部みたいに聞こえましたか？短縮形を使っても構いませんし、曖昧な文法規則に固執" +"することはありません。あなたはここに、もしそうしたいのならば前置詞で文を終" +"わっても構わないと言う権限を与えられました。" + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" +"ガイド文書を書くときは、論題の深刻さや難しさに合った語調に調整してください。" +"もしあなたが入門篇のようなチュートリアルを書くときには冗談を挟んでも構いませ" +"んが、繊細な注意を必要とするセキュリティ上の推奨事項をカバーするなら冗談を全" +"く入れないようにしたいと思うかもしれません。" + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "慣例と手順" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "**読者に向けて書く**" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" +"推奨事項や実行すべきステップを与えるときは、読者に *あなた* と呼びかけるか、" +"または、命令法を用いて欲しい。" + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "誤：それをインストールするために、ユーザは...を実行します。" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "正：...を実行することであなたはそれをインストールすることができます。" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "正：それをインストールするには、...を実行してください。" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "**前提条件の明示**" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" +"暗黙のうちに前提条件を仮定することのないようにしましょう。Webページとして提供" +"するということは、この文書のどのページであってもそれが読者にとっての初めての" +"ページになるかもしれないということです。" + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "**豊富な相互参照**" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" +"あるツールや行為にあなたが初めて言及するときには、ガイドのそれを説明している" +"部分へのリンク、または、どこか他の場所であっても適切な説明文書へのリンクも提" +"供してください。" + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "**命名慣習を尊重すること**" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" +"ツールやサイト、登場人物や他の適切な名詞に名前を付けるときには、大文字小文字" +"などそれぞれが好んで使っている書き方を尊重してください。" + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "誤：Pipは…" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "正：pipは…" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "誤：...はgithubにホストされている。" + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "正：...はGitHubにホストされている。" + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "**ジェンダー中立なスタイルを使う**" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" +"あなたが読者に直接呼びかけるときは「 *あなた* 」「 *あなたの* 」「 *あなたの" +"もの* 」を使ってください。そうできない場合は代名詞として「 *彼ら* 」「 *彼ら" +"の* 」「 *彼らのもの* 」を使う(訳註：従来なら\"he\", \"she\"を用いた場所に" +"\"they\"を使うことでジェンダーへの配慮を示す場合がある)か、または、代名詞を" +"まったく使わないようにしましょう。" + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "誤：メンテナンス担当者がファイルをアップロードする。それから、彼は…" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "正：メンテナンス担当者がファイルをアップロードする。それから、彼らは…" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "" +"正：メンテナンス担当者がファイルをアップロードする。それから、メンテナンス担" +"当者は…" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "**見出しの付け方**" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" +"見出しには読者が検索で使うような単語を使いましょう。質問の意図に答える形で見" +"出しを書くのは良い方法です。読者が例えば *MyLibraryをインストールするにはどう" +"すれば良いの？* ということを知りたいとすれば、適切な見出しとしては *MyLibrary" +"をインストールするには* のようになるでしょう。" + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" +"見出し部分では通常の文章のように大文字小文字を使いましょう。言い換えるなら、" +"ごく普通の文を書く時のように見出しを書きましょう。" + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "" +"誤：Pythonについてあなたが知っておくべき事柄 (訳註：日本語には大文字小文字の" +"区別がないので誤例にならないのではないか)" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "正：Pythonについてあなたが知っておくべき事柄" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "**数値の書き方**" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" +"地の文では一から九までの数字を単語で書きましょう(訳註：日本語では漢数字にする" +"よりもアラビア数字の方が適切かもしれません)。表の中ではアラビア数字で書きま" +"しょう。" + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "Pythonで書かれたアプリケーションを配置(deploy)する" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "ページステイタス" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "未完了" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "最終査読日" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "2021-8-24" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "概要" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "複数のハードウェアプラットフォームをサポートする" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "OSパッケージングとインストーラ" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" +"`Pynsist `__ は、Pythonで書かれたプログラム" +"群をNSISベースのPythonインタープリタ付きの単体インストーラにまとめるツールで" +"す。ほとんどの場合、パッケージング作業ではユーザがPythonインタープリタのバー" +"ジョンを選択することとプログラムの依存関係を宣言することしか求められません。" +"このツールは、指定されたWindows版のPythonインタープリタをダウンロードして、依" +"存関係にあるすべてをWindows上で実行可能な単体インストーラにまとめます。" + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" +"インストーラがスタートメニューに追加したショートカットから、インストールされ" +"たプログラムを起動することができます。プログラムは、そのアプリケーション用の" +"ディレクトリの中にインストールされたPythonインタープリタで同じコンピュータ内" +"にある他のPythonからは独立したをものを使います。" + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" +"Pynsistを使う大きな利点は、Windows用のパッケージをLinux上で作成することができ" +"るということです。 :any:`documentation ` には異なる種類のプロ" +"グラム(コンソール用やGUIを使うものなど)の例がいくつかあります。このツールは" +"MITライセンスのもとに公開されています。" + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "アプリケーションバンドル" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "py2exe" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" +"`py2exe `__ はdistutilsの拡張パッケージで、" +"Pythonのスクリプトから単独で動作するWindowsの実行プログラム(32ビット版または" +"64ビット版)を作成することができます。公式の開発サイクルに含まれるバージョンの" +"Pythonがすべてサポートされています( `Status of Python branches`__ を参照して" +"下さい)。py2exeはコンソールで動作する実行可能ファイルも、Windowsの(GUIの)実行" +"ファイルも作成することができます。WindowsサービスやDLL/EXE COMサーバを作成す" +"ることもできるかもしれませんが、これらは活発にサポートされているとは言えませ" +"ん。distutilsの拡張パッケージは、MITライセンスとMozilla Publicライセンス2.0の" +"下で公開されています。" + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "macOS" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "py2app" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" +"`py2app `__ はPythonのsetuptoolsのコマンド" +"で、単独で動作するmacOSアプリケーションバンドルやプラグインをPythonスクリプト" +"から作成することができます。アプリケーションを作成する時はmacOS上でpy2appを使" +"わなければならず、他のプラットフォーム上ではMacアプリを作成することができない" +"点に留意して下さい。py2appはMITライセンスの下で公開されています。" + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "Unix (LinuxとmacOSを含む)" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "pex" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" +"`pex `__ は、.pex (Python EXecutable)ファイ" +"ル、つまり、virtualenvを利用した実行可能なPython環境を含んだファイルを生成す" +"るライブラリです。pexは :pep:`441` で概要が示されたアイデアに基づく拡張で、単" +"純にファイルをコピーするだけでPythonアプリケーションを配置(デプロイ)すること" +"ができるようにします。複数のプラットフォーム依存なPython配布物でもpexファイル" +"に内包することができますので、単一のpexファイルがLinuxでもmacOSでも動作可能と" +"いうことになります。pexはApacheライセンス2.0の下で公開されています。" + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "設定管理" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "配布パッケージ vs. インポートパッケージ" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" +"数多くの異なったコンセプトが同じ \"パッケージ\" の名で呼ばれています。この" +"ページでは、\"配布パッケージ\" と \"インポートパッケージ\" という、関連しては" +"いるが全く異なる二つの Python のパッケージングの意味を明らかにします。" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "配布パッケージとは何でしょうか？" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" +"配布パッケージとは、インストール可能な一片のソフトウェアです。ほとんどの場" +"合、これは \"プロジェクト \" と同義です。 ``pip install pkg`` とタイ" +"プする時、あるいは、 ``pyproject.toml`` に ``dependencies = [\"pkg\"]`` と書" +"く時、 ``pkg`` のところには配布パッケージの名前を書きます。Python のライブラ" +"リやツール類の集約された源として最も広く知られている PyPI_ で検索したり閲覧す" +"る時、あなたが目にするものは配布パッケージのリストです。あるいは、\"配布パッ" +"ケージ\" という言葉があるプロジェクトの特定のバージョンを内包した特定のファイ" +"ルのことを指す場合もあります。" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" +"Linux の世界では、 \"配布パッケージ \" が \"ディストロ" +"パッケージ \" か単に \"パッケージ \" と短縮形で呼ば" +"れることが通常であり、 `Linux distibution `_ のシステムパッケージ管" +"理者によって提供される何かのことであって、異なる意味で使われているということ" +"は意識しておいてください。" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "パッケージをインポートする、とは何でしょうか？" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" +"インポートパッケージは Python モジュールです。したがって、 Python コードに " +"``import pkg`` もしくは ``from pkg import func`` と書く時、 ``pkg`` の部分は" +"インポートパッケージの名称です。より精確には、インポートパッケージは、サブモ" +"ジュールを内包することができる特別な Python モジュールです。例えば、 " +"``numpy`` パッケージは ``numpy.linalg`` や ``numpy.fft`` のようなモジュールを" +"内包しています。通常は、インポートパッケージはファイルシステム上のディレクト" +"リであって、モジュールを ``.py`` の形で含み、サブパッケージをサブディレクトリ" +"の形で含むものです。" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" +"インポートパッケージを提供する配布パッケージをインストールするや否や、イン" +"ポートパッケージを使用することができます。" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "配布パッケージとインポートパッケージの間の繋がりとは何でしょうか？" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" +"ほとんどの場合、配布パッケージはあるひとつのインポートパッケージ (またはパッ" +"ケージではないモジュール) を対応する名称で提供します。例えば、 ``pip install " +"numpy`` を行えば ``import numpy`` として使うことができます。" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" +"しかしながら、これは単なる慣習です。PyPI や他のパッケージインデックスでは、配" +"布パッケージとそれが提供するインポートパッケージの名称の間に *なんらかの関係" +"性を強制することはしません* 。 (このことの帰結として、 ``import foo`` を見た" +"からと言って盲目的に PyPI のパッケージ ``foo`` をインストールすることはできま" +"せん; これは意図しないか、あるいは潜在的には悪意のあるパッケージをインストー" +"ルしてしまうことになりかねません。)" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" +"配布パッケージは、異なる名称でインポートパッケージを提供することが可能です。" +"この例としては、画像処理分野で人気のある Pillow_ です。配布パッケージの名称" +"は ``Pillow`` ですが、インポートパッケージとしては ``PIL`` を提供しています。" +"これには歴史的な理由があります: Pillow は PIL ライブラリのフォークとして始ま" +"り、PIL の既存のユーザがあまり手間をかけずに Pillow に移行できるようにイン" +"ポート名称の ``PIL`` を使い続けたのです。もっと一般的にいうと、配布パッケージ" +"とインポートパッケージの間で異なる名称を使う時のよくある理由が既存のライブラ" +"リからのフォークなのです。" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" +"(PyPI のような) あるパッケージインデックス内では、配布パッケージの名称は一意" +"でなければなりません。他方で、インポートパッケージにはそのような要求事項はあ" +"りません。同じ名称のインポートパッケージが複数の配布パッケージから提供される" +"ということも可能です。繰り返しますが、これのよくある理由はフォークです。" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" +"一方で、あまり見かけませんが、配布パッケージは複数のインポートパッケージを提" +"供することができます。その例は attrs_ 配布パッケージで、より新しい API を持" +"つ ``attrs`` インポートパッケージと、旧来のものだがサポートされている API を" +"持つ ``attr`` の両方を提供します。" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" +"配布パッケージの名称とインポートパッケージの名称は、どのように比較されるので" +"しょうか？" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" +"インポートパッケージは、その名称として正当な Python 識別子 (Python の説明文書" +"の中に :ref:`exact rules ` が見つかるでしょう) [#non-" +"identifier-mod-name]_ を持っているべきです。特に、単語間の区切りにアンダース" +"コア ``_`` を使い、また、大文字小文字を区別します。" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" +"他方で、配布パッケージはハイフン ``-`` でもアンダースコア ``_`` でも使うこと" +"ができます。また、 :ref:`名前空間パッケージ ` " +"のサブパッケージをパッケージングするために使われることがあるドット ``.`` を含" +"むこともできます。ほとんどの目的においては、大文字小文字や ``-`` 対 ``_`` の" +"違いをを区別せず、例えば、 ``pip install Awesome_Package`` と ``pip install " +"awesome-package`` は同じものです (詳細な規則は :ref:`名前正規化仕様 ` にあります) 。" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" +"正当な Python 識別子をその名称として持たないパッケージ/モジュールをインストー" +"ルすることは、 :doc:`importlib ` を使うことで技術的" +"には可能ではありますが、絶無と言って良いほど稀であり、強く抑制されています。" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "下流のパッケージングをサポートする" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "ドラフト" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "2025-?" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" +"PyPI および :ref:`pip` のような Python のパッケージングツールは、Python パッ" +"ケージを配布する主要な手段ですが、その一方で、しばしば他のパッケージングエコ" +"システムの一部として利用可能にされています。これらの再パッケージングの努力" +"は、*ダウンストリーム* パッケージングと総称され (対して元の方は *アップスト" +"リーム* パッケージングと総称されます)、 Linux ディストロ・Conda・Homebrew・" +"MacPorts といったプロジェクトが (訳註：ダウンストリームパッケージングに) 該当" +"します。これらは、一般的には、 Python パッケージングツール単独では取り扱えな" +"いようなユースケースをよりよくサポートすること、例えば、特定のオペレーティン" +"グシステムとの間でネイティブな統合をすることや、非 Python ソフトウェアの特定" +"のバージョンとの互換性を保証することを目指しています。" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" +"この議論では、ダウンストリームパッケージングが通常どのように行われるのか、お" +"よび、ダウンストリームパッケージングが直面する追加的なチャレンジがどのような" +"ものであるかを説明することを試みます。 (アップストリームプロジェクトを保守す" +"る上で何らかの大きな追加作業を招来しない範囲で) ダウンストリームパッケージン" +"グを *劇的に* 簡単なものにするような、プロジェクトの保守者が追随することを選" +"択してもよいいくつかの選択可能なガイドラインを提供することを目指しています。" +"これが全部採用するかまったく採用しないかという提案ではないことを銘記してくだ" +"さい -- アップストリーム側の保守者が為し得ることは、たとえそれが小さな部分だ" +"けだったとしても、すべて役に立ちます。ダウンストリーム側の保守者もこれらの問" +"題を解決するためのパッチを提供することに意欲的です。他のダウンストリーム群が" +"パッチを作成してリベースし続ける必要を取り除くことや、同じ問題に対して一貫性" +"のない解決策を適用するリスクを取り除くことができるので、このようなパッチを" +"マージすることは非常に助けになります。" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" +"ソフトウェアの保守者達とダウンストリームのパッケージ作業者の間の良い関係を確" +"立することは、相互に利益をもたらします。ダウンストリーム側は、しばしば、パッ" +"ケージを改良するために彼らの経験・時間・ハードウェアを共有したいと望み、そう" +"しなければ獲得するのに多大な労力を必要とする他パッケージとの関係について情報" +"を提供したいと望んでいます。パッケージ作業者は、しばしば、プロダクションレベ" +"ルになった後でユーザがそのバグを踏むよりも前に、高品質のバグレポートを提供" +"し、可能な時ならいつでもパッチを供給します。例えば、彼らは、新しい Python の" +"バージョンがリリースされた時に起きる互換性問題のいずれについても、彼らが再配" +"布するパッケージがアップデートされていることを確実にすることに恒常的に活発で" +"す。" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" +"ダウンストリームのビルドには、バイナリ形式での再配布だけでなく、 (例えば、" +"Gentoo Linux のようなソースコードありきのディストロで) ユーザ側のシステムで行" +"われるソースビルドも含まれることを銘記してください。" + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "完全な形のソースコード配布物を提供する" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "なぜ？" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" +"ダウンストリームのパッケージ作業者の大多数は、アップストリーム側が提供するバ" +"イナリのパッケージを使ってやるよりも、ソースコードからパッケージをビルドする" +"ことを好みます。いくつかの場合には、パッケージを配布物に同梱してもらうために" +"ソースコードを使うことが要求されていることもあります。これは、また、汎用 " +" の wheel を提供する純 Python のパッケージにも当てはまります。ソー" +"スコード配布物を用いる理由には次のようなものがあるでしょう:" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "すべてのパッケージのソースコードを監査することができるようにするため。" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" +"試験一式を動作させることができるようにし、また、説明文書をビルドすることがで" +"きるようにするため。" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" +"プロジェクトのリポジトリからのバックポートされたコミットを含めてパッチの適用" +"が容易にできるようにするため、また、逆にプロジェクトへパッチを送ることができ" +"るようにするため。" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" +"アップストリームのビルドではカバーされていない特定のプラットフォームでのビル" +"ドができるようにするため。" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" +"システムのライブラリの特定のバージョンに対してビルドができるようにするため。" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" +"すべての Python パッケージを通じて守備一貫したビルドプロセスを保持するため。" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" +"通常は、 Git リポジトリからパッケージをビルドすることができますが、代わりに静" +"的なアーカイブファイルを提供する重要ないくつかの理由があります:" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" +"単一のファイルをダウンロードする方が、より効率が良く、より信頼できて、例えば " +"Git clone を使うよりも良くサポートされていることがしばしばです。これによっ" +"て、貧弱なインターネット接続性の元にあるユーザを助けることができます。" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" +"ダウンストリーム側は、引き続くビルドに用いるためのソースファイルの真正性を検" +"証するために、時を経てもビット単位で同一であることを要求するハッシュ値を使う" +"ことがしばしばあります。例えば、仮にサーバ上の gzip がアップグレードされれ" +"ば、圧縮されたデータが変化するかもしれないので、自動的に作成される Git アーカ" +"イブはこのようなことを保証しません。" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" +"アーカイブファイルはミラーサイトにおくことも可能で、アップストリームとダウン" +"ストリームの両方の帯域幅を節約することができます。実際のビルドは、ローカルミ" +"ラーまたは前もって再配布を受けたソースファイル群にしかアクセスが提供されない" +"ファイアウォールの内側もしくはオフラインの環境下で後から実行することが可能で" +"す。" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" +"明示的にアーカイブファイルを公開することで、そのソースコードアーカイブが作成" +"された時点でバージョン管理システムのメタデータに関する依存関係がすべて解決さ" +"れていたことを保証することができます。例えば、自動的に生成される Git アーカイ" +"ブはコミットタグ情報をすべて削除していて、そのビルドに必要なバージョン情報の" +"詳細が不正確になっている可能性があります。" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "どのように？" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" +"理想的には、 ** PyPI上で公開されたソースコード配布物のアーカイブには、その" +"パッケージの Git リポジトリのファイルを全て含み ** 、それらのファイル群から" +"パッケージ自体をビルドし、テストスイートを走らせ、説明文書をインストールする" +"ために必要なファイルや、シェル補完やエディタ用のサポートファイルなどエンド" +"ユーザにとって役に立つかもしれない他のファイルを全て含めるべきです。" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" +"この点は、パッケージそれ自体に属するファイル群にだけ適用します。Python のパッ" +"ケージ管理機構に極めてよく似ていますが、ダウンストリームパッケージの処理で" +"は、必要な Python の依存関係や、そのパッケージとそのビルドスクリプトが必要と" +"するシステムツールや外部のライブラリの依存関係を提供します。しかしながら、ダ" +"ウンストリーム側が必要な依存関係を決定し、それらの変更をチェックするために、" +"これらの依存関係を列挙するファイル (例えば ``requirements*.txt`` ファイル) も" +"また同梱されるべきです。" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" +"プロジェクトによっては、PyPI からのソースコード配布物を使う Python パッケージ" +"管理機構に関して心配する場合があります。彼らとしては、特定のプロジェクトを" +"ソースコードからビルドするという問題含みではっきりと機能しないことがわかって" +"いる代替策を有効にすることになるので、これらのツール類によって使われることの" +"ないファイル群で彼らのパッケージのサイズが増えることを望まなかったり、ソース" +"コード配布物を公開することを全く望まなかったりするのです。" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" +"他方で、(例えば NumPy_ のような) いくつかのプロジェクトでは、そのインストール" +"パッケージの中にテストスイートを同梱することに決めたものがあります。これに" +"よって、そのようなパッケージをインストールした後に、例えば依存先のパッケージ" +"をアップグレードした後にリグレッション (退行)がないかどうかの確認を行うため" +"に、ユーザがテストスイートを走らせることを許すという利点を追加することができ" +"ます。さらに別のやり方としては、テストスイートやテストデータを別の Python " +"パッケージに分割する方法があります。そのような方法は、巨大なテストベクトルを " +"cryptography-vectors_package に分離する形で、 cryptography_project で採用され" +"ています。" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" +"リリースの際のワークフローでソースコード配布物を用いるのは良い考えです。例え" +"ば、 :ref:`build` ツールは正にそれをやります -- まずソースコード配布物をビル" +"ドし、それを使って wheel をビルドするのです。これによって、ソースコード配布物" +"が実際に動作することを確実にし、誤って公式の wheel よりも数の少ないファイル群" +"をインストールしてしまうことがなくなります。" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" +"理想的には、テストスイートを走らせたり説明文書をビルドしたりといったことや、" +"全ての必要なファイルが実際に含まれていることを確実にする特殊なテストを追加す" +"るのに、ソースコード配布物も使いましょう。当然のことですが、これはより多くの" +"努力を必要としますので、こうしなくても問題はありません -- ダウンストリームの" +"パッケージ作業者たちが素早く不足しているファイルを報告してくれるでしょう。" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "ビルドプロセスの最中にインターネットを使うことはやめましょう" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" +"ダウンストリームのビルドは、しばしば、インターネットにアクセスすることができ" +"ないサンドボックス化された環境の中で行われます。パッケージのソースファイルが" +"この環境内に展開され、必要な全ての依存関係がインストールされます。" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" +"仮にこれが当てはまらない場合でも、適切にダウンロードを認証するために十分な注" +"意を払っていたものと仮定して、インターネットを使うことはいくつもの理由から推" +"奨されません:" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" +"インターネット接続は (例えば受信状態が悪いために) 不安定であるかもしれません" +"し、プロセスを失敗させたりハングさせたりしかねない一時的な問題の影響を受ける" +"かもしれません。" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" +"リモートにあるリソース群は、もはやビルドができなくなるような形で、一時的また" +"は永続的に利用不可能になるかもしれません。これは、特に、誰かが古いバージョン" +"のパッケージをビルドする必要に迫られた時に問題となります。" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" +"リモートのリソース群は、ビルドが再現可能にならない形に変化するかもしれませ" +"ん。" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" +"リモートのサーバにアクセスすることは、当該システムでそのパッケージをビルドし" +"ていることに関する情報を暴露するので、プライバシー問題と潜在的なセキュリティ" +"問題をもたらします。" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" +"ユーザは、制御下にないインターネットアクセスが追加料金やその他の不都合に帰結" +"してしまう、そのようなデータ量に制約のある通信サービスを使っているかもしれま" +"せん。" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" +"パッケージが、例えば売り物の依存関係を自動的にダウンロードしたり、Git のサブ" +"モジュールをフェッチしたりするような、そのようなインターネットを使用する何ら" +"かのカスタムビルド *バックエンド* 動作を実装しているなら、そのソースコード配" +"布物は、これらのファイル群をすべて同梱するか、別途準備することができるように" +"するかのいずれかをするべきで、ファイル群がすでに存在する場合にはインターネッ" +"トを使用しないようにしなければなりません。" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" +"この点は、パッケージのメタデータの中で指定された Python の依存関係には当ては" +"まらないということ、また、それらは (:ref:`build` や :ref:`pip` のような) *フ" +"ロントエンド* によるビルドやインストールのプロセスの最中にフェッチされるとい" +"うことに注意してください。ダウンストリーム側では、Python の依存関係をローカル" +"に準備するようなフロントエンドを使います。" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" +"理想的には、カスタムビルド用スクリプトは、明示的に要求された場合を除いて、イ" +"ンターネットへのアクセスを試みることさえ全く行うべきでありません。もし、何ら" +"かのリソースが不足していてフェッチする必要があるなら、まずユーザに許可を求め" +"るべきです。それが実現不可能であれば、次善の策は、あらゆるインターネットアク" +"セスをさせないというオプトアウトのスイッチを提供するべきです。これは、例えば " +"``NO_NETWORK`` 環境変数が空でない値に設定されているか否かを調べることで行うこ" +"とができます。" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" +"ダウンストリームは、しばしばテストを走らせたり説明文書をビルドしたりしますの" +"で、理想的を言えば、上記のことはこれらのプロセスにも同様に拡大適用されるべき" +"です。" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" +"もし、リモートのリソースをフェッチするのであれば、悪意ある第三者がファイルを" +"置換しているという事態から保護するために、 (通常はハッシュ値を使って) 絶対に " +"*その真正性を検証* しなければならないことも覚えておいてください。" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "システムの依存関係に対してビルドすることをサポートする" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" +"Python プロジェクトの中には、 C や C++ で書かれたライブラリのような非 Python " +"の依存関係を持つものがあります。アップストリームパッケージング内でこのような" +"依存関係のシステムバージョンを使おうとする試行は、エンドユーザに多数の問題を" +"もたらすかもしれません:" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" +"公開された wheel は、使っているライブラリのバイナリ互換のバージョンがユーザの" +"システム上に存在することを要求します。もし、ライブラリが不足していたり非互換" +"のバージョンがインストールされていたりすると、 Python パッケージは、経験豊か" +"とは言えないユーザにとっては明晰でないエラーを伴って失敗するかもしれません" +"し、動作時に誤動作することさえあるかもしれません。" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" +"ソースコード配布物からのビルドには、ソースコードレベルで互換性のあるバージョ" +"ンの依存関係先が、システムによってはライブラリ本体とは別のパッケージとして用" +"意されていることがある、開発用のヘッダーファイルやその他の補助ファイルと共" +"に、存在していることが要求されます。" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" +"経験を積んだユーザにとってさえ、互換性のある依存関係先のバージョンをインス" +"トールすることは極めて難しかもしれません。例えば、使っている Linux ディストロ" +"が要求されているバージョンを提供していないこともあり得るし、他のパッケージが" +"互換性のないバージョンのものを要求しているかもしれません。" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" +"Python パッケージとそのシステム依存関係の間の関連性は、パッケージングシステム" +"によって記録されているということはありません。次回のシステム更新がライブラリ" +"を、 Python パッケージとのバイナリ互換性を破壊するような、より新しいバージョ" +"ンへとアップグレードするかもしれず、ユーザが修復のために介入することが要求さ" +"れるかもしれません。" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" +"これらの理由は、依存関係先を静的にリンクするか、インストールされるパッケージ" +"の中にローカルコピーを用意するかのいずれかに決める合理的な理由になります。" +"ソースコード配布物の中にも依存関係先を含めることもあるかもしれません。時に、" +"これらの依存関係先もまた PyPI でパッケージされていて、他のすべての Python " +"パッケージのように、プロジェクトの依存関係先として宣言され得ることもありま" +"す。" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" +"しかしながら、これらの課題のどれひとつを取ってもそれはダウンストリームのパッ" +"ケージングには当てはまらず、ダウンストリーム側ではシステムの依存関係に直接に" +"リンクする方を好む十分な理由があります。とりわけ次のような場合:" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" +"多くのケースでは、部品間で動的な依存関係を信頼できる形で共有することが、ダウ" +"ンストリーム側のパッケージングエコシステムの *目的* の大きな部分を占めていま" +"す。それをサポートするのを補助することは、そのようなシステムのユーザが好まし" +"いフォーマットでアップストリームのプロジェクトにアクセスすることをより容易に" +"します。" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" +"静的なリンキングと提供は、その出自の検証が難しくなるので、外部への依存関係の" +"使用をわかりにくくします。" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" +"動的なリンキングは、ダウンストリームのパッケージングエコシステム全体で使用さ" +"れるライブラリを素早く体系的に置き換えることができるようにしますが、それは、" +"セキュリティ上の脆弱性や致命的なバグを含んでいることが判明した時には特に重要" +"になり得ます。" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" +"システムの依存関係を使うことで、ダウンストリーム保守者が様々なパッケージ内で" +"提供される依存関係に統一的にパッチしなければならないということがない形で、特" +"定のプラットフォーム上でユーザ経験を改善し得るところのダウンストリームでのカ" +"スタマイゼーションからの利益をパッケージにもたらします。これは、互換性の向上" +"やセキュリティハードニングを含み得ます。" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" +"静的なリンキングとベンダーリングによって、同一ライブラリの複数の異なるバー" +"ジョンが同じプロセスの中でロードされ得ます (例えば、同じライブラリの別バー" +"ジョンにリンクしたふたつの Python パッケージを import しようと試みた場合) 。" +"ある時には、事件にならずに動作しますが、ライブラリのローディングエラーに起因" +"する問題や、微妙な動作中のバグや、 (突然クラッシュしてデータを失うといった) " +"壊滅的な失敗へと至ることもあり得ます。" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" +"最後ではあるが最も軽微といういうわけではありませんが、静的なリンキングとベン" +"ダーリングの結果として重複が起きて、ディスクスペースとメモリの両方を余計に使" +"うことになります。" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" +"双方のニーズの間の良い妥協点は、ベンダード (訳註：パッケージ側が準備したもの" +"の意か) のものを使うかシステムの依存関係を使うかを切り替えるスイッチを提供す" +"ることです。理想的には、パッケージ側が複数の独自の依存関係を持つならば、それ" +"ぞれの依存関係について独立したスイッチを提供するべきで、かつ、例えば " +"``USE_SYSTEM_DEPS`` 環境変数のようにデフォルト設定を制御する一般的なスイッチ" +"をも持つべきです。" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" +"ユーザがシステム側の依存関係を使うことを要求していて、特定の依存関係が存在し" +"ないか非互換である場合には、ビルドは、ベンダードのバージョンにフォールバック" +"するよりも説明的なメッセージと共に失敗するべきです。これによって、パッケージ" +"製作者が誤りに気付き、どのように解決するかを意識して解決する機会を得ることが" +"できます。" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" +"アップストリーム側プロジェクトが、システム側の依存関係を使ってビルドする *テ" +"スト* をダウンストリーム側の再パッケージ作業者に残しておくことは合理的です。" +"これらのガイドラインのゴールは、アップストリーム側プロジェクトとダウンスト" +"リーム側再パッケージ作業者の間の協調作業がより効率的になるようにお膳立てする" +"ことであって、ダウンストリーム側再パッケージ作業者がよりよく取り扱えるように" +"装備を整えるというタスクをアップストリーム側プロジェクトが分担するようにと示" +"唆するものではありません。" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "ダウンストリーム側のテストをサポートする" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" +"さまざまなダウンストリームプロジェクトが、何らかの形でパッケージ済みの " +"Python プロジェクトのテストを走らせています。これは、それぞれのケースに依っ" +"て、最低限のスモークテストからテストスイートを隅から隅まで網羅的に行うところ" +"までの幅を持ちます。こうしたことを行うにはさまざまな理由があり得ます:" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" +"ダウンストリームのパッケージングがどんなバグも持ち込まないようにするために検" +"証すること。" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" +"アップストリームのテストではカバーされていない追加的なプラットフォームでのテ" +"ストを行うこと。" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" +"特定のハードウェアやシステムパッケージのバージョンといったものだけで再現し得" +"る些細なバグを探索すること。" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" +"アップストリーム側でのリリース時のテストで使われたものに比べて、より新しい " +"(またはより古い) 依存先バージョンに対してリリース済パッケージをテストするこ" +"と。" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" +"本番構成に非常によく似た環境でパッケージをテストすること。これによって、パッ" +"ケージ自身の依存関係先ではないパッケージを含めて、異なるインストール済パッ" +"ケージとの間の自明でない相互作用によって引き起こされる問題点を検出することが" +"できます。" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" +"リリースされたパッケージを、 (ポイントリリースを含めて) より新しい Python の" +"バージョンや、よりテストされていない PyPy のような Python 実装に対してテスト" +"すること。" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" +"確かに、ダウンストリーム側でテストを行うと、偽陽性や、アップストリーム側プロ" +"ジェクトがサポートする上で興味を持たないようなシナリオについてのバグ報告を生" +"み出すかもしれません。しかしながら、おそらく、もっとよくあるのは、問題に関す" +"る早期の気付きを得たり、発見できなければアップストリーム側プロジェクトのユー" +"ザにとっての問題を引き起こしたであろう非自明のバグを発見したりということで" +"しょう。過誤は起きるものですが、ダウンストリーム側パッケージ作業者の大半は、" +"結果をダブルチェックすることに最善の努力を行っていますし、自分たちが報告した" +"バグをアップストリーム側の保守者が優先順位を付けて修正することを助けます。" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" +"ダウンストリーム側の再パッケージ作業者がそのパッケージを効率よく効果的にテス" +"トするのを助けるために、アップストリーム側プロジェクトができることは、すでに" +"上述した示唆のいくつかを含めて沢山あります。これらは、典型的には、テストス" +"イートが誰にとってもより信頼できて簡単に使えるようにするような改善です。いく" +"つかの特定の示唆は:" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" +"テストファイルと必要品はソースコード配布物の中に含めておくか、簡単に個別にダ" +"ウンロードできるようにしておきましょう。" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" +"テストを実行している間は、パッケージのディレクトリに書き込んではいけません。" +"ダウンストリーム側のテスト構成は、インストールパッケージのトップディレクトリ" +"で実行される場合があり、テスト実行中の修正や一時的なテストファイルがインス" +"トールパッケージの一部となってしまうかもしれません！" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" +"テストスイートがオフラインで動作するように作ってください。 responses_ や " +"vcrpy_ のようなパッケージを使って、ネットワークとの相互作用を疑似的に行ってく" +"ださい。もし可能であれば、たとえば pytest_ マーカを経由するなどして、インター" +"ネットアクセスを伴うテストを簡単に無効にできるようにしてください。テストがオ" +"フラインで動作可能であることを検証するには、 pytest-socket_ を使ってくださ" +"い。このようにすることで、テストワークフローがより素早く、かつ、より信頼でき" +"る形で実行できるようになります。" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" +"テストが特別な設定なしで動作するようにするか、または、必要な設定をテストの必" +"要物の一部として行うようにしましょう。データベースのようなシステム側のサービ" +"スに接続することができるとは絶対に仮定しないでください -- とんでもない場合に" +"は、供用中のサービスをクラッシュさせるかもしれませんよ！" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" +"パッケージがオプションの依存関係を持つなら、その部分のテストもまたオプション" +"にしましょう。必要なパッケージがインストールされていなければ、そのようなテス" +"トをスキップするか、簡単に選択外にすることができるようなマーカを追加しましょ" +"う。" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" +"もっと一般的に、特別な要求事項を伴うテストにはマーカを付けましょう。これに" +"は、例えば、相当な記憶スペースを使用する、相当なメモリを使用する、長時間を要" +"する、並行でテストを走らせることができない、などが含まれます。" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" +"テストスイートが ``-Werror`` 付きで実行されるであろうと仮定してはなりません。" +"それは、例えばより新しい依存関係のバージョンなどのせいで偽陽性を引き起こすの" +"で、往々にしてダウンストリーム側では無効にする必要があります。 " +"``pytest.raises()`` を使うよりも ``pytest.warns()`` を使って警告をアサートし" +"てください！" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" +"テストスイートが信頼できて再現可能なものになることを目指しましょう。当てにな" +"らないテストを避けましょう。浮動小数点計算や操作のタイミングの結果をそのまま" +"信頼することなど、特別なプラットフォームの細部に依存するものを避けましょう。" +"ファジングには利点もありますが、完全性を期すための静的なテストも持っておきた" +"いでしょう。" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" +"その目的に従ってテストを分割し、重要でないカテゴリや問題含みのカテゴリを簡単" +"にスキップできるようにしましょう。ダウンストリーム側でのテストの一義的な目的" +"は、そのパッケージ自体が動作することを保証することであって、一般的に、ダウン" +"ストリーム側ではコードカバー率・コードフォーマット・型チェックやベンチマーク" +"するというようなタスクには興味がありません。パッケージ自体に実際に影響を与え" +"ることはなくとも、依存関係先がアップグレードされたりシステムが高負荷下にあっ" +"たりするとこれらのテストが失敗する可能性があります。" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" +"テストスイートの実行に非常に長い時間がかかるなら、並行テストをサポートしま" +"しょう。ダウンストリーム側は、しばしば、多数のパッケージを維持管理していて、" +"それらを全てテストするには長い時間がかかります。ボトルネックを避けるには、 " +"pytest-xdist_ を使うことが助けとなるでしょう。" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" +"理想としては、テストスイートを ``pytest``を通じて走らせることをサポートしてく" +"ださい。 pytest_ は、テストを便利に非選択にしたり、当てにならないテストを " +"(pytest-rerunfailures_を通じて) 再実行したり、テストがハングアップしてしまう" +"のを防ぐためのタイムアウトを (pytest-timeout_ を通じて) 追加したり、 (pytest-" +"xdist_ を通じて) テストを並行して走らせたり、といったダウンストリーム側に真に" +"役立つ多くのコマンドライン引数を持っています。テストスイートが ``pytest`` と" +"一緒に *書かれている* ことや ``pytest`` と一緒に *実行される* 必要はないこと" +"を覚えておいてください: ``pytest`` は、標準ライブラリの ``unittest`` テスト探" +"索と互換性のあるほぼ全てのテストケースを探索して実行することができます。" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "安定版リリースの目的" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" +"多くのダウンストリームは、メインのパッケージストリームに加えて、ステーブルリ" +"リースチャンネルを提供しています。このようなチャンネルのゴールは、より高い安" +"定性を必要とするユーザ向けに、より保守的なアップグレードを提供することです。" +"このようなユーザは、しばしば、最新の機能を得ることよりも、問題発生のリスクが" +"より低いことを選択することを好みます。" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" +"正確にはポリシーはそれぞれに異なりますが、新しいバージョンのパッケージをス" +"テーブルリリースチャンネルに取り込む際の重要な評価基準は、すでに幾らかの時間" +"をかけてテストが行われているものを利用可能にする、既知の大きな手戻りがない、" +"ということです。例えば、 Gentoo Linux では、あるパッケージがステーブルである" +"と印をつけられるのは一ヶ月間のテストが行われた後であり、その時点で依存関係先" +"のパッケージ群がステーブルであるバージョンを使ってテストされていることです。" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" +"しかしながら、もっと素早い行動が要求される状況もあります。例えば、ステーブル" +"チャンネルで現に利用可能になっているバージョンにセキュリティ上の脆弱性や大き" +"なバグが発見された場合、ダウンストリーム側はそれを解決する必要に直面します。" +"このような場合には、以下のようなさまざまな選択肢を考慮の対象とする必要があり" +"ます:" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "新しいバージョンをステーブルチャンネルに早期に送り、" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "その時点で公開されているバージョンにパッチを追加し、" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" +"あるいは、ステーブルチャンネルを以前のリリースへとダウングレードさえも行う。" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" +"これらのオプションは、それぞれ、それなりのリスクとそれなりの作業量を伴うもの" +"であり、パッケージ作業者はアクションの方向性を決定するために重み付けを行う必" +"要があります。" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" +"ステーブルリリースチャンネル向けのワークフローを調整するためにアップストリー" +"ム側ができることがいくつかあります。これらのアクションは、しばしば、パッケー" +"ジのユーザにも恩恵を与えます。いくつかの具体的な示唆が続きます:" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" +"リリースの頻度をコード変更の割合に適合させましょう。稀にしかリリースされない" +"パッケージは、しばしば、毎回のリリースに巨大な変更を持ち込み、偶発的な手戻り" +"のリスクを高めます。" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" +"可能であれば、バグ修正と新機能を混ぜないようにしましょう。とりわけ、既知のバ" +"グ修正がすでにマージされているなら、機能ブランチをマージする前に新しいリリー" +"スを行うことを検討しましょう。" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" +"大きな変更の後には、ユーザやダウンストリーム側が自発的に参加するような試験の" +"機会をより多く提供するために、プレリリースを作ることを検討しましょう。" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" +"プロジェクトが集中した開発を必要とするのであれば、より保守的なコミットだけを" +"含むブランチを分岐させて、個別にリリースを行うことを検討しましょう。例えば、" +"現状では、 Django_ は main ブランチに加えて３個のリリースブランチを維持してい" +"ます。" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" +"追加のブランチを恒常的に維持していくことを望まない場合であってさえ、特にセ" +"キュリティ上の脆弱性が発見された時には、以前のバージョンに最低限の変更を加え" +"たパッチリリースを追加することを検討しましょう。" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" +"必要となればそれ以前のリリース用にチェリーピッキングした変更を取り込みやすく" +"なるように、変更は、ある時点でひとつの問題に対処することに焦点を当てたコミッ" +"トに分割しましょう。" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" +"**議論型文書**は、特定の話題について網羅的な情報を提供することに重点を置いて" +"います。もしあなたがとにかく何かを終わらせようとしているだけなら、:doc:`/" +"guides/index`を見た方が良いでしょう。" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "install_requiresかrequirementsか" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" +"``install_requires`` は :ref:`setuptools` :file:`setup.py` のキーワードで、そ" +"のプロジェクトが正しく動作するために必要な **最小限** のものを指定するもので" +"す。プロジェクトが :ref:`pip` でインストールされた場合には、プロジェクトが依" +"存するパッケージをインストールするのに用いられます。" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" +"例えば、プロジェクトがAとBに依存しているなら、 ``install_requires`` は次のよ" +"うになるでしょう：" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" +"さらに、下限や上限がわかっているなら、それを示しておくことがベストプラクティ" +"スです。" + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" +"例えば、あなたのプロジェクトが少なくともv1の'A'と少なくともv2の'B'を必要とす" +"るとわかっているなら、次のようになるでしょう：" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" +"また、プロジェクト 'A' が v2 になる時にある変更を行なったために、あなたのプロ" +"ジェクトと 'A' の v2 以降のバージョンとの間の互換性が失われるであろうという場" +"合には、 v2 を許容しないことが筋の通ったことになるでしょう。" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" +"依存関係にあるものを特定のバージョンに固定するために、あるいは、さらなる依存" +"関係(すなわち、あなたの依存先が依存するもの)を指定するために " +"``install_requires`` を使うことはベストプラクティスとは考えられていません。こ" +"れは過剰に制限的であり、依存関係にあるものをまとめて更新することからユーザが" +"得られる利益を阻害するものと考えられています。" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" +"最後に、 ``install_requires`` が必要事項の「要約」のリスト、つまり、単に必要" +"事項の名前とバージョンが要求されるだけあって、どこから(すなわち、どんな索引や" +"情報源から)充当するのかについては要求していないのだということを理解することは" +"重要です。どこから(すなわち、どのようにして「具体化」されるのか)という点につ" +"いては、 :ref:`pip` のオプションを使ってインストール時に決定されるのです。" +"[1]_" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "Requirementsファイル" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" +":ref:`Requirementsファイル ` は、一番簡単にいうなら" +"ば、 :ref:`pip:pip install` の引数のリストをファイルに書いただけのものです。" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" +"``install_requires`` が単一のプロジェクトにおける依存関係を定義する一方" +"で、 :ref:`Requirements Files ` はPython環境全体に対" +"する要求事項を定義するのにしばしば用いられます。" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" +"``install_requires`` での要求事項が最小限のものである一方で、requirementsファ" +"イルは再現可能な形で環境全体をインストールできるようにする :ref:`repeatable " +"installations ` という目的に沿って限定されたバージョンの網" +"羅的なリストを含むことがしばしばです。" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" +"``install_requires``での要求事項が「要約」、すなわち特定の索引には紐づけられ" +"ていないのに対して、requirementsファイルではしばしば``--index-url``や``--" +"find-links``のようなpipのオプションが含まれていて特定の索引やパッケージ登録簿" +"に紐づけられた「具体的な」要求事項になっています。[1]_" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" +"``install_requires``では、メタデータがインストール中にpipによって自動的に解析" +"される一方、requirementsファイルではそうではなく、``python -m pip install " +"-r``を使ってユーザが明示的にインストールする時に使われるだけです。" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" +"要求事項が「要約」か「具体的」かの議論についてもっと知りたい場合は、https://" +"caremad.io/posts/2013/07/setup-vs-requirement/をご覧ください。" + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "パッケージフォーマット" + +#: ../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 "" +"このページでは、 Python パッケージの配布に使われるファイルフォーマット群とそ" +"の相違点について議論します。" + +#: ../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 "" +"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/package-formats.rst:21 +msgid "What is a source distribution?" +msgstr "ソースコード配布物とは何か？" + +#: ../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 "" +"概念としては、ソースコード配布物は生の形のソースコードをアーカイブしたもので" +"す。具体的に言うと、sdist は、ソースコードに加えて、プロジェクトのメタデータ" +"を保持する ``PKG-INFO`` と言う名の特別なファイルをアーカイブした ``.tar.gz`` " +"ファイルです。このファイルの存在によってメタデータを自分自身で計算しなくても" +"済むようにすることでパッケージングツール群を補助しています。 ``PKG-INFO`` " +"ファイルは、 :ref:`コアとなるメタデータ ` で指定されたフォー" +"マットに従うもので、人の手で書くことが想定されていないものです [#core-" +"metadata-format]_ 。" + +#: ../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/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/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/package-formats.rst:50 +msgid "" +"If you want technical details on the sdist format, read the :ref:`sdist " +"specification `." +msgstr "" +"sdist 形式の技術的な詳細を知りたければ、 :ref:`sdist 仕様 ` を見てください。" + +#: ../source/discussions/package-formats.rst:55 +msgid "What is a wheel?" +msgstr "wheel とは何か？" + +#: ../source/discussions/package-formats.rst:57 +msgid "" +"Conceptually, a wheel contains exactly the files that need to be copied when " +"installing the package." +msgstr "" +"概念としては、 wheel は、パッケージをインストールする際にコピーされる必要のあ" +"るファイル群をそのまま含んでいるものです。" + +#: ../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 "" +"プラットフォームに依存した機械語にコンパイルする必要がある C や C++ や Rust " +"のようなコンパイル言語で書かれた :term:`拡張モジュール ` を" +"伴うパッケージにおいては、sdist と wheel の間には大きな違いがあります。このよ" +"うなパッケージでは、 wheel は (C言語のソースのような) ソースコードを内包して" +"おらず、代わりに (Linux における ``.so`` ファイルや Windows における DLL のよ" +"うな) コンパイル済みで実行可能なコードを含んでいます。" + +#: ../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 "" +"さらにまた、あるバージョンのプロジェクトには sdist がひとつしか存在しない一方" +"で、wheel はたくさんあるかもしれません。繰り返しになりますが、これは拡張モ" +"ジュールの文脈でもっとも有りがちなことです。拡張モジュールのコンパイル済みの" +"コードはオペレーティングシステムとプロセッサーアーキテクチャに、また、 " +"(:ref:`Python stable ABI ` を使っていなければ) しばしば " +"Python インタープリタのバージョンに紐付いています。" + +#: ../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 "" +"純 Python のパッケージでは、 sdist と wheel の差異はあまり顕著ではありませ" +"ん。普通は、あらゆるプラットフォームと Python のバージョン向けに wheel がたっ" +"たひとつ存在します。 Python はインタープリタ言語であり、事前にコンパイルして" +"おく必要がなく、それゆえに wheel は sdist と同様に ``.py`` ファイル群を内包し" +"ているのです。" + +#: ../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 "" +"``.pyc`` バイトコードファイル群: これらは wheel には含まれていませんが、これ" +"らについて不思議に思っているなら、これらは安価に生成することができ、また、も" +"しこれをパッケージに含めるとすれば、単一の wheel を配布する代わりに、Python " +"のバージョン毎に巨大な数のパッケージを配布するという不必要なことを強いられる" +"ことになるでしょう。代わりに、 :ref:`pip` のようなインストーラがインストール" +"中に生成しています。" + +#: ../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 "" +"そうは言っても、たとえ純 Python のプロジェクトであったとしても、 sdist と " +"wheel の間には依然として重要な違いがあります。 wheel は、インストールされるも" +"のだけを正確に含むように、それ以外のものは含まないようにと意図して作られてい" +"ます。とりわけ、 wheel にはテストや説明文書を決して含めるべきではありません" +"が、他方で sdist では普通はこれらを含みます。また、 wheel のフォーマットは " +"sdist のものよりもより複雑です。例えば、wheel にはある特別なファイル -- " +"``RECORD`` と呼ばれます -- が含まれていて、このファイルには wheel 内の他のす" +"べてのファイルのハッシュ値付きのリストが含まれており、安全性の確認やダウン" +"ロードの際の完全性の確認に使われます。" + +#: ../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 "" +"一見したところでは、 wheel こそが \"単純かつ基本的な\" 純 Python プロジェクト" +"に必要なものではないかと思うかもしれません。 sdist の自由度が大きいために " +"pip のようなインストーラは sdist から直接にインストールすることができないとい" +"うことを覚えておいてください -- まず sdist が指定する :term:`ビルドバックエン" +"ド ` を起動することで (ビルドバックエンドはビルドして wheel を" +"作成している間に C 言語拡張のコンパイルのようなあらゆる種類の変形をすべて行い" +"ます) wheel をビルドする必要があるのです。こう言う理由で、たとえ純 Python の" +"プロジェクトであっても、PyPI やその他のパッケージインデックスには常に sdist " +"と wheel の *両方* をアップロードしておくべきなのです。こうすることで、wheel " +"なら直接にインストールできるので、ユーザにとってはインストールがとても素早く" +"行えることになります。インストールされるファイルだけを含むという wheel の性質" +"は、ダウンロードのサイズが小さくなることにもつながります。" + +#: ../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 "" +"技術的なレベルでは、 wheel は (sdist が TAR アーカイブであるのとは違って) " +"ZIP アーカイブです。例えば Linux や macOS のような UNIX 系プラットフォームな" +"ら ``unzip`` 、 Windows 上の PowerShell 内なら ``Expand-Archive`` 、あるいは " +"Python の zipfile モジュールのコマンドライン ` を" +"使って通常の ZIP アーカイブとして展開することで、内容を検査することができま" +"す。これは、 wheel ファイルが必要なすべてのファイルを内包していることを確認す" +"るのにとても便利です。" + +#: ../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 "" +"wheel の中には、パッケージのファイル群と :samp:`{package_name}-" +"{version}.dist-info` と呼ばれる追加のディレクトリがあります。このディレクトリ" +"には、 sdist における ``PKG-INFO`` に相当する ``METADATA`` ファイルや " +"``RECORD`` などのさまざまなファイルを含みます。これは、wheel 内のファイルがひ" +"とつも欠けていないことを保証するのに役立ちます。" + +#: ../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 "" +"wheel のファイル名は (ほとんど使われることのない幾つかの機能を除けば) このよ" +"うに見えます: :samp:`{package_name}-{version}-{python_tag}-{abi_tag}-" +"{platform_tag}.whl` 。この命名規則によって、その wheel がどのプラットフォーム" +"でどの Python バージョンと互換性を持つのかを識別することができます。例えば、 " +"``pip-23.3.1-py3-none-any.whl`` という名前は次のことを意味します:" + +#: ../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 "" +"(``py3``) CPython、最も広く使われている Python 実装、あるいは PyPy_ のような" +"代替実装でも、 Python 3 の実装があればどこでも、この wheel をインストールする" +"ことができます;" + +#: ../source/discussions/package-formats.rst:124 +msgid "(``none``) It does not depend on the Python version;" +msgstr "(``none``) Python のバージョンには依存しません;" + +#: ../source/discussions/package-formats.rst:125 +msgid "(``any``) It does not depend on the platform." +msgstr "(``any``) プラットフォームには依存しません。" + +#: ../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 "" +"``py3-none-any`` というパターンは、純 Python のプロジェクトに広く見られます。" +"拡張モジュールを伴うパッケージは、典型的に、もっと複雑なタグ群を持つ複数の " +"wheel を出荷します。" + +#: ../source/discussions/package-formats.rst:130 +msgid "" +"All technical details on the wheel format can be found in the :ref:`wheel " +"specification `." +msgstr "" +"wheel のフォーマットに関するすべての技術的な詳細は、 :ref:`wheel 仕様 " +"` で見つかるでしょう。" + +#: ../source/discussions/package-formats.rst:138 +msgid "What about eggs?" +msgstr "egg って何？" + +#: ../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 "" +"\"Egg\" は、 wheel によって置き換えられた古いパッケージフォーマットです。もは" +"や使用されるべきではありません。 2023 年 8 月以降、 PyPI は `egg のアップロー" +"ドを拒絶 `_ しています。" + +#: ../source/discussions/package-formats.rst:144 +msgid "Here's a breakdown of the important differences between wheel and egg." +msgstr "wheelと egg の重要な差異について以下にまとめます。" + +#: ../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 "" +"egg のフォーマットは、2004年に:ref:`setuptools`によって、また、wheel のフォー" +"マットは2012年に :pep:`427` によって導入されました。" + +#: ../source/discussions/package-formats.rst:149 +msgid "" +"Wheel has an :doc:`official standard specification `. Egg did not." +msgstr "" +"Wheel には :doc:`公式の標準仕様 ` が存在します。 Egg にはありません。" + +#: ../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 "" +"Wheel は :term:`配布物 `のフォーマット、つまり、パッ" +"ケージングのフォーマットです [#wheel-importable]_ 。 Egg は配布物のフォーマッ" +"トでもあり、かつ、(もし圧縮されたままであれば)実行時のインストールフォーマッ" +"トであって、 importができるように設計されています。" + +#: ../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 "" +"Wheel 形式のファイルには ``.pyc`` ファイルが含まれていません。従って、Python" +"ファイルだけが配布物に含まれている (即ちコンパイル済みの拡張がない) 場合、か" +"つ、 Python 2 および 3 と互換性を持つ時、その wheel ファイル" +"は、 :term:`sdist ` と同様に \"汎用 " +"\" である可能性があります。" + +#: ../source/discussions/package-formats.rst:161 +msgid "" +"Wheel uses standard :ref:`.dist-info directories `. Egg used ``.egg-info``." +msgstr "" +"Wheel は、:ref:`.dist-info ディレクトリ ` を使" +"います。 Egg は ``.egg-info`` を使います。" + +#: ../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 "" +"Wheel には :ref:`多彩なファイル命名慣行 `が存在します。" +"単独のwheelアーカイブはPython言語のバージョンや実装、ABI、そしてシステムの" +"アーキテクチャとの互換性を表示することができます。" + +#: ../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 "" +"Wheel はバージョン付けされています。それぞれのwheelファイルは、wheelの仕様の" +"バージョンやパッケージングに使われた実装のバージョンを保持しています。" + +#: ../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 "" +"wheel は、内部では、 `sysconfigパスの型 `_ に従って整理されているので、他のフォー" +"マットに変換するのがより簡単になっています。" + +#: ../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 "" +"このフォーマットは、電子メールのものをベースにしています。今となってはこれが" +"選択されるとは思えませんが、後方互換性を鑑みて正規のフォーマットとして維持さ" +"れています。ユーザの観点からは、これはほとんど目に映りません。というのは、ビ" +"ルドバックエンドに理解できる形、典型的には ``pyproject.toml`` の中の " +"``[project]`` でメタデータがユーザによって指定され、ビルドバックエンドが " +"``PKG-INFO`` 内へと翻訳するからです。" + +#: ../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/pip-vs-easy-install.rst:6 +msgid "pip vs easy_install" +msgstr "pip対easy_install" + +#: ../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/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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/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/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../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/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "``setup.py`` は非推奨になりましたか？" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" +"いいえ、 :term:`setup.py` および :ref:`setuptools` は非推奨にはなっていませ" +"ん。" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" +"Setuptools は、 :term:`ビルドバックエンド ` として Python のプ" +"ロジェクトをパッケージングすることに完璧に使用可能です。そし" +"て、 :file:`setup.py` は、例えば *TOML* の代わりにたまたま Python で書かれて" +"いる :ref:`setuptools` 向けの正当な設定ファイルです (*nox* とその設定ファイル" +"である :file:`nox.filepy` や *pytest* と :file:`conftest.py` のような他のツー" +"ル類でも、よく似たパターンが使われています)。" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" +"しかしながら、 ``python setup.py`` および :file:`setup.py` をコマンドライン" +"ツールとして使うことは非推奨になりました。" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" +"その意味するところは、次のようなコマンドを実行することはもはや **許されない" +"** ということです:" + +#: ../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]_" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" +"これは、:ref:`build` の依存関係を要求します。 ``python -m build`` を実行すれ" +"ばそうなりますが、プロジェクトにおいては常にソースコード配布物とwheelの両方を" +"公開することを推奨します。もし必要であれば、いずれか片方を生成するのに ``--" +"sdist`` や ``--wheel`` のオプションを使うことができます。" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +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 +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 .``." +msgstr "" +"*編集可能 * モードとしても知られる *開発 * モードでのイン" +"ストールのためには、 ``python setup.py develop`` の代わりに pip の *install* " +"サブコマンドの ``--editable`` オプションを使うことができます: ``python -m " +"pip install --editable .``。" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" +":term:`ソースコード配布物 ` およ" +"び :term:`wheels ` をビルドする方法で推奨されていて単純かつ直截なひと" +"つのやり方は、 :ref:`build` ツールを ``python -m build`` のようなコマンドから" +"使って両方の配布物フォーマットの生成を開始することです。いずれか片方の配布物" +"だけを生成するのであれば、必要に応じて ``--sdist`` や ``--wheel`` のオプショ" +"ンを使うことができます。build ツールは個別にインストールする必要があることに" +"注意してください。" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" +"コマンド ``python setup.py install`` は、setuptools のバージョン *58.3.0* で" +"非推奨になりました。" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +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/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "``python setup.py test``" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "推奨されるものは、pytest_ のようなテストランナーを使うことです。" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" +"``python setup.py check``, ``python setup.py register``, および ``python " +"setup.py upload``" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "信頼されている代替物は :ref:`twine` です:" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "``python -m twine check --strict dist/*``" + +#: ../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/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "``python -m twine upload dist/*``" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" +"必ずしもそうではなく、 :term:`PyPI ` でもサポー" +"トされていません。しかし、(例えば :ref:`devpi` のような) 他の :term:`パッケー" +"ジインデックス ` では必要になるかもしれません。" + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "``python setup.py --version``" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" +"実行可能な代替案は (他にもありますが) setuptools-scm_ に頼ることでしょう:" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "``python -m setuptools_scm``" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "残りのコマンド群" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "このガイド文書では、それらコマンド群の代替案について示唆しません:" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "``alias``" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "``bdist``" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "``bdist_dumb``" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "``bdist_egg``" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "``bdist_rpm``" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "``build``" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "``build_clib``" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "``build_ext``" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "``build_py``" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "``build_scripts``" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "``clean``" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "``dist_info``" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "``easy_install``" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "``editable_wheel``" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "``egg_info``" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "``install_data``" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "``install_egg_info``" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "``install_headers``" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "``install_lib``" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "``install_scripts``" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "``rotate``" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "``saveopts``" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "``setopt``" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "``upload_docs``" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "カスタムコマンドについてはどうでしょうか？" + +#: ../source/discussions/setup-py-deprecated.rst:158 +msgid "" +"Likewise, custom :file:`setup.py` commands are deprecated. The " +"recommendation is to migrate those custom commands to a task runner tool or " +"any other similar tool. Some examples of such tools are: chuy, make, nox or " +"tox, pydoit, pyinvoke, taskipy, and thx." +msgstr "" +"同様に、カスタムコマンドの :file:`setup.py` も非推奨になっています。そのよう" +"なカスタムコマンドについては、タスクランナーツールか他の類似ツールに移植する" +"ことをお勧めします。そのようなツールの例を挙げれば: chuy、 make、 nox もしく" +"は tox、 pydoit、 pyinvoke、 taskipy、 そして thx。" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "カスタムビルドステップについてはどうでしょうか？" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" +"例えば、 ``build_py`` 、 ``build_ext`` や ``bdist_wheel`` のように既存のス" +"テップを上書きしたり新しいビルドステップを追加したりするカスタムビルドステッ" +"プは、非推奨にはなっていません。そのようなステップは期待通りに自動的に呼び出" +"されるでしょう。" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "``setup.py`` は削除されるべきですか？" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" +":file:`setup.py` を実行可能なスクリプトとして使うことは非推奨になりましたが、" +"しかし、setuptools に対する設定ファイルとして使うことは完全に正当で" +"す。:file:`setup.py` を修正する必要はないでしょう。" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "``pyproject.toml`` は必須ですか？" + +#: ../source/discussions/setup-py-deprecated.rst:185 +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/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" +"これについては、説明文書の :ref:`setup.py 近代化プロジェクト ` にもっと詳しい説明があります。" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "どうして？一体全体どういうこと？" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" +"ひとつの見方は、setuptools のスコープが、いまや、ビルドバックエンドの役割に限" +"定されているということです。" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "これについて、どこでもっと読めますか？" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" +"Paul Ganssle による `setup.py を直接に起動するべきではないのは何故か " +"`__" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr ":doc:`setuptools:deprecated/commands`" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "プロジェクトのバージョン番号をひとつの源から取得する" + +#: ../source/discussions/single-source-version.rst:7 +msgid "Complete" +msgstr "完了" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "2024-10-07" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" +"多くの Python :term:`配布パッケージ ` は、インポート" +"パッケージのランタイムにある ``__version__`` アトリビュートが、 " +"(:ref:`runtime-version-access` に述べられているよう" +"に) :func:`importlib.metadata.version` 関数が報告する配布パッケージのバージョ" +"ンと同じバージョン指定子を報告することが求められているところの、単一の " +"Python :term:`インポートパッケージ ` を公開します。" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" +"このバージョン番号の情報が、ソースコード内で手動で更新するものではない、 " +"(``v1.2.3`` のような) バージョン管理システムの *タグ* から派生したものになっ" +"てほしいと、繰り返し要望されます。" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" +"プロジェクトの中には、単純に重複したデータエントリを抱えたまま進行することを" +"選択し、異なる値に分岐しないことを保証する自動テストに依存するものもあってよ" +"いでしょう。" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" +"別のやり方としては、プロジェクトが選択したビルドシステムは、バージョン番号に" +"ついて唯一の源を定義する方法を提案しても構いません。" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "一般的に、取りうる選択肢は:" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" +"ソースコードが Git のようなバージョン管理システム (VCS) の中にあるなら、バー" +"ジョン番号は VCS から取り出すことできます。" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" +"バージョン番号は、 :file:`pyproject.toml` ファイルにハードコードすることが可" +"能です -- そして、ビルドシステムがそれを要求される他の場所にコピーすることが" +"できます。" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" +"バージョン番号の文字列をソースコードの中にハードコードすることもできます " +"-- :file:`_version.txt` のような特別な目的のファイル (これはプロジェクトの" +"ソースコード配布物 (パッケージ) の一部として同梱されなければなりません) の中" +"に置くか、あるいは、 :file:`__init__.py` のような特定のモジュールの中のアトリ" +"ビュートとして置くかです。ビルドシステムは、ビルド時にランタイムの場所からそ" +"れを取り出すことができます。" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "推奨される方法を知るには、ビルドシステムの説明文書に当たってください。" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" +"配布パッケージとそれが関連するインポートパッケージが同一のバージョン番号を共" +"有することを意図する時は、そのプロジェクトに、 ``import_name.__version__`` " +"と ``importlib.metadata.version(\"dist-name\")`` が同じ値を報告することを保証" +"する自動化されたテストケースが含まれていることが推奨されます (ノート: 多くの" +"プロジェクトでは ``import_name`` と ``dist-name`` は同じ名称でしょう) 。" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "ビルドシステムでのバージョン番号の取り扱い" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" +"以下は、ビルドシステムのいくつかの、バージョン文字列の取り扱い方を説明した文" +"書です。" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "`Flit `_" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "`Hatchling `_" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" +"`PDM `_" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" +"`Setuptools `_" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "`setuptools_scm `_" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "src レイアウト対フラットレイアウト" + +#: ../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/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/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/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/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/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" +"src レイアウトを採用することは、今まさに開発中のソースコードを使ってしまうと" +"いう事故を防ぐことを助けます。" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +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." +msgstr "" +"Python インタープリタはカレントワーキングディレクトリをインポートパスの先頭に" +"含むので、これは妥当なことです。これが意味するところは、もしインストール済み" +"のパッケージと同名のものがカレントワーキングディレクトリに存在するならば、カ" +"レントワーキングディレクトリにあるものが使われるであろうということです。これ" +"によって、配布物に一部ファイル群が含まれない結果に終わるという、プロジェクト" +"のパッケージングツールの微妙な誤設定をもたらしかねません。" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" +"src レイアウトを使えば、パッケージ群をプロジェクトのルートディレクトリとは異" +"なるディレクトリに置くので、インストール済みのパッケージの方を使用することが" +"保証され、このような誤設定を避ける助けになります。" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" +"src レイアウトを使うことで、インポートしようと意図した :doc:`編集可能なインス" +"トール ` だけをインポートするように強" +"制することを助けます。" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" +"これは、編集可能なインストール (のパッケージ) がインポートパスにそのディレク" +"トリを追加するように動く `パス設定ファイル `_ を使って実装されている場合に、特に適切です。" + +#: ../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/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" +"src レイアウト付きのソースコードからコマンドラインインターフェースを走らせる" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" +"最初に述べた src レイアウトの特殊性の故に、コマンドラインインタフェース" +"は、 :term:`ソースコードツリー ` から直接に起動すること" +"ができず、試験目的のために :doc:`開発モード `:doc:`開発モード ` " +"でインストールされたパッケージを要求します。状況によってはこれは現実的ではな" +"くなるので、 :file:`__main__.py` ファイル経由で呼ばれた時にパッケージフォルダ" +"を Python の :py:data:`sys.path` の先頭に追加することが回避策になるかもしれま" +"せん。" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +msgid "Versioning" +msgstr "バージョニング" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" +"この議論では、 Python パッケージのバージョニングについてあらゆる角度からカ" +"バーします。" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "正当なバージョン番号" + +#: ../source/discussions/versioning.rst:14 +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]_:" +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``" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "アルファリリース: ``1.2.0a1``" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "ベータリリース: ``1.2.0b1``" + +#: ../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 "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +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``" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +msgstr "エポック付きのバージョン (非推奨): ``1!1.0``" + +#: ../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/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/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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" +"最後に、エポックは、バージョニングの方法を変更する時にソート順を修正すること" +"を意図しています。例えば、 ``23.12`` のようなカレンダーバージョニングを使って" +"いるプロジェクトが ``1.0`` のようなセマンティックバージョニングに移行するよう" +"な場合に、 ``1.0`` と ``23.12`` の間の比較は誤った結果になるでしょう。これを" +"訂正するために、 ``1!1.0`` のような明示された エポックを持つことで、新しい" +"バージョン番号が古いバージョン番号よりもより最近のものとして扱われるようにす" +"るべきです。しかしながら、これは非推奨であって、例えば ``100.0`` のようなより" +"大きなバージョン番号でユーザが混乱しそうにないものを使う方が好ましいです。" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "セマンティックバージョニング対カレンダーバージョニング" + +#: ../source/discussions/versioning.rst:62 +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:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" +"次のバージョン番号を選定する上で既知の例外があります。保守者は、最後のバー" +"ジョン断片の変更では後方互換性を保つ変更だけを含むという想定を破るような選択" +"を意識的に行っても構いません。そのような場合の一つは、セキュリティ上の脆弱性" +"を修正する必要がある時です。セキュリティリリースは、しばしば、パッチバージョ" +"ンとして提供されますが、そうすると必然的にここで述べているような変更をもたら" +"します。" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "セマンティックバージョニング" + +#: ../source/discussions/versioning.rst:87 +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:90 +msgid "*major* when they make incompatible API changes," +msgstr "APIの変更で互換性を失う時には *major* 番号、" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "後方互換性を保ったままで新機能を追加する場合には *minor* を、そして" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "後方互換性を維持したままのバグ修正の場合には *patch* を増加させます。" + +#: ../source/discussions/versioning.rst:94 +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:104 +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:113 +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:116 +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:125 +msgid "Calendar versioning" +msgstr "カレンダーバージョニング" + +#: ../source/discussions/versioning.rst:127 +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:131 +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 "" +"`calendar versioning `_ (CalVer) の最大の利点は、バージョン番号を見" +"ただけで基盤になっている機能セットがどれほど古いのかが直截にわかることです。" + +#: ../source/discussions/versioning.rst:135 +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:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" +"標準的な Python パッケージインストーラである :doc:`Pip ` はカレン" +"ダーバージョニングを採用しています。" + +#: ../source/discussions/versioning.rst:143 +msgid "Other schemes" +msgstr "他の方法" + +#: ../source/discussions/versioning.rst:145 +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:151 +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 "Accessing version information at runtime" +msgstr "ランタイムにバージョン情報にアクセスする" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" +"現在の環境でローカルに利用可能な :term:`配布パッケージ ` のバージョン情報は、標準ライブラリ" +"の :func:`importlib.metadata.version` 関数を使ってランタイム内から取得するこ" +"とが可能です::" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" +"多くのプロジェクトでは、パッケージレベルの ``__version__`` アトリビュートを提" +"供することで、トップレベルの :term:`インポートパッケージ ` に" +"バージョン番号を付与することも選択しています::" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" +"このテクニックは、とりわけ、バージョン番号を問い合わせる呼び出し (``pip -V`` " +"など) が可能な限り素早く動作することが保証されることを望む CLI アプリケーショ" +"ンにおいて価値があります。" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" +"報告された配布パッケージとインポートパッケージのバージョン番号が互いに整合性" +"のあるものとなることを保証したいと望むパッケージの公開者は、そのようにするた" +"めの潜在的なアプローチとして :ref:`シングルソースのバージョン番号 ` の議論を復習することができます。" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" +"インポートされたパッケージやモジュールはランタイムのバージョン情報をこのやり" +"方で公開することを *要求* されてはいない ( :pep:`PEP 396 <396>` で撤回された" +"提案を見てください) ので、 ``__version__`` アトリビュートは、それを提供するも" +"のとして知られているインターフェース (あるプロジェクトが自身のバージョン番号" +"やその直接の依存先のバージョン番号を問い合わせるなど) だけから問い合わせを受" +"けるか、または、問い合わせる側のコードがアトリビュート欠損の場合 [#fallback-" +"to-dist-version]_ を取り扱えるように設計されているかのいずれかであるべきで" +"す。" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" +"プロジェクトによっては、モジュール自身のバージョン番号ではないバージョン情報" +"を外部の API 群向けに公開する必要があるかもしれません。そのようなプロジェクト" +"では、ランタイムに適切な情報を取得するための、そのプロジェクト特有の方法を定" +"義するべきです。例えば、標準ライブラリの :mod:`ssl` モジュールは、下敷きにし" +"ている OpenSSL ライブラリのバージョンにアクセスするための複数の方法を提供して" +"います::" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" +"普通でないバージョン番号のいくつかの例が Seth Larson によって `blog post " +"`_ に挙げられています。" + +#: ../source/discussions/versioning.rst:229 +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/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" +"インポートされるパッケージやモジュールを提供する配布パッケージにインポートす" +"るために利用可能なトップレベルの名称をマッピングした全数リストは、標準ライブ" +"ラリの :func:`importlib.metadata.packages_distributions` 関数を通じて取得する" +"ことができるかもしれません。これが意味するところは、すべてのインポート可能な" +"トップレベルの名称群向けに報告するバージョン番号を暗に示唆することを試みてい" +"るコードであってさえも、もし ``__version__`` アトリビュートが定義されていなけ" +"れば、配布物のバージョン状をを報告するということにフォールバックする方法を" +"持っているということです。標準ライブラリのモジュール群だけが、そして、 " +"Python パッケージインストレーション以外の方法を通じて追加されたモジュール群だ" +"けが、このような場合にほうこくするバージョン情報を得ることに失敗することで" +"しょう。" + +#: ../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 Package Index (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 format`_ で書かれた :file:`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:`pdm` のような他の" +"ツールを使うことも可能です。" + +#: ../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 "" +":term:`ビルド済配布物 ` の特定の種類で、コンパイル済みの" +"拡張部分を含むもの。" + +#: ../source/glossary.rst:14 +msgid "Build Backend" +msgstr "ビルドバックエンド" + +#: ../source/glossary.rst:17 +msgid "" +"A library that takes a :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" +":term:`ソースコードツリー ` を受け取って、そこか" +"ら :term:`ソースコード配布物 ` や :term:`" +"ビルド済配布物 ` をビルドするライブラリ。ビルドの作業" +"は、 :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 :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 "" +":term:`配布物 ` フォーマットは、インストールするために" +"ターゲットとなるシステムの適切な位置に移動させることに必要となるファイルや" +"メタデータだけを含んでいます。 :term:`Wheel` はそのようなフォーマットですが、" +"インストールできるようになる前にビルド段階が必須となると言う点で " +":term:`Source Distribution (or \"sdist\")` はそうではありません。この" +"フォーマットであることは、 Python のファイル群があらかじめコンパイルされた状" +"態でなければならないということを意味しません (:term:`Wheel` では意図的に" +"コンパイル済みの Python ファイル群を含まないようになっています)。より詳しく" +"は :ref:`package-formats` を見てください。" + +#: ../source/glossary.rst:56 +msgid "Built Metadata" +msgstr "ビルドされたメタデータ" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" +"インストールされた :term:`プロジェクト ` (``METADATA`` ファイル) " +"や :term:`配布物アーカイブ ` ( :term:`Sdist ` の中の ``PKG-INFO`` や :term:`Wheel` 内の " +"``METADATA``) の内部に含まれる場合に :term:`コアとなるメタデータ ` が具体的な形式を取ることになります。" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "コアとなるメタデータ" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" +":ref:`仕様 ` および :term:`コアとなるメタデータのフィールド " +"`\\s において、 :term:`配布パッケージ ` あるいは :term:`インストール済みのプロジェクト ` の鍵となる静的なアトリビュートを記述するものを定義しています。" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "コアとなるメタデータのフィールド" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" +":term:`コアとなるメタデータ ` の仕様の中で定義され、 :term:`ビ" +"ルド済みのメタデータ ` の中に保存される、単一のキー・バリュー" +"ペア (または、複数の使用方法のあるフィールドについては、一連の同名のキー・バ" +"リューペア)。特筆すべきことに、 :term:`Pyproject メタデータキー ` とは区別される。" + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "配布物アーカイブ" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" +":term:`配布パッケージ ` のための物理的な配布物のアー" +"ティファクト (即ち、ディスク上のファイル)。" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "配布パッケージ" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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:97 +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言語" +"の配布物) との混同を避けるために明確に述べる必要がある場合には、長い方の用語" +"を用いることがあります。これらの相違に関する詳細について" +"は、 :ref:`distribution-package-vs-import-package` を見てください。" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "卵" + +#: ../source/glossary.rst:108 +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:`Wheel` によって既に置き換えられていますが、 :term:`ビルド済配布物 " +"` フォーマットは、 :ref:`setuptools` によって導入されまし" +"た。詳細については、 :ref:`egg フォーマット ` を見てください。" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "拡張モジュール" + +#: ../source/glossary.rst:114 +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:121 +msgid "Import Package" +msgstr "インポートパッケージ" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" +"直接に、あるいは何段階になっても良いが、他のパッケージを組み込んで使うような" +"Pythonモジュール。" + +#: ../source/glossary.rst:127 +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:`配布物パッケージ ` との混同を避けるために必要な" +"場合には、長い方の用語を用いることにします。これらの違いの細かな部分について" +"は、 :ref:`distribution-package-vs-import-package` を見てください。" + +#: ../source/glossary.rst:133 +msgid "Installed Project" +msgstr "インストール済みのプロジェクト" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" +":ref:`recording-installed-packages` の仕様の中に記述されている、Python イン" +"タープリタまたは :term:`仮想環境 ` と一緒に使用するため" +"にインストールされた :term:`プロジェクト ` 。" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "既知の良好なセット" + +#: ../source/glossary.rst:143 +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 "" +"相互に互換性のある特定のバージョンの配布物の集合。典型的には、テストスイート" +"で全てのテストに合格して実行できるようなパッケージの特定の組み合わせが既知の" +"良好なセットであると宣言されます。この用語は、個々の配布物を複数組み合わせて" +"構成されるフレームワークやツールキットで共通して用いられます。" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "ライセンス分類詞 " + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" +"ライセンス ``License::`` で始まる (:term:`コアとなるメタデータ ` 仕様の中で :ref:`記述されている ` とおり" +"の) `` PyPI の Trove classifier プロジェクト。" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "ライセンス表現" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "SPDX 表現" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" +"ひとつかそれ以上の SPDX :term:`ライセンス識別子 ` (複数の" +"場合もあり) を含む、正当な SPDX ライセンス表現のシンタックスを伴う文字列" +"で、 :term:`配布物アーカイブ ` のライセンス(群) を記述" +"し、どのように相互に関係するのかを表現するもの。例: ``GPL-3.0-or-later`` ・ " +"``MIT AND (Apache-2.0 OR BSD-2-Clause)``" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "ライセンス識別子" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "SPDX 識別子" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" +"元々は :pep:`639` で仕様化された、正当な SPDX の短縮形式のライセンス識別子。" +"これには、すべての正当な SPDX 識別子と、 SPDX 仕様を満足するカスタムの " +"``LicenseRef-[idstring]`` 文字列が含まれます。例: ``MIT`` ・ ``GPL-3.0-" +"only`` ・ ``LicenseRef-My-Custom-License``" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "モジュール" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "パッケージインデックス" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" +":term:`パッケージ `の発見・消費(訳註、意訳になるが検" +"索・ダウンロードが適切か)を自動化するwebインターフェイスを伴った配布物のリポ" +"ジトリ。" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "プロジェクト単位の索引" + +#: ../source/glossary.rst:198 +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:`プロジェクト ` によって示されたもの。" + +#: ../source/glossary.rst:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "プロジェクト" + +#: ../source/glossary.rst:205 +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:209 +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:215 +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:220 +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:226 +msgid "Project Root Directory" +msgstr "プロジェクトのルートディレクトリ" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" +":term:`プロジェクト ` の :term:`ソースコードツリー ` が位置するファイルシステム上のディレクトリ。" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "プロジェクトソースコードツリー" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" +":term:`ソースコード配布物 ` や :term:`ビ" +"ルド済配布物 ` にパッケージされる前の生のソースコードを含" +"んだ、開発に使われる :term:`プロジェクト ` のディスク上でのフォー" +"マット。" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "プロジェクトソースのメタデータ" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" +":term:`プロジェクト ` の :term:`ソースコードツリー ` 内でパッケージ作者が定義したメタデータで、プロジェクトの :term:`ビルド" +"バックエンド ` が :term:`ビルド済メタデータ ` " +"内の :term:`Core Metadata field` へ変換するもの。 :term:`Pyproject のメタデー" +"タ ` の形か、ツール特有のフォーマット " +"(``pyproject.toml`` 内の ``[tool]`` テーブル、または、ツール独自の設定ファイ" +"ル) で書くことができます。" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "純粋なモジュール" + +#: ../source/glossary.rst:257 +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:260 +msgid "Pyproject Metadata" +msgstr "Pyproject のメタデータ" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" +":ref:`declaring-project-metadata` の仕様で定義されていて、 :pep:`621` で初め" +"て登場した :term:`プロジェクトソースのメタデータ ` " +"で、 :term:`pyproject.toml` ファイルの ``[project]`` テーブルの下" +"の :term:`Pyproject Metadata Key`\\s として格納されるもの。 " +"``pyproject.toml`` 内の ``[tool]`` テーブルの下にあるツール特有のソースメタ" +"データでは *ない* ということに注意。" + +#: ../source/glossary.rst:271 +msgid "Pyproject Metadata Key" +msgstr "Pyproject のメタデータキー" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" +"``pyproject.toml`` 内の ``[project]`` テーブルの中にあるトップレベルの TOML " +"キー; :term:`Pyproject のメタデータ ` の一部。 :term:`コ" +"アとなるメタデータのフィールド ` とは異なる点に注意。" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "Pyproject のメタデータサブキー" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" +":term:`Pyproject メタデータのキー ` のテーブルの値の" +"下にある第２層の TOML キー。" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "Pythonパッケージングオーソリティ(PyPA)" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" +"PyPAは、Pythonのパッケージングに関係する多くのプロジェクトを維持管理する作業" +"グループです。その活動の一環として :doc:`papa.io ` を維持管理して" +"おり、 `GitHub `_ に関連プロジェクトを置くととも" +"に、 `distutils-sig メーリングリスト `_ と `Python談話フォーラム `__ で議論を進めています。" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "Pythonパッケージインデックス (PyPI)" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "pypi.org" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "pyproject.toml" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" +"ツール不可知論者の :term:`プロジェクト ` 仕様を示すファイ" +"ル。 :pep:`518` で定義。" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "リリース" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" +"ある特定の時点における :term:`プロジェクト ` のスナップショットで、" +"バージョン識別子付きのもの。" + +#: ../source/glossary.rst:319 +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:324 +msgid "Requirement" +msgstr "要求事項" + +#: ../source/glossary.rst:327 +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:333 +msgid "Requirement Specifier" +msgstr "要求事項識別子" + +#: ../source/glossary.rst:336 +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:341 +msgid "Requirements File" +msgstr "Requirementsファイル" + +#: ../source/glossary.rst:344 +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:348 +msgid "Root License Directory" +msgstr "ライセンスディレクトリのルート" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "ライセンスディレクトリ" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" +":term:`プロジェクトソースツリー ` 、 :term:`配布物アーカ" +"イブ ` 、または、 :term:`インストール済みのプロジェク" +"ト ` の中で、その下にライセンスファイル群を保存するディレ" +"クトリ。 :term:`プロジェクトソースツリー ` また" +"は :term:`ソースコード配布物 (または \"sdist\") ` では、これは、 :term:`プロジェクトルートディレクトリ ` です。 :term:`ビルド済配布物 ` " +"や :term:`インストール済みのプロジェクト ` では、これは、 " +"それぞれ、wheel アーカイブの :file:`.dist-info/licenses/` ディレクトリである" +"か、プロジェクトフォルダーです。また、 ``License-File`` 内の :term:`Core " +"Metadata Field` に記録されているパスはルートディレクトリからの相対パスです。" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "setup.py" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "setup.cfg" + +#: ../source/glossary.rst:369 +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:372 +msgid "Source Archive" +msgstr "ソースコードアーカイブ" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" +"`ソースコード配布物 (またはsdist) `" + +#: ../source/glossary.rst:382 +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." +msgstr "" +":ref:`pip` のようなツールによるインストールや :term:`ビルド済配布物 ` の生成のために必要となるメタデータや必須のソースファイルを提供" +"する :term:`配布物 アーカイブ ` フォーマット (通常は " +"``python -m build --sdist`` を使って生成されます) 。もっと情報が欲しけれ" +"ば、 :ref:`パッケージフォーマット ` を見てください。" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "システムパッケージ" + +#: ../source/glossary.rst:391 +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:394 +msgid "Version Specifier" +msgstr "バージョン指定子" + +#: ../source/glossary.rst:397 +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\" の部分。Python のパッケージングで現在サポートさ" +"れている識別子の完全な記述については、 :ref:`バージョン指定子の仕様 ` を読んでください。この仕様のサポートは、 :ref:`setuptools` v8.0 " +"と :ref:`pip` v6.0 で実装されました。" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "仮想環境" + +#: ../source/glossary.rst:405 +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:`仮想" +"環境の生成と使用 ` フォーマットで、当初" +"は :pep:`427` で導入され、 :ref:`バイナリ配布物のフォーマット ` 仕様で定義されたもの。詳しくは :ref:`パッケージフォー" +"マット ` を見てください。参照実装である :term:`Wheel プロ" +"ジェクト ` と混同しないように。" + +#: ../source/glossary.rst:421 +msgid "Wheel Project" +msgstr "Wheel プロジェクト" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" +":term:`Wheel フォーマット ` の PyPA による参照実" +"装; :ref:`wheel` 参照。" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "動作可能セット" + +#: ../source/glossary.rst:429 +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:5 +msgid "Analyzing PyPI package downloads" +msgstr "PyPIパッケージのダウンロード状況の解析" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "背景" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "PyPIはいくつもの理由からダウンロード統計を表示しません。:[#]_" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "``pip`` のダウンロードキャッシュ (ダウンロード数を小さくする)" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" +"内部の、または、非公式のミラーサイト (ダウンロード数を大きくする要因にも小さ" +"くする要因にもなる)" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "PyPIにホストされていないパッケージ (比較することの妥当性を損ねる)" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" +"ダウンロード数を増やす非公式のスクリプトまたは試行 (ダウンロード数を大きくす" +"る)" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "過去のデータ品質における既知の問題 (ダウンロード数を小さくする)" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "公開データセット" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +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:49 +msgid "Getting set up" +msgstr "セットアップのやり方" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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`_ を使って `public PyPI download statistics dataset`_ に問い" +"合わせを行うためには、まずGoogleアカウントが必要で、Google Cloud Platform " +"(GCP) プロジェクトで BigQuery API を有効にしておく必要があります。 `クレジッ" +"トカード登録なしのBigQuery 無料枠 `__ " +"を使うと一ヶ月当たり1TBまでのクエリを走らせることができます" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "`BigQuery web UI`_ への道案内。" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "新しいプロジェクトを作成する。" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" +"`BigQuery API `__ を有効にする。" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +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:68 +msgid "Data schema" +msgstr "データ構造" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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:77 +msgid "Column" +msgstr "カラム" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "説明" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "例" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "日付と時刻" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "プロジェクト名" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "パッケージのバージョン" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "インストーラ" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "pip、 :ref:`bandersnatch`" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "Pythonバージョン" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "役に立つクエリ" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" +"「クエリを新規作成」ボタンをクリックすることで `BigQuery web UI`_ 内でクエリ" +"を走らせましょう。" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "パッケージのダウンロードを数える" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "次のクエリは\"pytest\"プロジェクトのダウンロード総数を数えています。" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" +"pipを通じてダウンロードされた数だけを数えるには、 ``details.installer.name`` " +"カラムを使って抽出してください。" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "時系列のパッケージダウンロード数" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" +"月毎のダウンロード数を数えるには、 ``TIMESTAMP_TRUNC`` 関数を使います。このカ" +"ラムを使って抽出することは、通信量を抑えることにもなります。" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "1956741" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "2344692" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "2017-12-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "1730398" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "2017-11-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "2047310" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "2017-10-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "1744443" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "2017-09-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "1916952" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "2017-08-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "時系列で見たPythonバージョン" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +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/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "python" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "3.7" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "18051328726" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "3.6" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "9635067203" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "3.8" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "7781904681" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "2.7" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "6381252241" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "2026630299" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "3.5" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "1894153540" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "アーティファクトへの完全なリンクを得る" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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/analyzing-pypi-package-downloads.rst:229 +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/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "url" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +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/analyzing-pypi-package-downloads.rst:246 +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/analyzing-pypi-package-downloads.rst:248 +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/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "注意書き" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" +"上記の背景に列挙した注意書きに加えて、Linehaulは、極端に過小報告されていたダ" +"ウンロード統計の原因となったバグに2018年7月26日まで悩まされていました。この日" +"より前のダウンロード数については、比率の点(例えばPython2とPython3の百分率)で" +"は正確ですが、絶対数の点では桁が異なるほどに過小です。" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "その他のツール" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +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:273 +msgid "``google-cloud-bigquery``" +msgstr "``google-cloud-bigquery``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" +"BigQuery APIとBigQuery用の公式Pythonクライアントである `google-cloud-" +"bigquery`_ プロジェクトを使って、プログラムからPyPIの公開ダウンロード統計デー" +"タセットにアクセスすることもできます。" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "``pypinfo``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" +"`pypinfo`_ はデータセットにアクセスして、役に立つクエリをいくつか生成する機能" +"を提供するコマンドラインツールです。例えば、 ``pypinfo package_name`` を実行" +"すれば、そのパッケージのダウンロード総数を問い合わせることができます。" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "pipを用いて `pypinfo`_ をインストール。" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "使い方：" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "``pandas-gbq``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" +"`pandas-bbq`_ プロジェクトを使えば `Pandas`_ 経由でクエリ結果を参照することが" +"できます。" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "``ClickPy``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" +"`ClickPy`_ プロジェクトは、基礎となる日毎に更新されるオープンソースの " +"`ClickHouse`_ データベースへのフリーで直接な SQL アクセスとともに、ダウンロー" +"ド統計をビジュアライズする公開のアプリケーションを提供します。" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "参考文献" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" +"`PyPI ダウンロード統計を非推奨とするメール (PyPI Download Counts deprecation " +"email) `__" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" +"`PyPI BigQueryデータセットをアナウンスするメール (PyPI BigQuery dataset " +"announcement email) `__" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "プラグイン作成と発見" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" +"Pythonのアプリケーションまたはライブラリを作成する時には、カスタマイズができ" +"るようにしたり **プラグイン** を通じて機能を追加できるようにしたりすることが" +"しばしばあります。Pythonのパッケージは別々に配布できますので、あなたのアプリ" +"ケーションまたはライブラリが利用可能なすべてのプラグインを自動的に **探し出す" +"** ようにしたくなるかもしれません。" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "プラグインの自動検出には大きく分けて３個の実現方法があります。" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "`Using naming convention`_ 。" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "`Using namespace packages`_ 。" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "`Using package metadata`_." + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "命名規則を用いるやり方" + +#: ../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 "" +"あなたのアプリケーション用のすべてのプラグインが命名規則に従うのであれ" +"ば、 :func:`pkgutil.iter_modules` を用いて命名規則に合致するトップレベルのす" +"べてのモジュールを発見することができます。例えば、 `Flask`_ は命名規則として " +"``flask_{plugin_name}`` を使います。もし、すべてのインストール済みFlask用プラ" +"グインを発見したいのであれば：" + +#: ../source/guides/creating-and-discovering-plugins.rst:38 +msgid "" +"If you had both the `Flask-SQLAlchemy`_ and `Flask-Talisman`_ plugins " +"installed then ``discovered_plugins`` would be:" +msgstr "" +"もしあなたが `Flask-SQLAlchemy`_ と `Flask-Talisman`_ のふたつのプラグインを" +"インストールしてあるなら、 ``discovered_plugins`` は次のようになるでしょう：" + +#: ../source/guides/creating-and-discovering-plugins.rst:48 +msgid "" +"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/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "namespaceパッケージを用いるやり方" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" +":doc:`Namespace パッケージ ` を使えば、プラグイ" +"ンをどこに配置するかに関する規則や、発見するための方法も提供できます。例え" +"ば、あなたが名前空間を決めるサブパッケージ ``myapp.plugins`` を作成したら、そ" +"の名前空間に他の :term:`配布物 ` がモジュールやパッケー" +"ジを配置することができます。インストールが終われば、あなた" +"は :func:`pkgutil.iter_modules` を用いてインストール済みの全てのモジュールや" +"パッケージをその名前空間で発見できるでしょう。" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" +":func:`~pkgutil.iter_modules` に ``myapp.plugins.__path__`` を指定すると、そ" +"の名前空間の直下にあるモジュールだけを探索するようになります。例えば、あなた" +"がモジュールの ``myapp.plugins.a`` と ``myapp.plugins.b`` を提供する配布物を" +"インストールしているとしたら、 ``discovered_plugins`` は次のようになるでしょ" +"う：" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +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 +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." +msgstr "" +"名前空間を決めるパッケージは込み入った機能で、いくつかの異なる作成方法があり" +"ます。 :doc:`packaging-namespace-packages` 文書を読むとともに、あなたのプロ" +"ジェクト用のプラグインとしてはどちらの手法が好ましいのかを明白に文書化してお" +"くことを強くお勧めします。" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "パッケージのメタデータを用いるやり方" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" +"パッケージは、 :ref:`entry-points` に記述されたプラグインのためのメタデータを" +"持つことができます。それを指定することで、パッケージが特定の種類のプラグイン" +"を含んでいることをアナウンスします。そのメタデータを使って、同じ種類のプラグ" +"インをサポートする別のパッケージがそのプラグインを検出するのに使うことができ" +"ます。" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" +"例えば、``myapp-plugin-a`` という名前のパッケージが存在して、その " +"``pyproject.toml`` に次のものを含む場合：" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +msgid "" +"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 "" +"そして、 :func:`importlib.metadata.entry_points` (あるいはPython 3.6-3.9用の " +"backport_ ``import lib_metadata>=3.6``)を使うことで、登録された" +"エントリポイントを全て検出することができます。" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" +"この例では、 ``discovered_plugins`` " +"は :class:`importlib.metadata.EntryPoint` 型の(オブジェクトの)集合となるで" +"しょう。" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" +"今や、``discovered_plugins['a'].load()`` を実行することで、あなたが選んだモ" +"ジュールをインポートすることができます。" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +msgid "" +"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 "" +":file:`setup.py` における ``entry_points`` の指定はかなり自由度が高く、オプ" +"ションがたくさんあります。 :doc:`entry_point ` の全部のセクションに目を通すことをお勧めします。" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" +"この仕様は :doc:`標準ライブラリ ` の一部な" +"ので、setuptools以外のほとんどのパッケージングツールでもエントリポイントを定" +"義できる機能を提供しています。" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "コマンドライン動作のツールを作成しパッケージングする" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" +"このガイド文書では、:term:`Python 仮想環境 ` を作成し管" +"理するツールである :ref:`pipx` でインストールできるような、スタンドアローンの" +"コマンドラインアプリケーションを作成しパッケージングすること、そして、パッ" +"ケージの実行可能なスクリプト (及び利用可能な man ページ) を外部からコマンドラ" +"インで使えるようにすることについて、一通り案内します。" + +#: ../source/guides/creating-command-line-tools.rst:12 +msgid "Creating the package" +msgstr "パッケージを作成する" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" +"まず最初に、 :term:`プロジェクト ` のためのソースツリーを作成しま" +"しょう。例示のために、コマンドラインの引数として与えられた人物名に挨拶 (文字" +"列) を出力する単純なツールをビルドするものとしましょう。" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "Todo" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" +"Python パッケージの最適な構造に関するアドバイスについて、他のガイド文書や議" +"論、リンク集はこちら。" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" +"このプロジェクトは、 :ref:`src-layout ` を厳守し、" +"最後には、トップレベルのフォルダとパッケージの名称として ``greetings`` を伴っ" +"た、このファイルツリーのようになります:" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" +"ツールの機能性に責任のある実際のソースコードは、メインのモジュールの名称から" +"命名された :file:`greet.py` の中に保存されるでしょう。" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" +"上記の関数は、どのように出力すべき挨拶を組み立てるかを決定するいくつかのキー" +"ワード引数を受け取ります。さて、同様にそれを準備するためのコマンドラインイン" +"タフェースを :file:`cli.py` の中に構築しましょう:" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" +"コマンドラインインタフェースは、 Python の型品とを基礎とした使いやすい CLI " +"パーサである typer_ とともにビルドされます。自動補完と申し分のないスタイルを" +"持つコマンドラインヘルプが、最初から使えます。別のオプションは、 Python 標準" +"ライブラリに含まれる :py:mod:`argparse` でしょう。これはほとんどの必要性に十" +"分に応えるものですが、適切に機能させるためには、通常は ``cli.py`` に、ソース" +"コードをたくさん書かなければなりません。さらに別の方法としては、 docopt_ を使" +"うことで、 docstrings だけに基づいて CLI インタフェースを作成することができま" +"す; 熟練ユーザには、 click_ (``typer`` はこれを基礎として使っています) の使用" +"をお勧めします。" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" +"さて、プロジェクトを通常の :term:`インポートパッケージ ` とし" +"て定義するために、空の :file:`__init__.py` ファイルを追加しましょう。" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" +":file:`__main__.py` ファイルは、 :mod:`runpy` から走らせた (すなわち " +"``python -m greetings`` 、これはフラットレイアウトならすぐに動作しますが、 " +"src レイアウトではパッケージのインストールを要求します) 時、アプリケーション" +"のメインのエントリポイントを提示するものですので、コマンドラインインタフェー" +"スをここで初期化しましょう:" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" +"例えば ``python src/greetings`` のように、:term:`ソースコードツリー ` から直接にコマンドラインインタフェースを呼び出すことができるよ" +"うにするためには、このファイルの中にそれなりのハックが置かれていることでしょ" +"う; もっと読みたければ :ref:`running-cli-from-source-src-layout` をどうぞ。" + +#: ../source/guides/creating-command-line-tools.rst:106 +msgid "``pyproject.toml``" +msgstr "``pyproject.toml``" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" +"プロジェクトの :term:`メタデータ ` " +"は :term:`pyproject.toml` の中にあります。 ``typer`` (このチュートリアルでは" +"バージョン *0.1.2.3* を使います) への依存を追加しながら、 :ref:`writing-" +"pyproject-toml` に記述されているように :term:`pyproject メタデータキー " +"` や ``[build-system]`` テーブルに値が埋め込まれま" +"す。" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" +"コマンドラインツールとして認識されるプロジェクト向けには、さらに " +"``console_scripts`` :ref:`エントリポイント ` ( " +":ref:`console_scripts` をご覧ください) が :term:`サブキー ` として追加されている必要があります:" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" +"これで、プロジェクトのソースコードツリーが、インストールすることができ" +"る :term:`配布パッケージ ` へと変換される準備ができまし" +"た。" + +#: ../source/guides/creating-command-line-tools.rst:123 +msgid "Installing the package with ``pipx``" +msgstr "``pipx`` を使ってパッケージをインストールする" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" +":ref:`installing-stand-alone-command-line-tools` に記述されているように " +"``pipx`` をインストールした後に、プロジェクトをインストールしましょう:" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" +"これによって、エントリポイントとして定義した実行可能なスクリプトを露出し、コ" +"マンド ``greet`` を利用可能にします。試してみましょう:" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" +"この例では ``typer`` を使っていますので、今や ``--help`` オプションをつけて呼" +"び出すことでプログラムの使用方法の概要を得たり、 ``--install-completion`` オ" +"プション経由でコマンドライン補完を得ることができるでしょう。" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" +"プログラムを永続的にインストールすることなしにただプログラムを走らせるために" +"は、一時的な (しかしキャッシュされる) 仮想環境を作ってくれる ``pipx run`` を" +"使いましょう。" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" +"しかしながら、このシンタックスはちょっと実際的ではありません; 上で定義したエ" +"ントリポイントの名称がパッケージ名称と一致しないので、 (たとえたったひとつだ" +"けしか実行スクリプトがないとしても) 明示的にどの実行スクリプトを走らせるのか" +"を述べる必要があります。" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" +"しかしながら、この問題に対するもっと実際的な解決法で、 ``pipx run`` でエント" +"リポイントを指定する形式があります。以下に述べる :file:`pyproject.toml` 内で" +"定義することで同様のことができるのです:" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" +"このエントリポイント (その名称がパッケージ名称と *一致しなければなりません*) " +"のおかげで、 ``pipx`` は実行可能なスクリプトをデフォルトのものとして選択しそ" +"れを走らせるでしょう、そして、それはこのコマンドを実現可能にします:" + +#: ../source/guides/creating-command-line-tools.rst:176 +msgid "Conclusion" +msgstr "結論" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" +"これまでに、 Python で書かれたコマンドラインアプリケーションをパッケージする" +"方法がわかったものと思います。さらなる一歩としては、そのパッケージを配布する" +"こと、つまり、最も一般的には :term:`PyPI ` のよ" +"うな :term:`パッケージインデックス ` へとアップロードすること" +"でしょう。それをするためには、 :ref:`プロジェクトをパッケージする ` の指示に従ってください。そして、一旦アップロードができたなら、" +"パッケージがどのように受け入れられたかについて :ref:`いくらかの調査を行う " +"` ことを実行してください！" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "パッケージングとプロジェクトの配布" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "期限切れのもの" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "2023-12-14" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" +"この節では、 ``setuptools`` を使ったPythonパッケージの設定・パッケージング・" +"配布方法について、 :doc:`/tutorials/packaging-projects`_ の入門的なチュートリ" +"アルでは触れていないような追加的な詳細を説明します。あなたが既に :doc:`/" +"tutorials/installing-packages` ページの内容については慣れ親しんでいるものと仮" +"定して進めます。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" +"この節は、Pythonプロジェクトの開発についての全体的なベストプラクティスを説明" +"しているわけではありません。例えば、バージョン管理や文書化、あるいは試験につ" +"いて、手引きとなったりツールを推奨するようなことはありません。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" +"より詳しい参考文献としては、:ref:`setuptools` の説明文書の中の :std:doc:`パッ" +"ケージのビルドと配布 ` を挙げておきますが、推奨事" +"項のいくつかはもはや古くなっているかもしれません。喰い違いがあった場合には、" +"Python パッケージングユーザガイドの推奨事項を優先してください。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "パッケージングと配布に対する要求事項" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" +"最初に、あなたが既に :ref:`パッケージをインストールする際の要求事項 " +"` を満たしていることを確実にしてください。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "\"twine\"をインストールする [1]_:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" +"あなたのプロジェクトの :term:`配布物 ` を :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 "最初に必要なファイル群" + +#: ../source/guides/distributing-packages-using-setuptools.rst:61 +msgid "" +"The most important file is :file:`setup.py` which exists at the root of your " +"project directory. For an example, see the `setup.py `_ " +"in the `PyPA sample project `_." +msgstr "" +"最重要のファイルは、あなたのプロジェクトのディレクトリの一番上(ルート)にあ" +"る :file:`setup.py` です。`PyPA サンプルプロジェクト `_ の `setup.py `_ に具体例がありま" +"す。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr ":file:`setup.py` はふたつの主要な機能を提供します。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" +"まず、あなたのプロジェクトをさまざまな角度から設定するためのファイルで" +"す。 :file:`setup.py` の主要な機能は、グローバルな ``setup()`` 関数を含んでい" +"ることです。この関数にキーワード引数を渡すことで、あなたのプロジェクトの特定" +"の細部を定義することができます。適切な引数のほとんどについて :ref:`次節 " +"` で説明します。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" +"それは、パッケージングする上での作業項目に関連したさまざまなコマンドを走らせ" +"るためのコマンドラインインタフェイスです。使用可能なコマンドを一覧するには、 " +"``python setup.py --help-commands`` を実行してください。" + +#: ../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/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 "" +"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 "" +"すべてのプロジェクトは、プロジェクトのゴールを記したreadmeファイルを備えるべ" +"きです。一番良くあるフォーマットは拡張子が \"rst\" の `reStructuredText " +"`_ ですが、これは(訳註、必須の)要求" +"事項というわけではありません。他にも複数の種類の `マークダウン `_ フォーマットがサポートされています" +"(``setup()`` の :ref:`long_description_content_type ` 引数を見て" +"ください)。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" +"`PyPA sample project `_ の中の " +"`README.md `_ に例" +"が出ています。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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:`setuptools`の0.6.27およびそれ以降のバージョンを使っているプロジェクトで" +"は、標準のreadmeファイル(:file:`README.rst`、 :file:`README.txt`、また" +"は :file:`README`)がデフォルトでソースコード配布物に含まれるようになっていま" +"す。標準ライブラリの :ref:`distutils` では、Python 3.7からこの動作を採用しま" +"した。さらに、:ref:`setuptools` の36.4.0およびそれ以降のバージョンでは、もし" +"見つかれば :file:`README.md` を含めるようになっています。もしあなたが" +"setuptoolsを使っているのであれば、あなたはreadmeファイル" +"を :file:`MANIFEST.in` に明記する必要はありません。そうでないなら、明示的に書" +"いてください。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "MANIFEST.in" + +#: ../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/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" +"しかしながら、あなたは必ずしも :file:`MANIFEST.in` を使わなくても構いません。" +"一つの例として`PyPA サンプルプロジェクト `_ では、必要なファイルがすべて 43.0.0およびこれ以降" +"の:ref:`setuptools`に含まれているので、マニフェストファイルを削除しています。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" +":file:`MANIFEST.in` は、wheelなどのバイナリ配布物には影響を与えません。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "LICENSE.txt" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" +"各パッケージは、配布の条件を指定するライセンスファイルを含んでいるべきです。" +"多くの司法管轄区域(訳註、大雑把にいうと「多くの国」)では、明示的なライセンス" +"条項がないと、著作権保持者でなければ誰も適法にパッケージを使用したり配布した" +"りすることができません。どのライセンスを選択すればよいか分からない場合には、" +"`GitHubの「オープンソースライセンスを選ぶには」 `_ などのリソースを見ることも、弁護士に相談することもできます。" + +#: ../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/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "<あなたのパッケージ>" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" +"必ずそうしなければならないというわけではありませんが、あなたのプロジェクトと" +"同じか非常に近い :ref:`名前 ` の単一のプロジェクトをPythonのモ" +"ジュールやパッケージのトップレベルに配置するということが共通の慣習になってい" +"ます。" + +#: ../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 "" +"`PyPAサンプルプロジェクト `_ に含まれ" +"る `サンプル `_ " +"パッケージに例が出ています。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "setup() の引数" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" +"上述の通り、:file:`setup.py` の第一の機能は、グローバルスコープの " +"``setup()`` 関数を含むことです。この関数に与えるキーワード引数は、あなたのプ" +"ロジェクトの特定の細部がどのように定義されているかを示すものです。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" +"いくつかについては、情報がどこか他の場所に移されるまでの一時的な説明が以下に" +"あります。すべてを列挙したものは :doc:`setuptools の説明文書 " +"` で見つかるでしょう。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" +"ほとんどのソースコード断片(スニペット)は、`PyPA サンプルプロジェクト " +"`_ の中の `setup.py `_ から取られたものです。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" +"あなたのユーザへ互換性情報を伝える方法としてバージョン番号を使うやり方につい" +"ては、 :ref:`バージョンをつける規則を選択するには ` をご覧ください。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "``packages``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"packages can be listed manually, ``setuptools.find_packages()`` finds them " +"automatically. Use the ``include`` keyword argument to find only the given " +"packages. Use the ``exclude`` keyword argument to omit packages that are " +"not intended to be released and installed." +msgstr "" +"``packages`` には、あなたのプロジェクトにある :term:`パッケージ ` を子パッケージや孫パッケージなども含めてすべて列挙してください。" +"パッケージは手動で列挙することもできますが、 ``setuptools.find_packages()`` " +"を使えば自動で列挙することができます。 ``include`` キーワード引数を使うと、こ" +"こに与えられた特定のパッケージだけを探索することができます。 ``exclude`` キー" +"ワード引数を使うと、公開したりインストールしたりする意図のないパッケージを除" +"外することができます。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +msgstr "``py_modules``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:198 +msgid "" +"If your project contains any single-file Python modules that aren't part of " +"a package, set ``py_modules`` to a list of the names of the modules (minus " +"the ``.py`` extension) in order to make :ref:`setuptools` aware of them." +msgstr "" +"あなたのプロジェクトに、プロジェクトの一部ではない単一ファイルのPythonモ" +"ジュールがあるなら、 :ref:`setuptools` に知らせるために、そのようなモジュール" +"の(拡張子``.py``を削除した)名前を ``py_modules`` に列挙してください。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" +"``install_requires`` は、プロジェクトが動作するために最低限必要な依存関係を指" +"定するのに使われます。プロジェクトが :ref:`pip` でインストールされる場合に" +"は、この指定を見て依存関係(訳註、にある他パッケージ)をインストールするために" +"用いられます。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" +"さらなる ``install_requires`` の使い方については :ref:`install_requires対" +"Requirementsファイル ` を参照してくだ" +"さい。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "``package_data``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"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 "" +"追加のファイルを :term:`パッケージ ` にインストールする必要が" +"ある、というのはよくあることです。このようなファイルは、しばしば、そのパッ" +"ケージの実装に深く関係していたり、パッケージを利用するプログラマの利益になる" +"ような説明を含んだテキストファイルであったりします。このようなファイルは" +"「パッケージデータ」と呼ばれます。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" +"この引数に渡す値は、パッケージ名から、そのパッケージ内にコピーされるべきファ" +"イルの相対パス名を列挙したもののマッピングになっていなければなりません。パス" +"名はパッケージを含むディレクトリからの相対パスとして解釈されます。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" +"詳しくは、 :std:doc:`setuptools説明文書 ` の中の :std:doc:`" +"データファイルを追加するには <1setuptools:userguide/datafiles>` を見てくださ" +"い。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "``data_files``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" +":ref:`パッケージデータ ` を設定すればほとんどの需要に応えられま" +"すが、あなたの :term:`パッケージ ` の *外側* にデータファイル" +"を置きたいこともあるでしょう。 ``data_files`` ディレクティブでそれができま" +"す。大抵は、Pythonのパッケージを認識しないような他のプログラムから利用する" +"ファイルをインストールする必要がある時に、これが役に立つでしょう。" + +#: ../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/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" +"さらに詳しくは、 :ref:`追加的なファイルをインストールするには " +"` の中のdistutilsの節を見てください。" + +#: ../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/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" +"``setup()`` はあらかじめ作成されたスクリプトをインストールするため" +"に :ref:`scripts ` キーワードをサ" +"ポートしていますが、異機種間の互換性を取るためのアプローチとして推奨されるの" +"は :ref:`console_scripts` エントリーポイント(後述)を使うことです。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "バージョン体系を選択する" + +#: ../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/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "開発モードで作業する" + +#: ../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/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" +"Pythonのパッケージを「編集可能」/「開発」モードでインストールするには、そのプ" +"ロジェクトのルートディレクトリへ移動して、次のコマンドを走らせてください:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" +"pip のコマンドラインオプションの ``-e`` は ``--editable`` の省略形で、 ``.`` " +"は現在作業をしているディレクトリのことですので、まとめると「現在のディレクト" +"リ(つまりあなたのプロジェクト)に編集可能モードでインストールせよ」ということ" +"になります。また、このコマンドによって ``install_requires`` に宣言された依存" +"先のパッケージや ``console_scripts`` に書かれたスクリプトもインストールされま" +"す。" + +#: ../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::" +msgstr "" +"依存先のプロジェクトも同様に編集可能モードでインストールしたい時があるかもし" +"れません。例えば、あなたのプロジェクトが \"foo\" と \"bar\" というパッケージ" +"を要求していて、 \"bar\" についてはVCS (バージョンコントロールシステム) から" +"編集可能モードでインストールしたい場合には、requirements ファイルを次のように" +"構成すれば良いでしょう::" + +#: ../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/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/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" +"さもなければ requirements ファイルに書かれた順にインストールされてしまうの" +"で、依存先のパッケージが PyPI から充当されてしまいます。 requirements ファイ" +"ルについてさらに詳しく知りたい場合は、 pipの解説文書の :ref:`Requirements " +"ファイル ` の節を見てください。VCSからのインストール" +"については、同書の :ref:`VCSサポート ` の節を見てください。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" +"最後に、もし依存先パッケージは何もインストールしたくないのであれば、このよう" +"にします:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" +"さらに詳しいことを知りたい場合は、 :ref:`setuptools` 文書の :doc:`開発モード " +"` の 節を見てください。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "プロジェクトをパッケージングする" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" +":term:`PyPI ` のような " +":term:`パッケージインデックス ` からあなたのプロジェクトを" +"インストールすることができるようにするには、 :term:`配布物 ` (:term:`パッケージ ` の名前でも知られる) を作" +"成しなければならないでしょう。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" +"あなたのプロジェクトでwheelsやsdistsをビルドする前に、 ``build`` パッケージを" +"インストールする必要があります。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "ソースコード配布物" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" +"少なくとも、 :term:`ソースコード配布物 ` " +"を作成するべきです:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" +"ソースコード配布物はビルドされていない (すなわち、 :term:`ビルド済み配布物 " +"` ではない) ので、pip でインストールする際にビルドする段" +"階が必要になります。配布物が純Python (つまり (訳注、多言語で書かれた) 拡張を" +"含まない) であったとしても、 :file:`setup.py` や :file:`setup.cfg` からインス" +"トール用メタデータを取り出してビルドする段階を必要とするのです。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "Wheels" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" +"あなたのプロジェクトでは、wheelも作成するべきです。wheel は、インストールする" +"のにビルド処理を行う必要がない :term:`ビルド済み配布物 ` " +"です。wheelを使えば、ソースコード配布物からのインストールに比べてエンドユーザ" +"にとって相当素早くインストールすることができます。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" +"あなたのプロジェクトが純Pythonなら、きっとあなたは :ref:`\"純PythonのWheel\" " +"(後述) ` を作成することになるでしょう。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" +"もしあなたのプロジェクトにコンパイル済の拡張が含まれているなら、 :ref:`*プ" +"ラットフォーム Wheel* (後述) ` を作成することになるでしょ" +"う。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" +"あなたのプロジェクトが Python 2をさぽーとしていて、 *かつ* 、C言語拡張を含む" +"のであれば、次のものをあなたの :file:`setup.cfg` ファイルに追加して " +"*ユニバーサル Wheel* と呼ばれるものを作成するべきです:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" +"あなたのプロジェクトにC言語拡張がなく、 *かつ* 、Python 2 および3をサポートし" +"ている場合に限って、この設定を使ってください。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "純Python Wheels" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" +"*純Python Wheels* は、コンパイル済拡張を含んでおらず、従って単独のPython " +"wheelを要求するだけです。" + +#: ../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/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" +"``wheel`` パッケージは、ソースコードが純Pythonであることを検出して、Python 3 " +"へのインストールであればどこでも使えるのでそのように名付けられたwheelをビルド" +"します。wheelファイルの名称について詳しいことは :pep:`425` を見てください。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" +"``--wheel`` か ``--sdist`` を付けずに ``build`` を実行すると、両方のファイル" +"が作成されます; 複数のwheelファイルにしたくないときにはこれが便利です。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "プラットフォームWheels" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*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/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" +"``wheel`` パッケージは、ソースコードが純Pythonで書かれていないと判断すると、" +"ビルドされたプラットフォーム上でのみ利用可能であるように命名されたwheelを作成" +"します。wheelファイルの命名規則については、 :pep:`425` を見てください。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" +"現在、 :term:`PyPI <` は、Windows向けとmacOS向" +"け、そして複数のLinuxディストリビューションに対応した ``manylinux*`` のABI向" +"けのプラットフォームWheelsをアップロードすることに対応しています。" + +#: ../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 "" +"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 "" +"配布物を作成するコマンドを走らせると、あなたのプロジェクトのルートディレクト" +"リに ``dist/`` という新しいディレクトリが作成されます。ここに配布物のファイル" +"(群)が置かれます。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" +"これらのファイルは、配布物作成のコマンドを走らせたときにだけ作成されます。と" +"いうことは、プロジェクトのソースコードや :file:`setup.py` の中の設定を変更し" +"たときにはいつでも、PyPIへ送る前に配布物のファイルを再作成する必要があるとい" +"うことです。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" +"PyPIの主リポジトリでリリースをする前に、半定期的に消去される `PyPI 試験サイ" +"ト `_ で練習する方が良いかもしれません。どのように設" +"定すれば試験サイトを使えるかについては、 :ref:`using-test-pypi` を見てくださ" +"い。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" +"他のリソースでは、 ``python setup.py register`` と ``python setup.py " +"upload`` に遭遇するかもしれません。これらのメソッドはパッケージを登録ないし" +"アップロードするものですが、 いくつかのバージョンのPythonで使うと平文のHTTPか" +"検証しないHTTPSを用いるのであなたのユーザ名とパスワードが 通信経路上で横取り" +"される恐れがあって **強く非推奨** の状態になっています。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" +"PyPIで使っている reStructuredText パーサは Sphinx **ではありません！** その" +"上、全ユーザの安全を確保するためにある種の URL やディレクティブ(例えば ``.. " +"raw::`` ディレクティブ)は禁止されていたり削除されたりしています。あなたの配布" +"物をアップロードしてみる **前に** :file:`setup.py` の中の brief/long " +"description が文法的に妥当かどうかを確かめるべきです。あなたのパッケージの" +"ファイル群に対して :std:doc:`twine check ` を走らせれば、それを確かめ" +"ることができます。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "アカウントを作成する" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" +"まず、 :term:`PyPI ` のユーザアカウントが必要で" +"す。 `PyPIウェブサイトにあるフォームを使えば `_ アカウントを作成することができます。" + +#: ../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 "" +"次に PyPI の `API トークン`_ を作成して、プロジェクトを安全にアップロードでき" +"るようにしましょう。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" +"https://pypi.org/manage/account/#api-tokens and create へ行って、新しい `API " +"トークン`_ を作成してください; これから新しいプロジェクトを作成するわけですか" +"ら、スコープを特定のプロジェクトに限定しないようにしてください。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" +"**トークンをコピーして保存するまではページを閉じないでください -- トークンは" +"二度と表示されることがありません。**" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" +":file:`$HOME/.pypirc` ファイルを作っておくことで、アップロードするたびにトー" +"クンをコピー・ペーストする手間を省くことができます。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" +":file:`.pypirc` についてさらに詳しく知りたい場合は :ref:`specification " +"` を見てください。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "配布物をアップロードする" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" +"アカウントが入手できれば、 :ref:`twine` を使ってあなたの配布物を :term:`PyPI " +"` へアップロードすることができます。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" +"リリースをアップロードする手続きは、そのプロジェクトがPyPIに既に存在していて" +"も存在していなくても同じです - もしまだ存在していなければ、最初にリリースが" +"アップロードされたときに自動的に作成されます。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" +"２回目やそれ以降のリリースで PyPI が要求するのは、新しいリリースのバージョン" +"番号が先行するすべてのリリースとは異なるものであることだけです。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" +"``sampleproject`` のところをアップロードしているプロジェクトの名前に置き換え" +"るとして、 ``https://pypi.org/project/`` に誘導されれば、あな" +"たのパッケージのアップロードは成功です。あなたのプロジェクトがサイト上に表示" +"されるまでには1,2分の時間がかかるかもしれません。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" +"あなたのプラットフォームに依りますが、これにはrootまたはAdministratorの権限で" +"アクセスしなければならないかもしれません。 :ref:`pip` は現在、 `一般ユーザで" +"のインストールを規定動作にする案 `_ にあるように、この部分の変更を検討しています。" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "古いバージョンのPython へのサポートをやめる" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" +"古いバージョンのPythonへのサポートを取りやめる能力については、標準的" +"な :ref:`core-metadata` 1.2 仕様の :ref:`Requires-Python ` アトリビュートで有効化されています。" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 のような Metadata 1.2+ のインストーラは、動作中の Python ランタイムのバー" +"ジョンとパッケージのメタデータで要求されているバージョンを比較突合すること" +"で、この仕様を遵守しようとします。もし両者が一致しなければ、その Python ラン" +"タイムでサポートされているパッケージ配布物の中で最新のものをインストールしよ" +"うと試みます。" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" +"パッケージのメタデータにある ``Requires-Python`` 属性を修正することで、古い" +"バージョンの Python へのサポートを削除するのにこのメカニズムを利用することが" +"できます。" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "要求事項" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" +"このワークフローは、パッケージをインストールしようとするユーザが Pip [#]_ " +"か、または、Metadata 1.2 の仕様を満足する別のインストーラを使うことを要求しま" +"す。" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "universal wheelsの取り扱い" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" +"伝統的には、Python 2 と Python 3 の両方に文法的な互換性のある Python ソース" +"コードを提供する :ref:`setuptools` プロジェクトは、 ``py2.py3`` というタグを" +"その名前の中に持つ :term:`wheels ` を生成します。 Python 2 へのサポー" +"トをやめる時には、このタグをただの ``py3`` に変更するのを忘れないことが重要で" +"す。これは、しばしば、 :file:`setup.cfg` の中の ``[bdist_wheel]`` セクション" +"で ``universal=1`` として設定されています。" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" +"このメソッドを使うのであれば、このオプションないしセクションを削除するか、ま" +"たは、明示的に ``universal`` を ``0`` に設定してください。" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" +"``setup.py`` から直接に呼び出すことは :ref:`非推奨 ` に" +"なっていて、コマンドラインで ``--universal`` フラグを渡すことでこの設定を上書" +"きできるでしょう。" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "要求する Python のバージョンを定義する" + +#: ../source/guides/dropping-older-python-versions.rst:48 +msgid "1. Install twine" +msgstr "1. twine のインストール" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "twine の最新版が利用可能であることを確実にしておきましょう。やり方は:" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "2. サポートする Python 配布物のバージョンの範囲を指定する" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" +"プロジェクトがどのバージョンの Python 配布物をサポートしているかを宣言する" +"バージョンレンジ を :file:`pyproject.toml` 内に設定しましょ" +"う。 :ref:`requires-python` 設定フィールドは、 :ref:`Requires-Python ` コアメタデータに対応しています:" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" +"「少なくとも Python 3.9」のような、バージョンの範囲や除外のルール " +"(で :ref:`version-specifiers` 仕様に合致するもの) を指定することができます。" +"あるいは、「少なくとも Python 3.7 かそれ以上、しかし、 3.7.0 と 3.7.1 のポイ" +"ントリリースを除く」:" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" +":ref:`setuptools` ビルドバックエンドを使っているなら、もっと詳しいことは " +"`dependency-management`_ 説明文書に当たってみてください。" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" +"例えば ``\">=3.8, < 3.10\"`` のようにバージョン範囲に上限を加えることを避けま" +"しょう。そうすることで別のエラーやバージョンコンフリクトを引き起こすかもしれ" +"ません。もっと詳しくは、 `discourse-discussion`_ を見てください。" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "3. 公開の前にメタデータを検証する" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" +"Python のソースコードパッケージ (あなたがダウンロードしたzipファイルやtar.gz" +"ファイル) の中には、PKG-INFO という名前のテキストファイルがあります。" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` 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 "" +"このファイルは、ソースコードパッケージを生成するときに、 :term:`ビルドバック" +"エンド ` によって生成されます。このファイルには、一連のキーと" +"値を含んでいて、キーのリストは PyPA 標準メタデータフォーマットの一部です。" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "生成されたファイルの内容はこのようになっています:" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "パッケージを公開する前に、以下のことが適切かどうかを検証してください。" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" +"アップグレードが正しく終われば、 ``Metadata-Version`` の値が 1.2 かそれ以上に" +"なっているはずです。" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" +"``Requires-Python`` フィールドが設定されていて、設定ファイルで指定したものに" +"一致しているはずです。" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "4. パッケージを公開する" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" +":ref:`プロジェクトを PyPI にアップロードする ` で示唆されたように進めましょう。" + +#: ../source/guides/dropping-older-python-versions.rst:120 +msgid "Dropping a Python version" +msgstr "Python のバージョンをサポートから外す" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" +"人々がまだ依存しているバージョンが一旦ドロップされればダウングレードせざるを" +"得なくなるので、原則として、 Python のバージョンに対するメタデータのサポート" +"は可能な限り長く保たれるべきです。しかしながら、特定のバージョンをサポートす" +"ることが、新しい機能の阻害要因になるとか、他の問題が起きるとかする場合は、メ" +"タデータの ``Requires-Python`` は修正されるべきです。もちろん、これは、プロ" +"ジェクトが安定的で広範囲のユーザをよくカバーするか否かにも依存します。" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "バージョン互換性の変更は、それぞれ、それ自身のリリースを持つべきです。" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" +"Python バージョン (のサポート) を落とす時は、使われているバージョン群を (テス" +"ト用の環境のような) 目にみえる場所に使用するように更新することと同様に、プロ" +"ジェクトのソースコードのシンタックスを全般的に更新することが値打ちのあるもの" +"になるかもしれません。 pyupgrade_ や `ruff `_ のようなツール類が、この作業の幾らかを自動化してくれるでしょう。" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "メタデータ仕様 1.2 へのサポートは Pip 9.0 で追加されました。" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "あなた自身の単純なリポジトリをホストする" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can 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/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:" +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." +msgstr "" +"加えて、あなたのリポジトリを公開する場合は正当なHTTPSで公開することが **強く" +"** 推奨されます。この時、ユーザがあなたのパッケージをインストールする際のセ" +"キュリティは、すべてのリポジトリが適切なHTTPS設定を使っているか否かに依存しま" +"す。" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "\"手動\"リポジトリ" + +#: ../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/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/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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "同期、複製、フェールオーバ、ミラーリングが可能な複数のインデックス" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr ":ref:`simpleindex`" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr ":ref:`pypiserver`" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr ":ref:`pypiprivate`" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr ":ref:`pypicloud`" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "メンテナンスされていない; またプロクシでキャッシュ; 認証、認可" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr ":ref:`pywharf`" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "メンテナンスされていない; GitHub内のファイルを提供する" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr ":ref:`pulppython`" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "また、ミラーリング、プロクシ利用; Pulp 用のプラグイン" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr ":ref:`pip2pi`" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "また、ミラーリング; 手動の同期" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr ":ref:`dumb-pypi`" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "サーバではなくて、静的ファイルのサイトのジェネレータ" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr ":ref:`httpserver`" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "標準ライブラリ" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "`Apache `_" + +#: ../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/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" +"単純なリポジトリプロトコルの完全な説明文書としては、 :ref:`simple repository " +"API ` を見てください。" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" +"要求されたパッケージが存在しなければ、 PyPI (もしくは他のパッケージインデック" +"ス) へフォールバックするように設定しておくことができます。" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" +"**ガイド文書** は特定のタスクを達成することに重点を置くもので、読者が Python " +"のパッケージングの基礎について既に馴染みがあるものと仮定しています。パッケー" +"ジングの導入的な説明を探しているのであれば :doc:`/tutorials/index` を見てくだ" +"さい。" + +#: ../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 "" +"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 "" +"PyPI (あるいは他の :term:`パッケージインデックス `) のミラーや" +"キャッシュがあると、手元でパッケージをインストールするのが速くなったり、オフ" +"ラインでインストールできたり、会社のファイアウォール経由でもできたり、あるい" +"は、単純にインターネットがあてにならなくてもインストールできたりします。" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "この領域のオプションには複数のクラスがあります:" + +#: ../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 "" +"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/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/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" +"pip は、 :term:`パッケージ ` のローカルキャッシュを使っ" +"て素早くインストールするためのいくつもの機能を提供します。" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" +"あるプロジェクトの依存先パッケージをすべてダウンロードし、 pip を PyPI の代わ" +"りにそれらダウンロード済みファイルに向けることによる :ref:`速くてローカルなイ" +"ンストール ` 。" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" +":ref:`python -m pip wheel ` を用いて依存先パッケージのインス" +"トール用ファイルをあらかじめビルドしておくという上記のバリエーション:" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "キャッシュ" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" +"継承・同期・複製・フェイルオーバ・パッケージアップロードの機能を持つ複数のイ" +"ンデックス群" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr ":ref:`bandersnatch`" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" +"カスタムプラグインによってキャッシングや他のパッケージインデックスへのリルー" +"ティングが可能になります" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "保守されていない; 認証・認可" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +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`" + +#: ../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 "" +"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 "" +"科学分野のソフトウェアは、他のほとんどのものよりも複雑な依存関係を持つことが" +"多く、異なる種類のハードウェアの利点を引き出すためや外部のソフトウェアのさま" +"ざまな部分と協調動作するためのオプションが複数存在することもしばしばです。" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" +"とりわけ `科学分野のPythonソフトウェア群 `_ の" +"ほとんどのソフトウェアに基盤を提供する`NumPy `__ は、他" +"の FORTRAN ライブラリと協調動作したり現代的なCPUで利用可能なさまざまなレベル" +"のベクター演算命令を活用できるように構成可能です。" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" +"Numpy のバージョン 1.10.4 および SciPy のバージョン 1.0.0 以降は、主要なオペ" +"レーティングシステム (WindowsとmacOSとLinux)向けに32 ビットと 64 ビットのビル" +"ド済みバイナリが ``wheel`` 形式でPyPIに準備されています。ただ、Windowsでは、" +"SSE2命令セットに限定された `ATLAS `__ " +"BLAS/LAPACK ライブラリに NumPy がリンクされているので、線形代数のパフォーマン" +"スが最適化されていない可能性があります。" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" +"科学分野の Python ライブラリ (または、ソースコードからインストールする際にコ" +"ンパイル環境を必要とするが、 PyPI にビルド済みの wheel ファイルが用意されてい" +"ないような、他の全ての Python ライブラリ) を手に入れるには他にも数多くの代替" +"方法があります。" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "ソースコードからビルドする" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" +"NumPy (およびそれに依存するプロジェクトの多く) を wheel ファイルとして配布す" +"ることを難しくする同じ複雑さが、自分でソースコードから作成することをも困難に" +"しています。しかしながら、C言語やFORTRAN言語のコンパイラやリンカを説得するの" +"に喜んで時間を費やそうという勇敢な人々にとっては、ソースコードからビルドする" +"ことは常にひとつの選択肢です。" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +msgstr "Linux 配布パッケージ" + +#: ../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/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/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "Windows 版インストーラ" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" +"現時点で wheel ファイルを公開していない(または公開できない)多くの Python プロ" +"ジェクトでも、 PyPI 上か、または、そのプロジェクトのダウンロードページで、少" +"なくとも Windows 版インストーラを公開しています。このようなインストーラを使え" +"ば、(他言語)拡張をローカルでビルドするための適切な環境を準備する手間を省くこ" +"とができます。" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" +"このようなインストーラで用意されている(他言語)拡張は、たいてい、 python.org " +"で公開されている CPython Windows インストーラと互換性のある形で公開されていま" +"す。" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" +"Linux のシステムパッケージの時と同じく、Windows 版インストーラはシステムワイ" +"ドの Python 環境にしかインストールしません -- つまり、仮想環境へのインストー" +"ルはサポートしていないのです。この制約を回避するよくあるやり方は、仮想環境を" +"使っている時にシステムワイドの Python 環境にインストールされた配布物へのアク" +"セスを許可することです。" + +#: ../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/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +msgstr "macOS インストーラとパッケージマネージャ" + +#: ../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/installing-scientific-packages.rst:83 +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 `_." +msgstr "" +"macOS のユーザは、 ``Homebrew`` のような Linux ディストロスタイルのパッケージ" +"マネージャも使うことができます。ScyPy サイトには、もっと詳しい Homebrew を" +"使って `SciPy を macOS にインストールする `_ 方法の説明があります。" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "SciPy 配布物" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" +"SciPy サイトには、利用・更新が簡単なフォーマットでエンドユーザ向けの SciPy の" +"全機能を提供する `いくつかの配布物 `_ のリストが" +"あります。" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" +"これらの配布物の内のいくつかは、標準的な ``pip`` や ``virtualenv`` を基礎にし" +"たツールチェーンと互換性がないかもしれません。" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "Spack" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" +"`Spack `_ は、複数のバージョン・設定・プラッ" +"トフォーム・コンパイラをサポートできるように設計されたパッケージマネージャで" +"す。大規模スーパーコンピュータセンタや科学分野のアプリケーションチームではあ" +"るソフトウェアを異なる方法でビルドする必要が多々ありますが、そのようなニーズ" +"を満たすように作られています。Spack は Python に限らず、 ``C`` ・ ``C++`` ・ " +"``Fortran`` ・ ``R`` やその他のプログラミング言語でも利用できます。Spackは破" +"壊的ではありません; というのは、あるパッケージの新しいバージョンをインストー" +"ルしても先にインストールされたものを壊すことはなく、非常に多くの設定(でインス" +"トールされたもの)が同一システム上で共存できるのです。" + +#: ../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/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "conda クロスプラットフォームパッケージマネージャ" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" +"``conda`` は、複数のバージョンのソフトウェアのバイナリパッケージやその依存先" +"パッケージをインストールして容易に切り替えて使えるようにする (BSDライセンス" +"の) オープンソースのパッケージマネジメントシステム兼環境管理システムです。こ" +"れは Windows・MacOS・Linuxで動作するクロスプラットフォームのツールです。" +"conda を使えばあらゆる種類のパッケージをまとめたり配布したりすることができ" +"て、 Python のパッケージだけには限りません。ネイティブの仮想環境を完全にサ" +"ポートしています。C 言語のライブラリさえも独立した環境を容易に生成できるよう" +"にすることで、conda は (仮想) 環境を一級市民にしています。Python で書かれてい" +"ていますが、Pythonに依存しているわけではありません。conda は Python そのもの" +"をパッケージのひとつとして扱うため :command:`conda update python` とすること" +"が可能で、Python のパッケージだけを扱う pip とは対照的です。" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" +"Anaconda `Anaconda `_ は Anaconda, Inc. " +"社が公開した Python 配布物です。ビッグデータや科学分野向けの一連のオープン" +"ソースパッケージの安定版のコレクションであり、 conda 環境を管理する GUI の" +"ユーティリティのコレクションでもあります。" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" +"Anaconda が提供する完全版の配布物に加えて、 conda パッケージマネージャそれ自" +"身が `miniconda `_ ・ `miniforge " +"`_ ・ `pixi `_ か" +"ら利用可能です。" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" +"Conda パッケージ群は、Anaconda Inc. がサポートするデフォルトのチャンネルや、" +"広範囲に渡るプリビルドパッケージや幾つかのドメイン特有のパッケージコレクショ" +"ンを提供しているところのコミュニティがサポートする conda-forge チャンネルを含" +"めて、 Anaconda.org の複数のチャンネルから利用可能です。" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "スタンドアローンのコマンドラインツールをインストールする" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" +"多くのパッケージは、コマンドラインアプリケーションを提供しています。そのよう" +"なパッケージの例としては、 `mypy `_ ・ " +"`flake8 `_ ・ `black `_ ・ :ref:`pipenv` が挙げられます。" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" +"通常ならシステムのどこからでもこれらのアプリケーションにアクセスできるように" +"したいと思うでしょうが、パッケージとその依存先パッケージを同じグローバル環境" +"にインストールすると、バージョンの衝突を起こしてオペレーティングシステムが" +"持っている Python パッケージ間の依存関係を破壊してしまうかもしれません。" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" +":ref:`pipx` は、 ``$PATH`` に含まれるディレクトリを通してアプリケーションにア" +"クセスできるようにしつつ各パッケージに仮想環境を作成することでこの問題を解決" +"します。こうすることで、各パッケージの更新や削除をしても他のパッケージには影" +"響を与えず、どこからでもアプリケーションを安全に走らせることができるようにで" +"きます。" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "pipx は Python 3.6+ でのみ動作します。" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "pipx は pip と一緒にインストールされています:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" +"``ensurepath`` は、アプリケーションのあるディレクトリが ``$PATH`` に含まれる" +"ようにすることを保証します。この更新(訳注、``$PATH``の修正のこと)が効果を持つ" +"ようにするためにターミナルを再起動する必要があるかもしれません。" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" +"これで、 ``pipx install`` を使ってパッケージをインストールすることができるよ" +"うになり、どこからでもそのパッケージのアプリケーションを起動することができる" +"ようになりました。" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "例:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" +"pipx でインストールされたパッケージのリストやどんなアプリケーションが使用可能" +"かを見るためには、 ``pipx list`` を使ってください:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "パッケージを更新またはアンインストールするには:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "pipx は pip を使って更新やアンインストールができます:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" +"また、pipx ならアプリケーションの最新版を一時的で短命の環境にインストールして" +"動作させることができます。例えば:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" +"pipx で使える(サブ)コマンドの完全なリストを見たければ、次のようにしてくださ" +"い:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +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 "" +"Linux パッケージマネージャを使って pip/setuptools/wheel をインストールする" + +#: ../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 section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" +"この節では、Linux のパッケージマネージャを使って :ref:`pip` " +"・ :ref:`setuptools` ・ :ref:`wheel` をインストールする方法について説明しま" +"す。" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" +"`python.org `_ からダウンロードした Python を使ってい" +"るなら、この節の議論はあてはまりません。代わり" +"に :ref:`installing_requirements` 節を見てください。" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +msgstr "" +"特定の Linux ディストロでサポートされているバージョンの :ref:`pip` " +"・ :ref:`setuptools` ・ :ref:`wheel` が公開時点で既に旧バージョンになってし" +"まっているのに、更新されるのはセキュリティが理由の時だけで機能追加があっても" +"更新されない、というのはよくあることです。ディストロの中にはより新しいバー" +"ジョンを提供することができる追加のリポジトリが存在する場合もあります。以下で" +"は、そのようなリポジトリのうちの既知のものを説明します。" + +#: ../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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "Fedora" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"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/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "CentOS/RHEL" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" +"CentOS と RHEL は、そのコアリポジトリでは :ref:`pip` や :ref:`wheel` を提供し" +"ていませんが、 :ref:`setuptools` はデフォルトでインストールされます。" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" +"システムに付属の Python 用に pip や wheel をインストールするには、二つのやり" +"方があります:" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" +"`これらの指示 `__ " +"を使って、 `EPEL リポジトリ `_ を有効に" +"してください。 EPEL 7 では、pip と wheel をこんなふうにインストールできます:" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" +"EPEL はシステムに欠けていて衝突しないパッケージだけを提供しているので、コアリ" +"ポジトリに入っている setuptools は EPEL にはありません。" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" +"`これらの指示 `__ [1]_ に従って `PyPA Copr Repo `_ を有効にしてください。 pip と " +"wheel はこうやってインストールできます:" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "さらに setuptools を更新するには、次のようにしてください:" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" +"システムの環境とは別に (yum を使って) pip ・ wheel ・ setuptools をインストー" +"ルするには、ふたつのやり方があります:" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" +"pip ・ setuptools ・ wheel を含むコレクションを (システムとは) 並行に有効化し" +"て \"ソフトウェアコレクション\" 機能を使ってください。" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" +"Red Hat についてはこちらを見てください: https://developers.redhat.com/" +"products/softwarecollections/overview" + +#: ../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 "" +"コレクションに含まれているバージョンが最新版であるとは限らない点に注意してく" +"ださい。" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" +"`IUS リポジトリ `_ を有効にして、かなり最新版に近い状態" +"に維持されている pip ・ setuptools ・ wheel と一緒に `並列インストール可能 " +"`_ な Python の内のひとつ" +"をインストールしてください。" + +#: ../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 "" +"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 "" +"最近のバージョンの Debian/Ubuntu は、 pip がデフォルトで `\"User Scheme\" " +"`_ を使うように修正" +"されていますが、これはユーザの一部を驚かせるような重要な動作の変更に当たるで" +"しょう。" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "Arch Linux" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +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 を使って仮想環境にパッケージをインストールする" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +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 の準備をする" + +#: ../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 "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" +"このガイド文書は、サポートされている Python のバージョン、現時点では 3.8 およ" +"びこれ以降のものに適用されます。" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" +"この文書では、 **パッケージ** という用語を通常は外部のホストからインストール" +"される :term:`配布パッケージ ` の意味で使います。これ" +"は Python ソースコードでモジュールをインポートするという意味で使われ" +"る :term:`インポートパッケージ ` とは異なります。" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" +"このガイド文書は、 から取得する公式の " +"Python を使っていることを前提条件にしています。Python をインストールするのに" +"オペレーティングシステムのパッケージマネージャを使っているのであれば、ここに" +"述べるようなステップを進める前に、Python がインストールされていることを確実に" +"してください。" + +#: ../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 "" +":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 "" +":ref:`venv` (Python 3 用) を使うと、異なるプロジェクトにそれぞれ別のパッケー" +"ジをインストールして管理できます。(仮想環境は) 互いに影響を与えない\"仮想的な" +"\" Python インストール環境を生成します。別のプロジェクトに移動すると、他の仮" +"想環境から隔離された新しい仮想環境を作成することができます。仮想環境を使うこ" +"とで、パッケージ群を自信を持ってインストールすることができ、他のプロジェクト" +"の環境には干渉しないであろうことから、あなたは利益を得ることができます。" + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" +"仮想環境を作成するには、プロジェクトのディレクトリへ行って次のようなコマンド" +"を実行してください。これによって、ローカルの ``.venv`` フォルダに新しい仮想環" +"境ができるでしょう:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" +"二つ目の引数は、仮想環境を作成するべき場所の指定です。一般的には、プロジェク" +"トのルートディレクトリに ``.venv`` という名前で作成します。" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" +"``venv`` は仮想的な Python を ``.venv`` ディレクトリの中にインストールするで" +"しょう。" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" +"仮想環境のディレクトリは、 ``.gitignore`` やその類似物を使ってバージョン管理" +"システムから除外しておくべきです。" + +#: ../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 "" +"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 "" +"仮想環境に (依存先の) パッケージをインストールして使用できるようにするには、" +"まず仮想環境を ``activate`` しなければなりません。仮想環境を活性化すると、そ" +"の仮想環境に特有の ``python`` と ``pip`` の実行ファイルがシェルの ``PATH`` 変" +"数に追加されます。" + +#: ../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 "" +"仮想環境が activate されたことを確認するには、 Python インタープリタの場所を" +"確かめましょう:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" +"仮想環境が active である間は、上記のコマンドは ``.venv`` ディレクトリを含む" +"ファイルパスを出力することでしょう、つまり以下のようになって終了します:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" +"仮想環境が active である間は、pip はパッケージをその仮想環境内にインストール" +"します。これによって、あなたの Python アプリケーションからそのパッケージをイ" +"ンポートして使用することができるようになります。" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "仮想環境を非活性化 する" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" +"プロジェクトを切り替えたい、あるいは、仮想環境から離脱したい時は、仮想環境を " +"``deactivate`` してください:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" +"シェルを終了すれば、仮想環境を非活性化 することになるでしょう。" +"もし、新しいシェル窓を開いて、そこで仮想環境を使いたい時は、再活性化 " +" してください。" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "仮想環境を再活性化 する" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" +"既存の仮想環境を活性化 したい場合は、仮想環境の活性化に関する上述" +"のやり方に従ってください。新しい仮想環境を作成する必要はありません。" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" +":ref:`pip` は Python の参照モデルとなるパッケージマネージャです。仮想環境内で" +"パッケージのインストールや更新に用いられます。" + +#: ../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/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" +"それから、ユーザサイトには最新版の pip がインストールされているはずです:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" +"Windows 用の Python インストーラは pip を含んでいます。以下のようにすると " +"pip が最新版であることを確実にすることができます:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst: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 を使ってパッケージをインストールする" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" +"仮想環境が活性化状態にある時には、パッケージ群をインストールすることができま" +"す。パッケージをインストールするには ``pip install`` コマンドを使ってくださ" +"い。" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "パッケージをインストールする" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" +"例として、 :term:`Python Package Index (PyPI)` から `Requests`_ ライブラリを" +"インストールしてみましょう:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" +"pip が requests とその依存先パッケージをすべてダウンロードしてインストールす" +"るはずです:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "特定のバージョンのパッケージをインストールする" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" +":term:`version specifiers ` を使えば、 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/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" +"``--pre`` フラグを使ってパッケージのリリース前のバージョンをインストールする" +"には:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +msgid "Install extras" +msgstr "(パッケージの) extra 部分をインストールする" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" +"必須ではない `extra`_ 部分を持つものがパッケージの中にはあります。extra の名" +"前を角括弧([, ])の中に書くことで pip にインストールするように指示することがで" +"きます。" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "ソースコードからパッケージをインストールする" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" +"pip は、ソースコードから直接にパッケージをインストールすることができます。例" +"えば、 ``google-auth`` ディレクトリの中にあるソースコードをインストールするに" +"は:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +msgid "" +"Additionally, pip can install packages from source in :doc:`development mode " +"`, meaning that changes to the source " +"directory will immediately affect the installed package without needing to " +"re-install:" +msgstr "" +"さらに、 pip は :doc:`開発モード ` で" +"ソースコードからパッケージをインストールすることができます。つまり、ソース" +"コードを修正すると、再インストールしなくても、すぐにインストール済みのパッ" +"ケージに反映されます。" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" +"pip は、バージョン管理システムから直接に、パッケージをインストールすることが" +"できます。例えば、git リポジトリから直接にインストールするには:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" +"サポートされているバージョン管理システムや文法について、詳しくは :ref:`VCS サ" +"ポート ` の pip の説明文書を見てください。" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "ローカルアーカイブからインストールする" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" +"もし :term:`配布パッケージ ` のアーカイブ ( zip や " +"wheel や tar ファイル) をローカルに持っているなら、 pip でそこから直接にイン" +"ストールすることができます:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" +"複数のパッケージのアーカイブを置いたディレクトリを pip に探索させるようにし" +"て、:term:`Python パッケージインデックス ` を全" +"く利用しないということも可能です:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" +"この機能は、限定的なインターネット接続しか得られないシステムでパッケージをイ" +"ンストールする際や、配布物パッケージの出自を厳密に管理したい時には便利です。" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "他のインデックスサイトからインストールする" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" +":term:`Python パッケージインデックス ` 以外のと" +"ころからパッケージをダウンロードしたいのであれば、 ``--index-url`` オプション" +"でできます:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" +":term:`Python パッケージインデックス ` と別のイ" +"ンデックスを同時に使いたいのであれば、 ``--extra-index-url`` オプションででき" +"ます:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "パッケージを更新する" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" +"pip に ``--upgrade`` オプションを与えるとパッケージの入れ替え更新ができます。" +"例えば、 ``requests`` とその依存先パッケージの最新版をインストールしたいのな" +"ら:" + +#: ../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 "" +"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 "" +"パッケージをひとつひとつインストールする代わりに、pip で" +"は :ref:`Requirements ファイル ` にすべての依存先パッ" +"ケージを列挙しておくことができます。例えば、 :file:`requirements.txt` を下記" +"を含むように作成しておいて:" + +#: ../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 "" +"このファイルに書いてあるパッケージを全てインストールするようにと、 ``-r`` オ" +"プションを与えることで pip に指示します:" + +#: ../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 "" +"Pip can export a list of all installed packages and their versions using the " +"``freeze`` command:" +msgstr "" +"Pip では、 ``freeze`` コマンドを使うことで、インストール済みの全パッケージの" +"バージョン付きのリストを取り出すことができます:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 +msgid "Which will output a list of package specifiers such as:" +msgstr "それは、次に挙げるようなパッケージ指定子のリストを出力します:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" +"``pip freeze`` コマンドは、環境内にインストール済みのすべてのパッケージの正確" +"なバージョンを再生成することができる :ref:`pip:Requirements Files` を作成する" +"のに便利に使えます。" + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "virtualenv を使ってパッケージをインストールする" + +#: ../source/guides/installing-using-virtualenv.rst:4 +msgid "" +"This guide discusses how to install packages using :ref:`pip` " +"and :ref:`virtualenv`, a tool to create isolated Python environments." +msgstr "" +"このガイド文書では、:ref:`pip` と隔離された Python 環境を作成するツールである" +"ところの :ref:`virtualenv` を使ってパッケージをインストールする方法について議" +"論します。" + +#: ../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/installing-using-virtualenv.rst:13 +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." +msgstr "" +"この文書では **パッケージ** という用語を :term:`配布パッケージ ` の意味で使いますが、これは Python ソースコードでモジュールをイン" +"ポートするという意味で使われる :term:`パッケージインポート ` " +"とは異なります。" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "ライセンシングの例とユーザシナリオ" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" +":pep:`639` では、 :term:`配布物アーカイブ ` のライセン" +"スを宣言する方法やライセンスファイルへのパス、そして、その他の法的に要求され" +"る情報を仕様化しています。この説明文書は、レガシーなライセンス宣言から標準化" +"されたそれへどのようにして移行するのかに関する明確なガイダンスを提供すること" +"を目的としています。より新しいガイダンスを適用しようと試みる前に、好みのビル" +"ドバックエンドが :pep:`639` をサポートしていることを確認してください。" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "ライセンシングの例" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "基本的な例" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" +"Setuptools プロジェクトそれ自体は、 `version 75.6.0 `__ 時点" +"で、自身のプロジェクトソースコードのメタデータ内の ``License`` フィールドを" +"使っていません。さらに、共通のパターンにマッチさせることで現在使用してい" +"る :file:`LICENSE` のようなライセンスに関係するファイル群を自動的に含める自身" +"の仕組みに立脚しているので、以前にはそうしていましたがもはや " +"``license_file`` / ``license_files`` を明示的に指定することもしていません。" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" +"以下のようなライセンスに関連するメタデータを :file:`pyproject.toml` の中に含" +"みます:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "PEP 639 への最も単純な移行は、代わりにこれを使うことから構成されます:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" +"あるいは、プロジェクトで :file:`setup.cfg` を使っているなら、その中の " +"``[metadata]`` テーブルで:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" +":term:`配布パッケージ ` のためのコアとなるメタデータの" +"出力はこんなふうになるでしょう:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" +":file:`LICENSE` ファイルは、 sdist 内なら :file:`/setuptools-{VERSION}/" +"LICENSE` に、 wheel 内なら :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` に、そこから展開されるとインストール先のサイトディレクトリ (例え" +"ば :file:`site-packages/`) に置かれることでしょう; ここで :file:`/` はそれぞ" +"れのアーカイブのルートディレクトリであり、 ``{VERSION}`` はコアとなるメタデー" +"タ内の Setuptools のリリースのバージョンです。" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "先進的な例" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" +"仮に Setuptools が、 :file:`setuptools/_vendor/` と :file:`pkg_resources/" +"_vendor/` のディレクトリ内に第三者のプロジェクトのライセンスを包含していたと" +"しましょう; 特にこの場合は:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "適切なライセンス表現は:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" +"Setuptools 純正のものとベンダーが取り込んだものの両方をカバーするこみいったラ" +"イセンス条項をすべてひとつにまとめて、これらのメタデータを包含することになる" +"でしょう。そのような条項はこんなものになるでしょう:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" +"加えて、ライセンスの要求事項次第で、パッケージ内に適切なライセンスファイルが" +"含まれていなければなりません。 :file:`LICENSE` ファイルには Setuptools や " +"``pyparsing`` や ``more_itertools`` や ``ordered-set`` が使用する MIT ライセ" +"ンスとコピーライトが含まれているものと思ってください; そし" +"て、:file:`setuptools/_vendor/packaging/` ディレクトリの :file:`LICENSE*` " +"ファイル群には Apache 2.0 と 2 項の BSD ライセンスの文言があり、Packaging コ" +"ピーライト文言や `ライセンス選択通知 `__ があるものと思っ" +"てください。" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" +"明確にいうと、ライセンスファイル群はプロジェクトソースコードツリー内の以下の " +"(プロジェクトルートと :file:`pyproject.toml` からの相対) パスに位置するものと" +"仮定しています:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" +"これらをすべて一緒にすると、 :file:`pyproject.toml` はこんなふうになるでしょ" +"う:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" +"あるいは、別の方法としては、ライセンスファイル群を明示的に示すこともできます " +"(パスはglobパターンとして解釈されるでしょう):" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" +":file:`setup.cfg` をプロジェクトで使っているなら、こんなふうに定義することが" +"できます:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" +"どちらのアプローチでも、配布物内のコアとなるメタデータの出力はこんな風になる" +"でしょう:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" +"結果として生成される sdist の中には、 :file:`/` をアーカイブのルートディレク" +"トリとし、 ``{VERSION}`` をコアとなるメタデータの中で指定された Setuptools の" +"バージョン番号として、ライセンスファイル群が次のようなパスに配置されるでしょ" +"う:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" +"ビルド済みの wheel では、 :file:`/` をルートディレクトリとし、 ``{VERSION}`` " +"を先述の通りとして、ライセンスファイル群は次の場所に保存されるでしょう:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" +"最後に、インストールされたプロジェクトでは、 :file:`site-packages/` をサイト" +"ディレクトリとし、 ``{VERSION}`` を先述の通りとして、ライセンスファイル群は次" +"の場所にインストールされるでしょう:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "表現 の例" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "いくつかの追加の ``License-Expression`` の正当な値の例:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "ユーザシナリオ" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" +"以下では、それぞれにガイダンスを提供しながら、ユーザ視点からのよくあるユース" +"ケースをカバーします。以下に述べることを法律上の推奨事項であると見做すべきで" +"は **ない** ことを銘記するとともに、読者は、それぞれの状況に応じた細部につい" +"て確信を持てないならば、それを法律上の管轄範囲とするライセンスを持った法律実" +"務家に相談するべきす。" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "配布するつもりのないプライベートなパッケージがあります" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" +"そのパッケージが、例えば会社や組織あるいは家庭の外に公開・共有されていないな" +"ら、 *通常は* 厳格に公式のライセンス (ファイル) を含める必要があるわけではあ" +"りませんし、だからここで何か追加の作業をする必要があるわけではないでしょう。" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" +"しかしながら、それでも、パッケージングツール群によって自動的に取り込まれるで" +"あろうプロジェクトのルートディレクトリの :file:`LICENSE.txt` ファイルの中に、" +"パッケージの設定の中にライセンス条項として ``LicenseRef-Proprietary`` や著作" +"権情報やその他の法的通知を含めておくことは良い考えです。" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "自分の作品を法的制限なしに共有したいだけです" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" +"ライセンスを含めておくように要求されてはいない一方で、含めておかなければ皆が " +"`その作品のダウンロード、使用、または改良の許可なし `__ " +"の状態になりますが、それは多分、作者が実際に望んでいることとは *真逆* のこと" +"でしょう。 `MIT ライセンス `__ は、簡明で広く使われており" +"作品に対して誰でも (多分作者も望まないでしょうが、作者相手に訴訟を起こす以外" +"の) どんなことでも許容するので、その代替として偉大な選択肢です。" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" +"これを適用するには、単にリポジトリのルートディレクトリにあ" +"る :file:`LICENSE.txt` と名付けられたファイルに `テキスト " +"`__ を貼り付けて、年とあなたの名前をコピーライトの行に追" +"加して下さい。それから、パッケージングツールがサポートしている場合は " +"``license = \"MIT\"`` を :file:`pyproject.toml` の中の ``[project]`` の下か、" +"あるいは、設定ファイル・節の中に追加してください。これで出来上がりです！" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "プロジェクトを特定のライセンスの下で配布したい" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" +"特定のライセンスを使用するには、もし :file:`LICENSE` または :file:`COPYING` " +"で始まるファイルを既に置いているのでなければ、単にリポジトリのルートディレク" +"トリにある :file:`LICENSE.txt` ファイルの中にそのテキストを貼り付けて、 使っ" +"ているパッケージングツールがサポートしているなら :file:`pyproject.toml` の中" +"の ``[project]`` の下に ``license = \"LICENSE-ID\"`` を追加するか、そうでなけ" +"れば設定ファイルの中に追加すれば良いだけです。 `ChooseALicense " +"`__ や `SPDX `__ のようなサイトに行けば、 " +"``LICENSE-ID`` とコピー可能なライセンス条項を見つけることができるでしょう。" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" +"多くの人気のあるソースコードホスト・プロジェクトテンプレート・パッケージング" +"ツールによってライセンスファイルを加えることができ、将来に渡って表現をサポー" +"トするでしょう。" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "既にライセンスが付与された既存パッケージを維持管理しています" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" +"ライセンスファイルやプロジェクト内のメタデータが既に存在しているなら、新機能" +"の利点を得るためには2,3の捻りを加えるだけで良いはずです。" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" +"プロジェクト設定ファイルにおいて、ライセンス条項を ``license`` " +"(:file:`pyproject.toml` の ``[project]`` テーブル) の下か、使っているパッケー" +"ジングツールでの相当する場所に置き、古いやり方である ``license`` テーブルサブ" +"キーや ``License::`` 分類子を取り除くのを忘れないでください。既存の " +"``license`` 値は、そのままでも正当なもの (例えば ``MIT`` や ``Apache-2.0 OR " +"BSD-2-Clause`` 等) かもしれません; そうでなければ、採用しているライセンスに合" +"致する識別子を `SPDX ライセンスリスト `__ で確認して下さい。" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" +":file:`pyproject.toml` の中の ``[project]`` の下の ``license-files`` か、使用" +"しているツールの設定ファイルに、ライセンスファイル群を列挙しておくのを忘れな" +"いでください。" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" +"これが実際にどのように動作するのかに関する、簡明ではあるが一通り揃った実世界" +"でのデモが、 :ref:`licensing-example-basic` に出ています。また、ライセンス分" +"類子からライセンス条項へ対応付けるやり方に関するベストエフォートのガイダンス" +"が :pep:`639` の著者達によって提供された `ライセンス分類子から SPDX 識別子へ " +"`__ にありますので、こちらもご覧ください。パッケー" +"ジングツールが、レガシーのライセンスメタデータを自動的に変換する機能を持って" +"いるかもしれませんので、さらなる情報を得るために使っているツールの説明文書を" +"調べて下さい。" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "私のパッケージには異なるライセンスの他のソースコードが含まれています" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" +"プロジェクトが、提供された依存関係ないし他のオープンソースソフトウェアからコ" +"ピーされたファイル群のような、相異なるライセンスでカバーされたソースコードを" +"含んでいるなら、関与するライセンスとそれらの間の関係を記述するために、ライセ" +"ンス条項を構築することができます。" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" +"端的に言えば、 ``License-1 AND License-2`` は *両方の* ライセンスが適用される" +"こと (例えば、同梱されたあるファイルがもう一つの方のライセンスの下にある) を" +"意味し、また、 ``License-1 OR License-2`` では、ユーザの選択によって、 *いず" +"れか一方の* ライセンスを使用することができます (例えば、複数のライセンスから" +"一つを選ぶことをユーザに許したい) 。もっと込み入った状況でさえもカバーできる" +"表現を組み立てるためのグループ化のために括弧 (``()``) を使うことができます。" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" +"プロジェクトの設定ファイルで、 (:file:`pyproject.toml` の ``[project]`` テー" +"ブルの) ``license`` の下にライセンス表現を入れるか、または、使用しているパッ" +"ケージングツールの同等物を入れるか、いずれかを行なって、旧来の ``license`` " +"テーブルサブキーや ``License::`` 分類子を削除するのを忘れないでください。" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" +"また、すべてのライセンスの全文をプロジェクトリポジトリのどこかにファイルの形" +"で追加しておくのを忘れないでください。 (ツールが対応しているな" +"ら) :file:`pyproject.toml` 内の ``[project]`` の下の ``license-files`` の下" +"に、それら一つひとつの相対パスか glob パターンを列挙するか、使用しているツー" +"ルの設定ファイルに列挙して下さい。" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" +"例として、もしプロジェクトが MIT ライセンスを適用していて、しかし、他所から提" +"供された依存関係 (ここでは ``packaging`` としましょう) が Apache 2.0 もしく" +"は ２条項 BSD でライセンスされているなら、ライセンス表現は ``MIT AND " +"(Apache-2.0 OR BSD-2-Clause)`` のようになるでしょう。すべてのライセンス全文を" +"リポジトリに入れておくために、リポジトリのルートディレクトリ" +"に :file:`LICENSE.txt` を置き、 :file:`_vendor/` サブディレクトリの下" +"に :file:`LICENSE-APACHE.txt` と :file:`LICENSE-BSD.txt` を置くでしょうし、 " +"glob パターンとして ``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` の" +"ように指定するか、あるいは、リテラルのファイルパスとして ``[\"LICENSE.txt\", " +"\"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-BSD.txt\"]`` のように指定す" +"ることでしょう。" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" +"これを現実世界の複雑なプロジェクト向けに完全に作業を尽くした、エンドトゥーエ" +"ンドなアプリケーションのための :ref:`licensing-example-advanced` を、多くの技" +"術面での詳細とともに見てほしいのと、さらなる手助けや SPDX の識別子と表現を" +"使った例を `チュートリアル `__ で当たってみて下さい。" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "PyPI によく合う README を作る" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" +"README ファイルは、あなたのパッケージのユーザがプロジェクトを理解するのを助" +"け、プロジェクトの説明をするのに使われています。このガイドでは、PyPI によく合" +"う形で README を作成するのを助け、あなたのパッケージの README が PyPI で表示" +"されるようにします。" + +#: ../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 "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" +"Python プロジェクトにおける READMEファイルは、しばしば ``README`` ・ " +"``README.txt`` ・ ``README.rst`` ・ ``README.md`` などと命名されます。" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" +"あなたの README を PyPI で正しく表示するためには、PyPI がサポートするマーク" +"アップ言語を選択する必要があります。 `PyPI の README レンダラ `_ としてサポートされているのは:" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "プレーンテキスト" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" +"`reStructuredText `_ (Sphinx 拡張な" +"し)" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" +"マークダウン (デフォルトでは `GitHub Flavored Markdown `_ 、あるいは `CommonMark `_)" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" +"README ファイルについては、 :file:`setup.py` ファイルと同様にプロジェクトの" +"ルートディレクトリに置くのが慣習になっています。" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "README にパッケージのメタデータを含ませる" + +#: ../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/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" +"例えば、これらの値をパッケージの :file:`setup.py` ファイルに設定するために" +"は、 ``setup()`` の ``long_description`` と " +"``long_description_content_type`` を使ってください。" + +#: ../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``." +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 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" +"プロジェクトの説明を GitHub 方言のマークダウンで書くのであれば、以下のツール" +"を更新しておくことを忘れないでください:" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "各ツールは少なくとも次のバージョンでなければなりません:" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" +"プロジェクトの配布物パッケージをアップロードする時は ``twine`` を使うことを推" +"奨します。" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" +"例えば、この :file:`setup.py` ファイルでは、 :file:`README.md` の内容を読み" +"取って ``long_description`` としていて、マークアップ方式は GitHub 方言のマー" +"クダウンを指定しています:" + +#: ../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 "" +"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 "" +"README を reStructuredText で書いている場合、無効なマークアップがひとつでもあ" +"ると描画できないので、PyPI 上では README の生のソースコードを表示するだけに" +"なってしまいます。" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" +":doc:`ディレクティブ ` と :doc:`" +"ロール ` (例えば " +"\"``:py:func:`getattr```\" や \"``:ref:`my-reference-label```\") のように " +"docstrings 内で使われる Sphinx 拡張はこの場所では使用を許されず、 ``Error: テ" +"キストロール \"py:func\" が見つかりません。`` といったエラーメッセージを出すことになります。" + +#: ../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/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +msgstr "" +"最新版の `twine `_ をインストールします; バー" +"ジョン 1.12.0 またはそれ以上のものが必須です:" + +#: ../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/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 "" +"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/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 "" +":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/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 "" +"2016年9月以降、 ``pypi.org`` がデフォルトのアップロードプラットフォームです。" + +#: ../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/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/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" +"``pypi.org`` に転換するためのデフォルトのアップロード設定は次のようなバージョ" +"ンです:" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../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 "" +"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 "" +"ツールのデフォルト設定が切り替わっている程に十分に新しいツールを使っているこ" +"とを確認するのに加えて、そのデフォルトのアップロード先 URL を上書きするような" +"設定をしていないことを確実にしてください。これは典型的に" +"は :file:`$HOME/.pypirc` で設定されています。もしこんなファイルを目にするよう" +"であれば:" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" +"その時は、 ``repository`` で始まる行を削除するだけで、アップロードツールのデ" +"フォルト URL を使うようになります。" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +msgstr "" +"なんらかの事情でPyPI.orgをデフォルトで使うところまでアップロードツールのバー" +"ジョンを上げられないのであれば、 :file:`$HOME/.pypirc` で ``repository:`` 行" +"が ``https://upload.pypi.org/legacy/`` を指すように編集しても構いません。" + +#: ../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/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "パッケージの名前とメタデータを登録する" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" +"初回のアップロードに先立って ``setup.py register`` コマンドでパッケージの名前" +"を明示的に先行登録する必要がなくなり、PyPI.org における以前のアップロード " +"API のエミュレーションではサポートされなくなりました。" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" +"その結果、アップロードに PyPI.org を使うように切り替えた後は、明示的な登録の" +"試行は次のエラーメッセージを返すでしょう::" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" +"解決方法は登録の段階を飛ばしていきなり作品のアップロードへと進むことです。" + +#: ../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 "" +"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 (testpypi.python.org) はもはや利用できませんので、代わり" +"に `test.pypi.org `_ を使ってください。 TestPyPI を使" +"うのであれば、 :file:`$HOME/.pypirc` で ``https://testpypi.python.org/pypi`` " +"を ``https://test.pypi.org/legacy/`` に置き換えるなどして、 TestPyPI の新しい" +"場所を使うように設定しなければなりません。例えば:" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "新しいユーザアカウントを登録する" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" +"PyPI に対するスパム攻撃を緩和する補助するために、 ``pypi.python.org`` におけ" +"る新規ユーザ登録は **2018年2月20日** に *終了* しました。 ``pypi.org`` での新" +"規ユーザ登録が始まっています。" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "パッケージを一覧する" + +#: ../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." +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/migrating-to-pypi-org.rst:136 +msgid "``pypi.org`` is the default host for downloading packages." +msgstr "" +"``pypi.org`` が、パッケージをダウンロードする際のデフォルトのホストです。" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "公開済みパッケージとリリースを管理する" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +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/modernize-setup-py-project.rst:12 +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`." +msgstr "" +":term:`pyproject.toml` ファイルは強く推奨されていま" +"す。:file:`pyproject.toml` ファイルが存在すること自体は多くをもたらすものでは" +"ありません。 [#]_ 実際に強く推奨されているものは、:file:`pyproject.toml` の中" +"の ``[build-system]`` テーブルです。" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" +"以下のように、これが pip のビルド隔離機能に影響を与えるということを銘記してく" +"ださい。" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" +"いいえ、 :file:`setup.py` は、近代的な :ref:`setuptools` ベースのプロジェクト" +"にあっても構いません。 :term:`setup.py` ファイルは、たまたま Python で書かれ" +"ている setuptools 向けの正当な設定ファイルなのです。しかしながら、以下のコマ" +"ンド群は非推奨になっていてもはや実行することは **許されず** 、その代わりに以" +"下のようなコマンドを使用するべきです:" + +#: ../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 "" +"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 "" +":term:`プロジェクト ` のソースコードツリーのルート部分には、次に示す" +"ように、 ``[build-system]`` テーブルを含む :file:`pyproject.toml` がなければ" +"なりません:" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" +"これは、 :term:`ビルドフロントエンド ` にこのプロジェクト" +"の :term:`ビルドバックエンド ` は :ref:`setuptools` だと知らせ" +"るための標準化されたやり方です。" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" +"(空のファイルであっても) :file:`pyproject.toml` ファイルが存在していれ" +"ば、 :ref:`pip` が *ビルド隔離 * を取り扱うデフォルトの動き" +"が変わることに注意してください。" + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr ":ref:`配布パッケージ `" + +#: ../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/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`" +msgstr ":doc:`pip:reference/build-system`" + +#: ../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 "" +"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 "" +"setuptools それ自体の上に、もし :file:`setup.py` が他の (Python の標準ライブ" +"ラリの外側の) 第三者のライブラリに依存しているのであれば、 :term:`配布物 " +"` をビルドする際にビルドフロトンエンドがそれらをインス" +"トールする必要があることを知るために、 ``[build-system]`` テーブルの " +"``require`` リストに挙げられていなければなりません。" + +#: ../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/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" +":file:`pyproject.toml` ファイルはこのようであることが要求されます " +"(:file:`setup.py` には変更なし):" + +#: ../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 "" +"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 "" +"典型的な場合、ビルドフロントエンドは、 ``build-system.requires`` の下に列挙さ" +"れているビルド時の依存関係 (と、その依存関係)だけをインストールする先としての" +"一時的な仮想環境を作成し、その環境内でビルドを開始します。" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" +"この隔離が不要な一部のプロジェクト向けには、以下のようにすれば (隔離を) 非活" +"性化することができます:" + +#: ../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/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" +"静的なメタデータはすべて、 :file:`pyproject.toml` の ``[project]`` テーブルへ" +"移しても構いません。" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" +"このように :file:`pyproject.toml` ファイルで完全に置き換えることも可能です:" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" +"``[project]`` テーブル内で許される内容の完全な仕様について" +"は、 :ref:`pyproject-project-table` を読んでください。" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "動的なメタデータをどのように取り扱いますか？" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" +"パッケージングであるメタデータフィールドが静的ではないならば、 ``[project]`` " +"テーブルの ``dynamic`` に列挙する必要があります。" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "以下のように近代化することができるでしょう:" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" +":ref:`プロジェクトのメタデータを動的であると宣言する `" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" +"変更不能ななにかが ``setup.py`` ファイルがあるものと期待していたらどうします" +"か？" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" +"例えば、簡単には変更することができないプロセスが存在していて、それが " +"``python setup.py --name`` のようなコマンドの実行を必要としてる場合。" + +#: ../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` へ移された後であっても、プロジェク" +"トのソースコードツリーに :file:`setup.py` を残すことは完全に問題のないことで" +"す。このファイルの最小限の姿はこのようになります:" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr ":ref:`pyproject-toml-spec`" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr ":doc:`setuptools:build_meta`" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "複数バージョンのインストール" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" +"easy_install を使えば、異なるバージョンの同一プロジェクトをひとつの環境に同時" +"にインストールして、なおかつ、それぞれ動作時にプロジェクトの特定のバージョン" +"を (``pkg_resources`` での指定を通じて) ``要求 `` する複数のプログラ" +"ムをその環境で動作させることができます。" + +#: ../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." +msgstr "" +"多くのユースケースでは、 ``require`` ディレクティブを混乱させる事なく、仮想環" +"境がこのような需要を満たします。しかしながら、同一環境内に(複数バージョンを)" +"並行してインストールすることの利点は、Linux 配布物におけるシステム側の " +"Python のように、複数のアプリケーションによって共有される環境で動作することで" +"す。" + +#: ../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." +msgstr "" +"並行インストールに立脚した ``pkg_resources`` の主要な制限事項は、 " +"``pkg_resources`` をインポートするや否や、sys.path 上で既に利用可能なものはす" +"べてそのバージョンに *デフォルト* バージョンが固定されてしまうことです。コマ" +"ンドラインスクリプトで生成された ``setuptools`` が ``pkg_resources`` を使って" +"プログラム実行のためのエントリポイントを探索するので、これは問題を引き起こす" +"かもしれません。これが意味するところは、例えば、そのアプリケーションが、標準" +"の ``sys.path`` 上に存在するものなら何であれ、それとは異なるバージョンを必要" +"とする場合に、 ``nose`` を通じて ``require`` テストを使ったり ``gunicorn`` を" +"通じて WSGI アプリケーションを呼び出したりすることができない - メインのアプリ" +"ケーションのためのスクリプトラッパがデフォルトで利用可能なバージョンに固定さ" +"れてしまって、各アプリケーションの引き続く ``require`` 呼び出しが見せかけの" +"バージョン衝突によって失敗してしまう、ということです。" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" +"最初に ``pkg_resources`` をインポートするよりも前に " +"``__main__.__requires__`` の中のすべての依存関係を設定しておくことでこの問題" +"を回避することができますが、このアプローチでは影響を受けるツールを標準のコマ" +"ンドラインからの呼び出しで使うことができないことになります - つまり、独自の" +"ラッパスクリプトを書くか、アプリケーションの main エントリポイントを直接に呼" +"び出すための ``python -c ''`` を使うかしなければなりません。" + +#: ../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" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" +"CPython の参照インタープリタの機能の一つは、Python のコードを実行することに加" +"えて、他のソフトウェアによる利用のために豊富な C の API を露出することです。" +"この C の API の最もよくある利用方法は、純粋な Python のコードでは必ずしも簡" +"単には達成できないようなことをインポート可能な C 拡張として作成することです。" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "バイナリ拡張の概要" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "ユースケース" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" +"バイナリ拡張の典型的なユースケースは、たった３個の伝統的なカテゴリに分類され" +"ます:" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" +"**アクセラレータモジュール**: これらのモジュールは完全に自己完結型で、" +"CPython で同機能の純粋なPython コードを走らせるよりも速く動作するためにだけ作" +"成されます。アクセラレートされたバージョンが当該システム上で動作しなかった時" +"のために、アクセラレータモジュールには同機能の純粋なPythonのコードを予備品と" +"して同梱していることが理想的です。CPython の標準ライブラリはアクセラレータモ" +"ジュールを多用しています。*例*: ``datetime`` をインポートする際、C での実装 " +"(`_datetimemodule.c `_) が使えない時には、`datetime.py `_ にフォールバックします。" + +#: ../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 `_." +msgstr "" +"**ラッパモジュール**: これらのモジュールは、既存の C のインタフェースを " +"Python に見せるために作られます。それらは C のインタフェースを直接に見せる" +"か、または、Python 言語の機能を使ってAPI をより使いやすくするようなもっと " +"\"Pythonic\" なやり方で見せるかします。CPython の標準ライブラリでは、ラッパモ" +"ジュールを多用しています。 *例*: `functools.py `_ は、 `_functoolsmodule.c `_ のための" +"ラッパモジュールです。" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" +"**低レベルシステムアクセス**: これらのモジュールは、CPython ランタイムやオペ" +"レーティングシステム、あるいはさらに下層のハードウェアの低レベルの機能にアク" +"セスするために作成されています。プラットフォームに固有のコードを通して、純粋" +"な Python コードでは不可能なことを拡張モジュールが達成できるかもしれません。" +"結構な数の CPython の標準ライブラリモジュールが C で書かれていて、言語のレベ" +"ルには提供されていないようなインタープリタの内部にアクセスできるようになって" +"います。 *例*: ``sys`` は `sysmodule.c `_ から来ています。" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" +"C 言語拡張の特筆すべき機能は、インタプリタランタイムにコールバックする必要の" +"ない時には、 (CPU制約であろうとIO制約であろうと関わりなく) 長時間走り続ける操" +"作を包む CPython グローバルインタプリタロックを解放することができるということ" +"です。" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" +"必ずしも全ての拡張モジュールが上記のカテゴリにぴたりと当て嵌まる訳ではありま" +"せん。例えば NumPy に含まれる拡張モジュールは３個のカテゴリのすべてにまたがっ" +"ています - 動作速度上の理由から内側のループを C 言語に移しているし、C 言語や " +"FORTRAN 言語その他で書かれた外部のライブラリをラップしているし、また、ベクタ" +"演算の並列実行や生成したオブジェクトのメモリレイアウトを正確な管理のために、 " +"CPython とその下にあるオペレーティングシステムの両方の低レベルなシステムイン" +"ターフェイスを利用しています。" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "欠点" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" +"バイナリ拡張を使うことの主たる欠点は、引き続くソフトウェア配布がより難しくな" +"ることです。Python を使う利点のひとつは非常に広範囲のクロスプラットフォームで" +"ある (訳注、同一の Python コードが広範囲の異種プラットフォームで動作する) こ" +"とですが、拡張モジュールを書くのに使われる言語 (典型的には C 言語や C++ だ" +"が、実際にはどんな言語でも CPython の C 言語 API にバインドできる) は異なるプ" +"ラットフォームには異なるバイナリを作成しなければならないのが普通なのです。" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "これが意味するところは、バイナリ拡張は:" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" +"エンドユーザがソースコードからビルドできるか、または、誰かが共通のプラット" +"フォーム向けにビルド済みのバイナリを公開するか、のいずれかでなければなりませ" +"ん" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "CPython 参照インタプリタのビルドが異なると互換性がないかもしれません" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" +"PyPy ・ IronPython ・ Jython のような代替インタプリタ上では動作しないことがし" +"ばしばです" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" +"もしハードコードされているなら、メンテナンス担当者が Python のみならずそのバ" +"イナリ拡張を作成するために使われている言語についてもCPython の C 言語 API に" +"ついても慣れ親しんでいることが要求されるので、メンテナンスがより難しくなるで" +"しょう。" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" +"純粋な Python で書かれた退避先実装が用意されているなら、変更を実装するべき場" +"所が２箇所になるのと、両方の実装が常に実行されることを保証するテストスイート" +"を準備するために複雑さが増加することになるので、メンテナンスがより一層困難に" +"なります。" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" +"バイナリ拡張に依存することによるさらなる欠点は、 (例えば zip ファイルから直接" +"にインポートする能力など) 通常とは異なるインポート機構が、しばしば拡張モ" +"ジュールでは動作しない (ほとんどのプラットフォームでは動的ロード機構はディス" +"クからライブラリを読み込むことしかできないため) ということです。" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "ハードコードされたアクセラレータモジュールの代わりとなるもの" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" +"拡張モジュールが単純にプログラムを速く走らせるためだけに使われてい (て、プロ" +"ファイリングの結果、メンテナンス工数が増えることを甘受しても速度を上げること" +"に価値があると判断され) る時には、他の複数の選択肢も検討しておくべきです:" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" +"既存の最適化された代替策を探す。CPython の標準ライブラリには、最適化された" +"データ構造やアルゴリズム (特に組み込み済みのものや ``collections`` および " +"``itertools`` モジュール) が多数含まれています。Python パッケージインデックス" +"にも他の代替となるパッケージがあります。時には、標準ライブラリや第三パーティ" +"のモジュールから適切なものを選択することで、自分自身でアクセラレータパッケー" +"ジを作成する必要に迫られないで済むでしょう。" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" +"長時間に渡って走り続けるアプリケーションに対しては、標準の CPython ランタイム" +"の代わりに JIT コンパイルされた `PyPy インタープリタ `__ を使うことが適切な代替策となるかもしれません。 PyPy を適用しようとする" +"時、典型的には他のバイナリ拡張モジュールへの依存が主たる障害になります - " +"PyPy が CPython の C 言語 API をエミュレートする一方で、その API に依存するモ" +"ジュールの側が PyPy の JIT に問題を引き起こし、また、エミュレーション層が " +"CPython では現在は許容されているような拡張モジュール側の潜在的な瑕疵 (参照カ" +"ウントに関係するエラーであることが多い - あるオブジェクトへの参照が２個あるは" +"ずのところが１個しかないという状態は何も悪さをしませんが、１個の参照のはずが" +"参照なしとなる場合が主な問題になります) をしばしば暴露してしまうのです。" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" +"`Cython `__ は、ほとんどの Python コードを C 言語の拡張" +"モジュールに変換できる成熟した静的コンパイラです。当初のコンパイルでは、" +"(CPython のインタプリタ層をバイパスすることによって) いくらかの速度向上が見込" +"めるとともに、 Cython のオプション扱いの静的型付け機能によってさらに速度向上" +"の機会があるかもしれません。Cython の使用には、バイナリ拡張の使用に関連した `" +"欠点`_ がまだ残っていますが、Python プログラマにとって (C 言語や C++ のような" +"他言語に比べると) 参入障壁が低いという利点があります。" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" +"`Numba `__ は新しめのツールで、LLVM を活用して " +"Python アプリケーションの一部分をランタイムに選択的にネイティブの機械コードに" +"コンパイルできるようにすることを目指している科学分野の Python コミュニティに" +"よって作成されました。この取り組みでは、コードが動作するシステムに LLVM が存" +"在していなければなりませんが、特にベクトル化が容易な操作について顕著な速度増" +"加を提供することができます。" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "ハードコードされたラッパモジュールに対する代替策" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" +"C 言語 ABI (アプリケーションバイナリインタフェイス )は、複数のアプリケーションの間で機能を共有する上での一般的な標準で" +"す。CPython の C 言語 API (アプリケーションプログラミングインタフェイス " +") を使えば Python のユーザがその機能に入り" +"込むことができます。しかしながら、手動でモジュールごとにラッピングしていくの" +"はうんざりするような作業なので、いくつもの代替アプローチが検討されるべきで" +"す。" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" +"以下に記述するアプローチは、単に配布物での事例ということは全くなく、むしろ" +"ラッパモジュールを最新に保つというメンテナンス上の重荷を大いに軽減することが " +"*できる* ものです。" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" +"アクセラレータモジュールの作成に役に立つことに加えて、 `Cython `__ は C 言語や C++ の API で書かれたものをラップするモジュールを" +"作成することにも役立ちます。インターフェイスを手動でラップする作業が必要であ" +"り、それはラッパーのソースコードを設計し最適化する上では大きな自由度を与えは" +"しますが、大規模な API を素早くラップするためにはあまり良い選択ではないかもし" +"れません。Cython を用いた自動ラッピングについては `サードパーティが提供する" +"ツールのリスト `_ を見てくださ" +"い。これらは、 PyPy や Pyston のような CPython に類似した C-API を提供する性" +"能重視の Python 実装をもサポートしています。" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" +":doc:`pybind11 ` は純粋な C++11 で書かれたライブラリで、綺麗" +"な C++ インタフェイスを CPython (および PyPy) の C 言語 API に提供します。事" +"前処理 (pre-processing) の段階が不要で、全体がテンプレート化された C++ で書か" +"れています。ヘルパーツールが Setuptools や CMake ビルドに含まれています。 " +"`Boost.Python `__ を基礎にしていますが、Boost ライブラリや BJam がなくてはダメと" +"いうことはありません。" + +#: ../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 "" +":doc:`cffi ` は、 Python と C 言語の両方を知っている開発者が C 言" +"語で書いたモジュールを Python アプリケーションから単刀直入に使えるようにと何" +"人かの PyPy 開発者たちが作成しました。たとえ C 言語を知らなくても、 C 言語の" +"モジュールをそのヘッダファイルに基づいてラップすることもいくらか簡単になりま" +"した。" + +#: ../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." +msgstr "" +"``cffi`` の最も重要な利点のひとつはPyPy JIT と一緒に使えることで、CFFI ラッパ" +"モジュールが PyPy の実行中の JIT 最適化に同居できるのです。" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" +"`SWIG `__ は、 Python を含むさまざまなプログラミング言" +"語から C 言語や C++ のコードへのインタフェースを生成できるラッパインタフェー" +"ス生成ツールです。" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" +"標準ライブラリの ``ctypes`` モジュールは、ヘッダの情報が得られない時でも C 言" +"語レベルのインタフェイスにアクセスできる点が役に立つ一方で、 C 言語の ABI の" +"レベルでのみ動作するため実際にエクスポートされているインタフェースと Python " +"コード側での宣言との間の一貫性を自動的に確認する仕組みがないという点が弊害を" +"引き起こすかもしれません。対照的に、上記の代替策はすべて C 言語の *API* のレ" +"ベルで動作するので、 C 言語のヘッダファイルを使ってライブラリからエクスポート" +"されラップされるインタフェイスと Python 側のラッパモジュールが期待しているイ" +"ンタフェースとの間の一貫性を保証することができます。 ``cffi`` は C 言語の " +"ABI のレベルで直接に動作する *ことができる* 一方で、そのように使った場合には " +"``ctypes`` と同じく一貫性を欠いたインタフェースの問題を孕みます。" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "低レベルのシステムアクセスを行う代替策" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" +"(理由を問わず) 低レベルのシステムにアクセスする必要のあるアプリケーションに" +"とって、バイナリ拡張モジュールはしばしば *進むべき最良の道* です。これは、 " +"``ctypes`` や ``cffi`` といったモジュールが適切な C 言語の API インタフェース" +"へのアクセスを取得するために使われている場合であってさえも、 (グローバルイン" +"タプリタロックの解除のような) いくつかの操作がインタプリタがコードを実行して" +"いる時には無効であるということだけを見ても、CPython ランタイム自身の低レベル" +"部分にアクセスする際によく当てはまると言えます。" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" +"拡張モジュールが (CPythonのランタイムではなく) 下層のオペレーティングシステム" +"やハードウェアを操作しようとする場合には、単純に通常の C 言語 (または C++ や " +"Rust のような別のシステム言語で C 言語と互換性のある ABI をエクスポートできる" +"もの) でライブラリを書いて、それを上述のようなインポート可能な Python のモ" +"ジュールとしてインタフェースを構築できるラッピングテクニックを使う方が良いと" +"いう場合もあるでしょう。" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "バイナリ拡張を実装する" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" +"CPython の :doc:`拡張と埋め込み ` のガイドに" +"は、 :doc:`C 言語による独自の拡張モジュール ` を" +"書くための導入的な説明があります。" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" +"FIXME: これが拡張モジュールを支援ツールなしで書きたいと *思わない* であろうと" +"いう理由のひとつであることを詳しく説明すること :)" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "拡張モジュールのライフサイクル" + +#: ../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/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "shared static state やサブインタプリタの影響" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "GIL の影響" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "メモリを割り当てる API 群" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "ABI の互換性" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" +"CPython の C 言語 API は、マイナーリリース (3.2, 3.3, 3.4 等) 間の ABI の互換" +"性を保証しません。これが意味するところは、典型的には、Python のあるバージョン" +"向けに拡張モジュールをビルドした時にマイナーバージョンまで同じ Python での動" +"作が保証されるだけであって、他のマイナーバージョンについては保証されないとい" +"うことです。" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" +"Python 3.2 では、Python の C 言語 API のよく定義されたサブセットとして " +"Limited API を導入しました。Limited API が必要とするシンボル群は、Python 3.x " +"のすべてのバージョンを通じて互換性を保つことが保証された \"Stable ABI\" を形" +"成しています。Stable ABI を使ってビルドされた拡張部分を含む Wheel は、Python " +"3.x のすべてのバージョンで互換性を保っていることを反映するために ``abi3`` と" +"いう ABI タグを使用します。" + +#: ../source/guides/packaging-binary-extensions.rst:277 +msgid "" +"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/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: 拡張をビルドする際に利用可能なビルドバックエンドをカバーせよ。" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "複数のプラットフォーム向けに拡張モジュールをビルドする" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" +"あなたが自分の書いた拡張モジュールを配布するつもりがあるなら、あたながサポー" +"トしようと思うすべてのプラットフォーム向けに :term:`wheels ` を準備す" +"るべきです。通常はこれらを継続的インテグレーション (CI) システム上でビルドし" +"ます。:ref:`cibuildwheel` や :ref:`multibuild` のような CI から再配布が非常に" +"やりやすいバイナリをビルドするのを補助するツールの存在が知られています。" + +#: ../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::" +msgstr "" +"ほとんどの拡張部分向けに、すべてのサポートするつもりのあるプラットフォーム用" +"の wheel をビルドする必要があるでしょう。これが意味するところは、ビルドする必" +"要のある wheel 群の数が次のような掛け算になるだろうということです::" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" +"CPython の :ref:`Stable ABI ` を使うことで、準備する必要" +"のある wheel の数を大いに減らすことに役立つでしょう、というのは、あるプラット" +"フォーム上の単一の wheel が Python のすべてのマイナーバージョンで使える; つま" +"り、マトリクスの次元をひとつ削除することになるからです。さらに、新しいマイ" +"ナーバージョンの Python が出現するたびに新たに wheel を生成する必要もなくなり" +"ます。" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "Windows 向けのバイナリ拡張" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" +"バイナリ拡張をビルドできるようになる前に、適切なコンパイラが利用できるように" +"なっていることを保証しなければなりません。Windows 上でCPython インタプリタを" +"ビルドするのに Visual C が使われていますが、互換性のあるバイナリ拡張をビルド" +"する時にも同じコンパイラを使うべきです。バイナリ拡張のためのビルド環境を構築" +"するためには、 `Visual Studio コミュニティエディション `__ をインストールしてください - 最近の" +"バージョンならどれでも構いません。" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" +"注意: Visual Studio 2019 またはこれ以降のバージョンを使う場合には、あなたの拡" +"張モジュールは、2015 までのそれ以前のバージョンで依存していた " +"``VCRUNTIME140.dll`` に加えて、\"追加的な\" ファイルである " +"``VCRUNTIME140_1.dll`` にも依存するでしょう。この追加のファイルを同梱していな" +"いバージョンの CPython 上であなたの拡張モジュールを使う場合には、要求事項が追" +"加されることになります。コンパイル時に引数 ``/d2FH4`` を追加しておくことで、" +"これを避けることができます。最近のバージョンの Python ならこのファイルを同梱" +"しているかもしれません。" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +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 向けのバイナリ拡張" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" +"Linux のバイナリは、古い配布物と互換性を保つために十分に古い glibc を使わなけ" +"ればなりません。 `manylinux `_ の Docker " +"イメージを使えば、よくあるアーキテクチャのほとんどの現行版 Linux 配布物をサ" +"ポートするのに十分なほど古い glibc を伴ったビルド環境を準備できるでしょう。" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "macOS 向けのバイナリ拡張" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +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 "バイナリ拡張を公開する" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" +"PyPI を通じてバイナリ拡張を公開する時にも、純 Python のパッケージを公開すると" +"きと同じアップロードのメカニズムを使います。その拡張の wheel をビルドバックエ" +"ンドを使ってビルドし、 :doc:`twine ` を使って PyPI にアップロー" +"ドするということです。" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "バイナリだけのリリースを避ける" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +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/packaging-binary-extensions.rst:381 +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." +msgstr "" +"拡張モジュールのプラットフォームを跨ぐ開発・配布は込み入った話題なので、この" +"ガイドでは主として背景にある技術的な課題の取り扱いを自動化するさまざまなツー" +"ルへのポインタを提供することに重点を置くことにします。代わりに、この節のその" +"他の部分では、そのようなシステムが実行時に依存するような下層のバイナリインタ" +"フェースについて開発者が理解を深めるために見ることを意図しています。" + +#: ../source/guides/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "sckit-build を用いたクロスプラットフォームな wheel の生成" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" +"`scikit-build `_ は、抽象的な" +"ビルド作業を補助し、バイナリ拡張のパッケージを作成する時に必要な追加的な能力" +"を提供します。 Python のバイナリ拡張モジュールに関するさらなる説明文書は、 " +"`C 言語におけるランタイム・コンパイラ・ビルドシステム生成器 `_ にあります。" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "C/C++ による拡張モジュールの紹介" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" +"Debian システム上で CPython がどのようにして拡張モジュールを使うのかについ" +"て、もっと深掘りした説明が次の記事に出ています:" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" +"`(c)python の拡張モジュールとはどんなものか？ `_" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" +"`gil をリリースする `_" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" +"`C++ で cpython の拡張モジュールを書く `_" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "バイナリの wheel に関する追加的な考慮" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" +"`pypackaging-native `_ ウェブサイトに" +"は、ネイティブのソースコード付きで Python パッケージをパッケージングすること" +"の追加のカバレッジがあります。最重要のパッケージング上の課題について、そのよ" +"うな (課題に直面した) プロジェクト向けに詳細な説明とリファレンスを提供するこ" +"とを目的としています。" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" +"話題の例としては、非 Python の要コンパイルな依存関係 (\"ネイティブ依存関係" +"\") や、ネイティブソースコードの ABI (Application Binary Interface) の重要性" +"や、 SIMD ソースコードへの依存とクロスコンパイルなどをカバーしています。" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "名前空間パッケージをパッケージする" + +#: ../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/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" +"そして、このパッケージを自分のソースコード中で使うにはこのようにします::" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" +"そうすることで、これらのサブパッケージ群を別々のふたつの配布物に分割すること" +"ができます:" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" +"それぞれのサブパッケージは、今や、個別にインストール・使用・バージョン管理す" +"ることができます。" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" +"名前空間パッケージは、 (単独の会社から出ている複数の製品向けのクライアントラ" +"イブラリの巨大な集積のような) 緩やかに関連したパッケージが多数含まれるコレク" +"ションに役立つでしょう。しかしながら、名前空間パッケージにはいくつかの注意書" +"きがあって、全ての場合に適切と言うわけではありません。単純明快な代替策は、あ" +"なたの配布物のすべてについて ``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/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" +"現在、名前空間パッケージを作るには２個の異なる手法がありますが、後者は使わな" +"い方が良いとされています:" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" +"`組み込みの名前空間パッケージ`_ を用いる方法。この種の名前空間パッケージ" +"は :pep:`420` で定義されていて、 Python 3.3 およびそれ以降で利用することがで" +"きます。パッケージ中の名前空間が Python 3 だけをサポートすればよくて ``pip`` " +"でインストールするのであれば、これが推奨される方法です。" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" +"`legacy namespace packages`_ を使ってください。これは `pkgutil 型の名前空間" +"パッケージ`_ および `pkg_resources 型の名前空間パッケージ`_ から構成されてい" +"ます。" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "組み込みの名前空間パッケージ" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" +"Python 3.3 では :pep:`420` から **暗黙の** 名前空間パッケージを追加しました。" +"ネイティブな名前空間パッケージを作成するのに必要なことは、名前空間パッケージ" +"のディレクトリから :file:`__init__.py` を取り除くことだけです。ファイル構造の" +"例はこちら (:ref:`src-layout ` に従います):" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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/packaging-namespace-packages.rst:99 +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`:" +msgstr "" +"``src-layout`` ディレクトリ構造によって、ほとんどの :term:`ビルドバックエン" +"ド ` が自動的にパッケージ群を発見できるようになります。もっと" +"情報が欲しい場合は :ref:`src-layout-vs-flat-layout` を見てください。しかしな" +"がら、パッケージの包含・除外を自分自身で管理したいのであれば、トップレベル" +"の :file:`pyproject.toml` を設定することで可能です:" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "同じことが :file:`setup.cfg` で達成できます:" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "または :file:`setup.py` ファイル:" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" +":ref:`setuptools` は、デフォルトでは暗黙の名前空間パッケージを探してディレク" +"トリ構造を探索します。" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" +"ふたつの名前空間パッケージの完全な動作例は、 `組み込みの名前空間パッケージの" +"使用例プロジェクト`_ にあります。" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" +"組み込み名前空間パッケージと pkgutil 型の名前空間パッケージは、多くの部分で互" +"換性があるので、 Python 3 しかサポートしない配布物では組み込み名前空間パッ" +"ケージを使用し、 Python 2 と Python 3 の両方をサポートしなければならない配布" +"物では pkgutil型名前空間パッケージを使うことが可能です。" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" +"これらのふたつの方法は、 :pep:`420` 以前に名前空間を作成するのに使われました" +"が、今では過去のやり方であると考えられていて、すでにこれらの方法のいずれかを" +"使っているパッケージとの互換性を必要とする場合を除いては使われるべきではない" +"と考えられています。" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" +"既存のパッケージを移植するためには、名前空間を共有するすべてのパッケージが同" +"時に移植されなければなりません。" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" +"組み込みの名前空間パッケージや pkgutil 型の名前空間パッケージは多くの点で互換" +"性がありますが、 pkg_resources 型の名前空間パッケージは他の手法とは互換性があ" +"りません。同じ名前空間向けにパッケージを提供するような複数の配布物で、異なる" +"手法を用いることは推奨されません。" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "pkgutil 型名前空間パッケージ" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was 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/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" +"pkgutil 型の名前空間パッケージを作成するには、その名前空間パッケージ用" +"に :file:`__init__.py` ファイルを準備する必要があります:" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" +"名前空間パッケージ用の :file:`__init__.py` ファイルは、次に示すものを含んでい" +"る必要があります:" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" +"pkgutil 型の名前空間パッケージのふたつの動作例が `pkgutil 型名前空間を例示す" +"るプロジェクト`_ にあります。" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "pkg_resources 型名前空間パッケージ" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" +"この節の情報は既に古くなっていて、 (Setuptools 82.0.0 の時点では) もはや機能" +"しません。歴史上の参考のために保持されているだけです。" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" +"``pkg_resources`` は既に非推奨になっており、 Setuptools 82.0.0 で完全に取り除" +"かれました。" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" +"pkg_resources 型名前空間パッケージを作成するには、名前空間パッケージ用" +"の :file:`__init__.py` を準備する必要があります:" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" +"いくつかの古めの推奨では、次のような名前空間パッケージ用 :file:`__init__.py` " +"を使うように言っています:" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" +"背景にあるアイデアとしては、 setuptools を使えないような稀な場合には、パッ" +"ケージを pkgutil 型パッケージに切り戻したいと言うことがあるかもしれません。 " +"pkgutil 型と pkg_resources 型の名前空間パッケージは互いに非互換なので、これは" +"推奨できるものではありません。 setuptool が存在するか否かが問題なのであれば、" +"パッケージとしては ``install_requires`` を通じて setuptools に明示的に依存す" +"ると示しておくべきです。" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" +"最後に、それぞれの配布物は :file:`setup.py` の :func:`~setuptools.setup` 向け" +"に ``namespace_packages`` 引数を準備しておく必要があります。例えば:" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" +"GitHub Actions CI/CD ワークフローを用いてパッケージ配布物のリリースを公開する" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" +"`GitHub Actions CI/CD`_ を使うと、 GitHub プラットフォームで何かイベントが発" +"生するたびに一連のコマンドを実行することができます。よくある選択のひとつは、 " +"``push`` イベントを引き金にしてあるワークフローを行うというものです。このガイ" +"ドでは、タグ付きのコミットが push されるたびに Python 配布物を公開するやり方" +"をお見せします。それには `pypa/gh-action-pypi-publish GitHub Action`_ を使っ" +"て出版 します。また、一時的な格納やソースコード配布物のダウンロード" +"のためにGitHubの `upload-artifact`_ と `download-artifact`_ を使います。" + +#: ../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." +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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:27 +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." +msgstr "" +"このガイド文書は、`GitHub Actions CI/CD`_ に接続するために PyPI の `Trusted " +"Publishing`_ の実装に依存しています。これは、生成されるトークンが各プロジェク" +"トでそれぞれ独立に作成されて自動的に期限切れになるというセキュリティ上の理由" +"から推奨されています。さもなければ、 PyPI と TestPyPI の両方について `API " +"トークン`_ を生成する必要があるでしょう。:doc:`devpi ` のような" +"第三者パーティのインデックス向けに出版 する場合には、ユーザ名とパス" +"ワードの組み合わせを提供する必要があるかもしれません。" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" +"このガイドではPyPIとTestPyPIの両方へのアップロードを実証しますので、ふたつの" +"信頼あるパブリッシャが設定されていることが必要になるでしょう。以下に示すス" +"テップによって、新しい :term:`PyPI project ` 用の \" ペンディングさ" +"れた\" パブリッシャ群を作成する手順を一通りお見せします。しかしながら、あなた" +"が所有者であるならば、任意の既存プロジェクトに `Trusted Publishing`_ を追加す" +"ることが可能でもあります。" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" +"このガイドの以前のバージョンを読み通したことがあるのであれば、PyPI や " +"TestPyPI への直接のアクセスをするために ``PYPI_API_TOKEN`` と " +"``TEST_PYPOI_API_TOKEN`` という秘密のトークンを作成したことでしょう。今ではこ" +"れらは過去のものとなっていて、旧来の設定を新しいものに置き換える際に GitHub " +"リポジトリから削除し、 PyPI や TestPyPI のアカウント設定から取り除くべきで" +"す。" + +#: ../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 "" +"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:`PyPI プロジェクト ` 向けに発行したいと思う名前を " +"(``setup.cfg`` か ``pyproject.toml`` の中の ``名称 `` の値として)、" +"GitHub のリポジトリ所有者の名称 (org または user) と、リポジトリの名称と、 " +"``.github/`` フォルダの下のリリースワークフローの名称を記入するには、 :ref:`" +"ワークフロー定義 ` をみてください。最後に、これからリポ" +"ジトリ内に設定しようとするGutHub 環境 (``pypi``) の名称を追加してください。ト" +"ラステッドパブリッシャを登録してください。" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" +"ここで https://test.pypi.org/manage/account/publishing/ へ行って第２のステッ" +"プを繰り返してください、ただし、今回は GitHub 環境の名称として ``testpypi`` " +"を入力します。" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" +"ペンディングされたパブリッシャは今やその初回使用の準備ができており、初回使用" +"を行えば自動的にあなたのプロジェクトを生成します。" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" +"TestPyPI のアカウントを持っていなければ、新たに作成する必要があります。これは" +"通常の PyPI のアカウントとは別のものです。" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "ワークフロー定義を作成する" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" +"GitHub CI/CD ワークフローは、リポジトリの ``.github/workflows/`` ディレクトリ" +"に置かれた YAML ファイルで宣言されます。" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "``.github/workflows/publish-to-pypi.yml`` ファイルを作成しましょう。" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" +"意味のある名前で始めて、 GitHub がこのワークフローを走らせるべきイベントを定" +"義しましょう:" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" +"PyPI と TestPyPI に向けて出版 するためには、二つのジョブを定義しな" +"ければならず、また、配布物のパッケージ群をビルドするための追加のジョブも定義" +"しなければなりません。" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" +"最初に、あなたのプロジェクトの dist パッケージをビルドして、その後の使用のた" +"めに保存するジョブを定義しましょう:" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" +"これによって、あなたのリポジトリを CI ランナーにダウンロードして、利用可能な" +"最新の Python 3 リリースをインストールしアクティベートすることになります。" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" +"そして、今や我々はソースコードから dist 配布物をビルドして保存しておくことが" +"できます。この例では、パッケージを ``build`` することになります。ですから、こ" +"れをステップリストに加えましょう:" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "ワークフローのジョブ環境を定義する" + +#: ../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 へ公開 する予定のジョブに初期設定を追加しましょう。それ" +"は、後ほど定義するであろうコマンドを実行するプロセスです。このガイド文書で" +"は、GitHub Actions が提供している最新版の Ubuntu LTS 安定版バージョンです。こ" +"れは、また、そのコンテキスト内でジョブが走る GitHub 環境 を定義するものでもあり、 GitHub の UI の中に申し分なく表示され" +"る URL でもあります。さらに、それは、 ``pypi-publish`` アクションがシークレッ" +"トなしの PyPI への信頼ある公開を実装するために必要となる OpenID Connect の" +"トークンを取得することを可能にするものでもあります。" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "PyPI へ配布物を公開する " + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" +"この手順では、保存されている配布パッケージが `download-artifact`_ アクション" +"によってダウンロードされた後に `pypa/gh-action-pypi-publish`_ という GitHub " +"Action: を使って、 ``dist/`` フォルダの内容物を無条件に PyPI へアップロードし" +"ます。" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" +"バージョン `v1.11.0 `_ 以降、 `pypa/gh-action-pypi-publish`_ は、デフォルトで各配布物" +"に対する :pep:`740` 互換の証明書を生成しアップロードするようになりました。手" +"動の署名手順はもはや必要ありません。" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "TestPyPI へ公開 するもうひとつのワークフロー" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" +"さて、これらのステップを繰り返して、 ``jobs`` セクションに TestPyPI パッケー" +"ジインデックスに公開 するようなもうひとつのジョブを作成しましょう:" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" +"``testpypi`` Github 環境において手動の承認を要求することは、main ブランチへの" +"コミット毎に走るように設計されていることから、典型的な場合には不必要とされて" +"いて、使われるとすればリリースの公開 パイプラインが健全であることを" +"示すためであることが多いのです。" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "CI/CD ワークフローの全体像" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" +"この段落には、上述のガイド文書に従った場合のワークフローの全体像を披露しま" +"す。" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "これでできましたよ、皆さん!" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" +"これで、手元の Git リポジトリをリモートの GitHub にタグ付きのコミットをプッ" +"シュする時はいつでも、このワークフローがそれを PyPI へ公開します。そして、" +"プッシュしさえすればいつでも TestPyPI で公開されますので、アルファ版のユーザ" +"にテストビルドを提供するためにも、あなたのリリースパイプラインが健全な状態に" +"保たれていることを確認するためにも役に立ちます!" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +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 "ホスティング" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +msgid "Installation" +msgstr "インストール" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "0; url=../../discussions/single-source-version/" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" +"古くなったシングルソースのパッケージバージョンリンクをリダイレクトする..." + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" +"もし、ページが自動的にリフレッシュされないなら、 :ref:`single-source-" +"version` をみて下さい。" + +#: ../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 "" +"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 "" +"Python パッケージを作成するのに必要とされる仕事に加えて、しばしばそのパッケー" +"ジが異なるバージョンの Python に対応することが求められます。 Python のバー" +"ジョンが異なると、異なる (または名称を変更した) 標準ライブラリパッケージを含" +"むことがあり、 Python 2.x と 3.x の間には言語の文法に違いがあります。" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" +"パッケージが対象となる Python バージョン (および OS 群！) で正しく動作するこ" +"とを確認するために要求されるテストを全て手動でやるとなると、大変に時間がかか" +"るでしょう。幸いなことに、このようなテストを扱ういくつかのツールを利用するこ" +"とができますので、ここで簡単に議論しておきましょう。" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "自動化されたテストと継続的インテグレーション" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" +"自動化されたテスト用のオンラインサービスがいくつか利用可能です。典型的には、" +"これらのサービスがあなたのソースコードリポジトリ (例えば `GitHub `_ や `Bitbucket `_) を監視していて、新しい" +"コミットが為されるたびにテストスイートを実行します。" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" +"これらのサービスは、また、あなたのプロジェクトのテストスイートを *複数のバー" +"ジョンの Python* で走らせる機能を提供しているので、開発者がそのようなテストを" +"自分でやらなくてもソースコードが動作するか否かについて素早くフィードバックを" +"返してくれます。" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" +"Wikipedia には、数多くの継続的インテグレーションシステムを多方面から比較した " +"`比較ページ `_ があります。その中には、両方" +"を一緒に使うことで Linux ・ Mac ・ Windows を跨いだ自動化されたテストを実行で" +"きるようなふたつのオンラインサービスもあります。" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" +"`Travis CI `_ は Linux と macOS の両方の環境を提供しま" +"す。本稿執筆時点で、 Linux 環境は Ubuntu 12.04 LTS Server Edition 64 bit " +"で、 macOS 環境は 10.9.2 です。" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" +"`Appveyor `_ は、Windows 環境 (Windows Server " +"2012) を提供します。" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" +"`Travis CI`_ も Appveyor_ も、 `YAML `_ 形式のテスト仕様書" +"を必要とします。いずれかのテストが失敗したら、そのテスト指示設定に関するログ" +"出力を調査することができます。" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +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 +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_." +msgstr "" +"`six `_ は、ベンジャミン・ピーターソン " +"(Benjamin Peterson) が開発した Python 2 と Python 3 の間の差異を吸収するため" +"のツールです。 six_ パッケージは広範囲に受け入れられていて、単一ソースコード" +"の Python パッケージが Python 2 と Python 3 の両方で使えるようにするための信" +"頼できる方法であるとみなされています。 six_ モジュールは早くも Python 2.5 か" +"ら使えます。アーミン・ロンチャー (Armin Ronacher) が開発した `modernize " +"`_ という名前のツールは、 six_ が提供する" +"修正を自動的にソースコードに適用するために使うことができます。" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +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 (文法による) モジュール。" + +#: ../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/supporting-multiple-python-versions.rst:109 +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." +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/supporting-multiple-python-versions.rst:116 +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." +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 に何がある？" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +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 をサポートする" + +#: ../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 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 "" +"この節では、無料の `Appveyor`_ 継続的インテグレーションサービスを使ってあなた" +"のプロジェクトで Windows をサポートする方法について議論します。これには、 " +"Windows におけるソースコードのテストや、 C 言語拡張を含むプロジェクトの " +"Windows 向けのバイナリへのビルドを含みます。" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" +"多くのプロジェクトが当然のように Unix 上で開発されており、適切なWindows のテ" +"スト環境を準備することが簡単ではないこととソフトウェアライセンスを購入しなけ" +"ればならないであろうことから Windows へのサポートを提供することはある種のチャ" +"レンジになっています。" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" +"Appveyor サービスは継続的インテグレーションのサービスであり、 `GitHub`_ にホ" +"ストされたプロジェクトをテストするのによく使われよりよく知られている " +"`Travis`_ サービスによく似ています。しかし、 Travis とは異なり、 Appveyor の" +"ビルドワーカーは Windows であり、 Python の拡張モジュールをビルドするために必" +"要なコンパイラもインストール済みです。" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" +"Windows のユーザは C 言語のコンパイラを持っていないのが普通で、従って、C 言語" +"拡張を使うプロジェクトについては PyPI でバイナリ wheel を配布していなければ " +"``python -m pip install `` 経由で配布物をインスールすることができませ" +"ん。 (たとえテスト目的では利用しなかったとしても) Appveyor をビルドサービスと" +"して利用することで、専用の Windows 環境がなくても Windows 上で動作するバイナ" +"リを準備することができます。" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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/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/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/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "プロジェクトに Appveyor サポートを追加する" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" +"Appveyor がプロジェクトをビルドする方法を定義するために" +"は、 :file:`appveyor.yml` ファイルをプロジェクトに追加する必要があります。こ" +"のファイルに書くことができる項目の完全な細部は、 Appveyor の説明文書で説明さ" +"れています。このガイドでは、wheel のビルドに必要な部分に限って細部を説明しま" +"す。" + +#: ../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 "" +"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" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" +"このファイルは `ここ `__ か" +"らダウンロードすることができます。" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" +":file:`appveyor.yml` ファイルは、プロジェクトのルートディレクトリに置かなけれ" +"ばなりません。このファイルは ``YAML`` フォーマットで書かれていて、数多くのセ" +"クションから構成されています。" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +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 へ移行できるからです) 。" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" +"``install`` セクションは、プロジェクトが必要とする追加的なソフトウェアを pip " +"を使ってインストールするのに使われます。 wheel をビルドするために必要なもの" +"は ``wheel`` プロジェクトだけですが、プロジェクトによっては特定の環境下ではこ" +"の項をカスタマイズしたいと思うかもしれません (例えば、 ``Cython`` のような追" +"加的なビルド用パッケージないし ``tox`` のようなテストツールをインストールする" +"ために)。" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" +"``build`` セクションでは単純にビルドのスイッチを切りましょう - ``C#`` のよう" +"な言語とは異なり、Python にはビルドする段階は不要なのです。" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" +"個々のプロジェクト向けに整える必要のある主なセクションは、 ``test_script`` " +"と ``after_test`` です。" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" +"``test_script`` セクションは、プロジェクトのテストを走らせる場所です。与えら" +"れたファイルを使って ``setup.py test`` を走らせることで一連のテストを行いま" +"す。wheel ファイルをビルドすることだけに興味があるのであれば、そして、 " +"Windows でテストをしないのであれば、このセクションに ``echo Skipped Tests`` " +"のようなダミーコマンドを書いておけば良いでしょう。 ``nose`` " +"や :file:`py.test` のような他のテストツールを使いたい場合があるかもしれませ" +"ん。あるいは、 ``tox`` のようなテストドライバを使いたいと思うかもしれません " +"- しかしながら、 ``tox`` を使う場合には、後述の通り、もう少し追加の設定変更を" +"検討する必要があることでしょう。" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" +"``after_test`` は、テストが完了したあとに一度だけ走り、したがって、ここで " +"wheel ファイルを生成するべきです。あなたのプロジェクトで推奨ツール (とりわけ " +"``setuptools``) を使っているなら、 ``setup.py bdist_wheel`` コマンドで wheel " +"ファイルを生成できます。" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" +"テストが成功した場合にだけ wheel ファイルが生成されるという点に留意してくださ" +"い。 Windows ではテストが失敗するとわかっているなら、前述の通り、それを省略す" +"ることができます。" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "サポートスクリプト" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" +":file:`appveyor.yml` ファイルは、Python 3.3 と 3.4 上で 64 ビットでのビルドを" +"行うために SDK のコンパイラを使う環境を構築するためのひとつのサポートスクリプ" +"トに依存しています。コンパイラを必要としないプロジェクトや64 ビット版の " +"Windows 上の 3.3 や 3.4 をサポートしないプロジェクトで" +"は、 :file:`appveyor.yml` ファイルさえあれば良いことになります。" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" +"`build.cmd `__ は、選択されたバー" +"ジョンの Python 用の適切なコンパイラが存在する環境内で単一のコマンドを実行す" +"るような Windows のバッチスクリプトです。やらなければならないことはたった一個" +"の環境変数 ``DISTUTILS_USE_SDK`` の値を ``1`` に設定することだけで、残りはす" +"べてこのスクリプトがやってくれます。スクリプトが Python 3.3 ないし 3.4 を 64 " +"ビットでビルドするのに必要な SDK 環境を構築するので、他のビルドに使う環境変数" +"を設定してはいけません。" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" +"このバッチファイルは単純にダウンロードして修正なしにプロジェクト内に置くこと" +"ができます。" + +#: ../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 "" +"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 "" +"ビルドが終わると、出来上がった wheel ファイルは Appveyor のコントロールパネル" +"の当該プロジェクトのページから取り出せるでしょう。ビルドのたびに生成されるビ" +"ルド状況のページからも取り出せます。ビルド結果の出力ページの先頭には一連のリ" +"ンクがあって、そのうちの \"Artifacts\" がそれです。そのページに行くと該当する" +"バージョンの Python / アーキテクチャに応じた wheel ファイルへのリンクがあるは" +"ずです。ここから wheel ファイルをダウンロードして、あなたのリリース作業の一環" +"として PyPI へアップロードすることができるでしょう。" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "tox を用いてテストする" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" +"多くのプロジェクトで :doc:`Tox ` ツールを用いてテストを行っていま" +"す。これを使えば、プロジェクトで配布するであろうファイル群そのものを使った独" +"立した環境下でテストを実行することができます。" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" +"Appveyor 上で ``tox`` を使うためには、(実際のところは、Appveyor に限ったこと" +"ではなく、他の CI システムにも影響します) いくつかの追加的な事項を検討しなけ" +"ればなりません。" + +#: ../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." +msgstr "" +"デフォルトでは ``tox`` は、環境変数のうちのいくつかの選択されたサブセットだけ" +"をテストプロセスに渡します。 ``distutils`` がコンパイラを制御するのに環境変数" +"を用いるので、この \"テスト環境分離\" の機能がデフォルトではテストに誤ったコ" +"ンパイラを使ってしまう問題を引き起こすでしょう。" + +#: ../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 "" +"``tox`` がサブプロセスに必要な環境変数を渡すように強制するためには、 ``tox`` " +"の設定オプションである ``passenv`` に追加的にサブプロセスに渡すべき環境変数の" +"リストを設定する必要があります。SDK コンパイラを使うのであれば、このような設" +"定が必要です" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "``DISTUTILS_USE_SDK``" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "``MSSdk``" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "``INCLUDE``" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +msgstr "``LIB``" + +#: ../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." +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)." +msgstr "" +"``tox`` を対話的に使うと、複数の環境 (これはしばしば複数のバージョンの " +"Python を意味します) でテストを実行することができます。設定ごとに独立した環境" +"ですべてのテストを実行する Travis や Appveyor のような CI 環境で見られるほど" +"には、この機能は有用ではありません。結果として、しばしばプロジェクト側から " +"``-e ENVNAME`` 引数を ``tox`` に与えてどの環境を使うべきか (ほとんどのバー" +"ジョンの Python に対応したデフォルトの環境群があります) を指定します。" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" +"しかしながら、このやり方は、 Appveyor のような Windows 上の CI システムでは " +"(例えば) Python 3.4 の (32 版ビットと64ビット版の) ふたつの実装が利用できるの" +"に、 ``tox`` では ``py34`` 環境がひとつしかないので、うまく *動きません* 。" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" +"``tox`` を使ってテストを実行するためには、したがって、プロジェクトがおそらく" +"は ``tox`` のデフォルトの ``py`` 環境、ここでは ``tox`` を実行するために使わ" +"れた Python インタープリタを使うことになりますが、その環境を使うべきでしょ" +"う。" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" +"``py`` 環境下での動作をサポートするためには、複雑な ``tox`` 設定を持つプロ" +"ジェクトでは :file:`tox.ini` を修正する必要があるかもしれません。そのようにす" +"ることは、しかしながら、この文書の範囲を越えます。" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "自動的に wheel ファイルをアップロードする" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" +"Appveyor に自動的に wheel ファイルをアップロードさせることができま" +"す。 :file:`appveyor.yml` ファイルの中に ``deployment`` 段階があって、(例え" +"ば) ビルドした生成物を FTP サイトや Amazon S3 インスタンスへコピーするために" +"使うことができます。これをやるにはどうすれば良いかについては、 Appveyor ガイ" +"ドに説明があります。" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" +"別のやり方としては、ビルドの際に ``twine upload`` 段階を追加することができる" +"でしょう。 (プロジェクトによってはそうしたいかもしれませんが) コミットのたび" +"に新しい wheel ファイルをアップロードすることが望ましいかどうかがはっきりしな" +"いので、先ほどの :file:`appveyor.yml` ファイルはこれをやりません。" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "外部への依存関係" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" +"提供されたスクリプトを使えば、ビルド時にサードパーティの外部ライブラリに依存" +"しない配布物ならどれでもビルドに成功するでしょう。" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" +":file:`appveyor.yml` ファイルでの設定 (典型的には \"install\" 段階) を加え" +"て、配布物に必要な外部ライブラリをダウンロードないしビルドすることは可能で" +"す。そして、もし必要なら、このようなライブラリの位置ををコンパイラに伝えるた" +"めの余分の設定を追加することもできます。しかしながら、このレベルの設定はこの" +"文書の範囲を超えます。" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "サポートスクリプト" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "参照用に SDK を構築するサポートスクリプトをここに挙げておきます:" + +#: ../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 "" +"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 "" +"Python パッケージングのランドスケープは、多くの異なったツール群からできていま" +"す。多くのタスクについて、 :term:`Python パッケージングオーソリティ ` (PyPA とは多数のパッケージングツール群を包含す" +"るとともにこのガイド文書を維持管理しているワーキンググループ) は、一律に適用" +"するような推奨ををしません; 例えば、数多くのビルドバックエンドが存在する理由" +"は、既存のユニークなバックエンドである setuptools よりもうまく特定のユーザの" +"ニーズに応える新しいバックエンドの開発を可能とするためにランドスケープを開放" +"しているということなのです。このガイド文書では、広く認知されている幾つかの" +"ツールを指し示していますが、また、非推奨であったり安全でなかったりするために " +"*使うべきでない* ものについても非推奨事項を記しています。" + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "仮想環境" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" +"仮想環境を手動で作成して使用するための標準的なツールは、 :ref:`virtualenv` " +"(PyPA project) と :doc:`venv ` (virtualenv には備わって" +"いる幾つかの機能が欠けてはいるものの、Pythonの標準ライブラリの一部) です。" + +#: ../source/guides/tool-recommendations.rst:28 +msgid "Installing packages" +msgstr "パッケージをインストールする" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" +":ref:`Pip` は :term:`PyPI ` からパッケージをイン" +"ストールするための標準的なツールです。 pip の推奨事項については、 :doc:`セ" +"キュアなインストール ` を読むと良いでしょう。 " +"pip は、標準ライブラリのパッケージ :doc:`ensurepip ` を通じて、ほとんどの Python 環境でデフォルトで利用可能です。" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" +"別のやり方としては、 PyPI を通じて配布されてコマンドラインから実行される " +"Python アプリケーションをインストールする特定のユースケースにおいて" +"は :ref:`pipx` を検討してください。 pipx は pip と、専用の仮想環境の中にそれ" +"ぞれのアプリケーションをインストールする venv のラッパーとして動作します。こ" +"れによって、異なるアプリケーションの間の依存関係上の衝突を避け、システムワイ" +"ドのアプリケーションとの間で同じ Python インタープリタを使う際の衝突を避ける" +"ことができます (特に Linux 環境で)。" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +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\" の比較を書くべし。" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +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 近代化プロジェクト ` を見" +"てください)。" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "ロックファイル" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" +":ref:`pip-tools` と :ref:`Pipenv` は、再現性を高める目的でロックファイル、そ" +"こにはその環境にインストールされたパッケージの正確なバージョンを含みますが、" +"そのようなロックファイルを作成するためのツールとしてよく知られています。" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "ビルドバックエンド" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" +"どうか覚えておいてください: このドキュメントは、読者に特定のツールへ向かって" +"舵を切らせることを追求しているわけではなく、一般的なツール群を列挙しているだ" +"けです。異なるユースケースでは、しばしば、そのケースに特化したワークフローが" +"必要になります。" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" +"純 Python のパッケージを取り扱う :term:`ビルドバックエンド ` " +"で人気のあるものは、アルファベット順に:" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" +":doc:`Flit-core ` -- :ref:`Flit` とともに開発されたが別" +"のもの。最小限で自己主張の強いビルドバックエンド。プラグインをサポートしな" +"い。" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" +"Hatchling_ -- :ref:`Hatch` とともに開発されたが別のもの。プラグインをサポート" +"する。" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" +"PDM-backend_ -- :ref:`PDM` とともに開発されたが別のもの。プラグインをサポー" +"ト。" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" +"Poetry-core_ -- :ref:`Poetry` とともに開発されたが別のもの。プラグインをサ" +"ポート。" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" +"このリストの他のバックエンドとは異なって、 Poetry-core は標準的" +"な :ref:`[project] table ` をサポートしていません " +"(``[tool.poetry]`` テーブル内に別のフォーマットで書くことはできます)。" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" +":ref:`setuptools` は、以前は唯一のビルドバックエンドでした。プラグインをサ" +"ポート。" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" +"setuptools を使うのであれば、標準化の努力が為される前の幾つかの機能が今では非" +"推奨になっていて互換性を保つために *一時的に継続使用* しているだけであること" +"を忘れないでください。" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" +"とりわけ、 ``python setup.py`` のように直接に起動しては *いけません* 。他方" +"で、可能であればいつでも近代的な :ref:`[project] table in pyproject.toml " +"` (または :file:`setup.cfg`) を使うことや、プログラム" +"的な設定が必要とされる場合にのみ :file:`setup.py` を使い続けることが推奨され" +"てはいますが、 :file:`setup.py` を使って setuptools に設定を渡すことは今も完" +"全にサポートされています。 :ref:`setup-py-deprecated` を見てください。" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" +"非推奨となった機能の他の例としては、 ``setup()`` の ``setup_requires`` 引数を" +"使うべきではなく (代わりに :file:`pyproject.toml` 内の :ref:`[build-system] " +"テーブル ` を使ってください) 、また、 " +"``easy_install`` コマンドを使うことも非推奨になっています (cf. :ref:`pip vs " +"easy_install`) 。" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" +":ref:`distutils` を *使わないで* ください、というのも、これは非推奨になってい" +"ますし、まだ setuptools から利用可能ではありますが Python 3.12 で標準ライブラ" +"リから取り除かれたものです。" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "拡張モジュール用のビルドバックエンド" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" +":term:`拡張モジュール ` を伴うパッケージについては、その拡" +"張が書かれた言語用の専用サポートのあるビルドシステムを使うのが最善です、例え" +"ば:" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" +":ref:`setuptools` -- C 言語および C++ 言語をネイティブにサポート (サードパー" +"ティのプラグインで Go 言語と Rust 言語も)、" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" +":ref:`meson-python` -- C 言語・ C++ 言語・ Fortran ・ Rust およびその他の言語" +"が Meson によってサポートされています、" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" +":ref:`scikit-build-core` -- C 言語・ C++ 言語・ Fortran やその他の言語が " +"CMake によってサポートされています、" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr ":ref:`maturin` -- Rust 、 Cargo を経由して。" + +#: ../source/guides/tool-recommendations.rst:128 +msgid "Building distributions" +msgstr "配布物をビルドする" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" +"PyPI へアップロードするために :term:`ソースコード配布物 ` や :term:`wheels ` をビルドするための標準ツール" +"は、 :ref:`build` です。:file:`pyproject.toml` 内で `宣言された ` ビルドバックエンドが何であれ、それを起動することに" +"なります。" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" +"この作業のために ``python setup.py sdist`` や ``python setup.py " +"bdist_wheel`` を *使わないで* ください。:file:`setup.py` を直接に起動すること" +"は :ref:`非推奨 ` になっています。" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" +"もし、 :term:`拡張モジュール ` を使っていて複数のプラット" +"フォーム向けに wheel ファイルを配布したいと考えているなら、配布可能な wheel " +"ファイルをビルドする CI 環境の一部として :ref:`cibuildwheel` を使いましょう。" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "PyPIにアップロードする" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" +"サポート対象の CI/CD プラットフォームにホストされている、もしくは、そこから公" +"開されているプロジェクトに関しては、手動で設定された API トークンなしで CI/" +"CD ワークフローから PyPI へとパッケージを安全にアップロードすることができ" +"る :ref:`Trusted Publishing ` を使うことが推奨されていま" +"す。" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" +"2024 年 11 月の時点では、 PyPI は以下のプラットフォームを 信頼ある公開 " +" プロバイダとしてサポートしています:" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "(``https://github.com`` における) GitHub Actions" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "(``https://gitlab.com`` における) GitLab CI/CD" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "ActiveState" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "Google Cloud" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" +"利用可能なもうひとつの方法は、 :ref:`twine` を用いて手動でパッケージをアップ" +"ロードすることです。" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" +"このタスクを行うために ``python setup.py upload`` を使うことは *絶対にやめて" +"* ください。 :ref:`非推奨 ` であることに加えて、危険 " +" です。" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "ワークフローツール" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" +"これらのツール群は、プロジェクトの仮想環境を自動的に管理する環境マネージャで" +"す。これらは、テストを走らせたり、説明文書をコンパイルしたり、何らかのファイ" +"ルを再生成したり、その他のタスクを定義して起動するための \"タスク実行係\" と" +"しても動作します。これらのうちのいくつかは配布物をビルドしたり PyPI にアップ" +"ロードするためのショートカットを提供しますし、あるいは、アプリケーション向け" +"のロックファイルをサポートしています。これらは、往々にして、先述のツール群を" +"内部的に呼び出しています。アルファベット順に:" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr ":ref:`Flit`," + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr ":ref:`Hatch`," + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr ":doc:`nox `," + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr ":ref:`PDM`," + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr ":ref:`Pipenv`," + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr ":ref:`Poetry`," + +#: ../source/guides/tool-recommendations.rst:185 +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 "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" +"このページの情報は、setuptools 説明文書の中の :doc:`setuptools:userguide/" +"miscellaneous` に移されました。" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" +"``TestPyPI`` は :term:`Python パッケージインデックス ` とは別のインスタンスで、本番環境に影響を与えてしまう心配をせずに配布" +"ツールやプロセスを試してみることができます。 TestPyPI は `test.pypi.org " +"`_ にホストされています" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "アカウントを登録する" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" +"TestPyPI は PyPI とは別のデータベースで運用されているので、 TestPyPI 専用の" +"ユーザアカウントを作成する必要があります。 https://test.pypi.org/account/" +"register/ へ行ってアカウントを登録しましょう。" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" +"TestPyPI 用のデータベースは定期的に刈り込まれるので、往々にしてユーザアカウン" +"トが削除されることがあります。" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "Twine を使って TestPyPI を使う" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" +":ref:`twine` に ``--repository`` フラグを指定して使うことで、配布物を " +"TestPyPI にアップロードすることができます:" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" +"``https://test.pypi.org/project/`` の ``sample project`` の部" +"分をあなたがアップロードしたプロジェクトの名前に置き換えた URL を参照すれば、" +"あなたのパッケージがうまくアップロードできたかどうかを確認することができま" +"す。サイトにあなたのプロジェクトが反映されるまでには 1,2 分かかるかもしれませ" +"ん。" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "pip で TestPyPI を使う" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" +":ref:`pip` で PyPI の代わりに TestPyPI からパッケージをダウンロードするに" +"は、 ``--index-url`` フラグを指定しましょう:" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" +"pip が PyPI からもパッケージをダウンロードできるようにしたいのであれば、 ``--" +"extra-index-url`` に PyPI を指定しましょう。テストしようとしているパッケージ" +"が依存関係を持つ場合にこれが役に立ちます:" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr ":file:`.pypirc` ファイルで TestPyPI を設定する" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" +"ユーザ名やパスワードの入力を毎回促されるのを避けたいな" +"ら、 :file:`$HOME/.pypirc` 内で TestPyPI の設定をしておくことができます。" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "``pyproject.toml`` を書く" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" +"``pyproject.toml`` は、lintersやtype checkersやその他のパッケージングツール群" +"でも同様に使われる設定ファイルです。このファイルの中には３個の TOML テーブル" +"を置くことが可能です。" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" +"``[build-system]`` テーブルは、 **強く推奨されています** 。これを使うことで、" +"どの :term:`ビルドバックエンド ` を使うのか、また、そのプロ" +"ジェクトをビルドするためには他のどんな依存関係が必要なのかを宣言することがで" +"きます。" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" +"``[project]`` テーブルは、依存関係や作者の名前など、そのプロジェクトの基本的" +"なメタデータを指定するためにほとんどのビルドバックエンドが用いるものです。" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" +"``[tool]`` テーブルは、例えば ``[tool.hatch]`` や ``[tool.black]`` や " +"``[tool.mypy]`` のような、ツールに特化したサブテーブルを持っています。テーブ" +"ルの内容がツール毎に定義されているので、ここでは簡単に触れるだけに留めます。" +"何を含めておくことができるのかを知るためには、それぞれのツールの説明文書に当" +"たってみてください。" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" +"``[build-system]`` テーブルは、 (``[build-system]`` に書くことで使用するビル" +"ドツールを *定義する* ので) どんなビルドバックエンドを使っているかにかかわら" +"ず、常に存在しているべきです。" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" +"他方で、 ``[project]`` テーブルは、 *ほとんどの* ビルドバックエンドで理解され" +"ますが、いくつかのビルドバックエンドは異なる書式を使います。" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" +"特筆すべき例外は Poetry_ で、バージョン 2.0 (2025年1月5日リリース) より前は " +"``[project]`` テーブルを使わず、 代わりに ``[tool.peotry]`` テーブルを使って" +"いました。バージョン 2.0 では、両方をサポートしています。また、 setuptools_ " +"のビルドバックエンドは、 ``[project]`` テーブルと、 ``setup.cfg`` ないし " +"``setup.py`` の中のより古い書き方の両方をサポートしています。" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" +"``setup.cfg`` と ``setup.py`` は依然として正当な書式ですが、新しいプロジェク" +"トでは ``[project]`` テーブルを使い、何かプログラム上の設定が必要である場合に" +"限って ``setup.py`` を維持しましょう。 :ref:`setup-py-deprecated` をみて下さ" +"い。" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "ビルドバックエンドを宣言する" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" +"``[build-system]`` テーブルは、使用されるべきビルドバックエンドを指定する " +"``build-backend`` キーを含んでいます。また、 プロジェクトをビルドするのに必要" +"な依存関係のリストである ``requires`` キーも含んでいます -- これは典型的には" +"ビルドバクエンドのパッケージだけですが、追加の依存関係を含んでいてもかまいま" +"せん。さらに、例えば ``requires = [\"setuptools >= 61.0\"]`` のようにバージョ" +"ンを制限することもできます。" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" +"通常は、ビルドバックエンドの説明文書が (:ref:`ビルドバックエンドを選択する " +"`) 示唆するものをコピーするだけでしょう。よく知られた" +"バックエンドでの値をいくつか挙げておきます:" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "静的なメタデータと動的なメタデータ" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "このガイド文書の残りの部分は、``[project]`` テーブルに捧げます。" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" +"ほとんどの場合、 ``[project]`` フィールドに直接に値を書き込むことになるでしょ" +"う。例えば: ``requires-python = \">= 3.8\"`` や ``version = \"1.0\"`` などで" +"す。" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" +"フィールドが動的となっている場合、そこを埋めるのはビルドバックエンドの責任で" +"す。どうすれば良いのかについては、ビルドバックエンドの説明文書に当たってみて" +"ください。" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "基本的な情報" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "``名称``" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" +"PyPI 上でのプロジェクト名称を書いてください。このフィールドは必須のもので、動" +"的であるとマークできない唯一のフィールドです。" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" +"プロジェクトの名称は、ASCII文字・数字・アンダースコア \"``_``\"・ハイフン " +"\"``-``\"・ピリオド \"``.``\" だけで構成されていなければなりません。また、先" +"頭や末尾にアンダースコア・ハイフン・ピリオドを使ってはいけません。" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" +"プロジェクト名の比較では、大文字小文字を区別せず、また、アンダースコア・ハイ" +"フン・ピリオドは何文字連続していても同じものとして扱います。例えば、あなたが " +"``cool-stuff`` という名前のプロジェクトを登録したなら、利用者がダウンロードし" +"たり依存関係を宣言したりするのに、次に挙げる綴りのいずれであっても使うことが" +"できます: ``Cool-Stuff`` ・ ``cool.stuff`` ・ ``COOL_STUFF`` ・ ``CoOl__-.-" +"__sTuFF`` 。" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "プロジェクトのバージョンを書いてください。" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" +"(アルファ版のリリース用の) ``2020.0.0a1`` のようなもっと込み入ったバージョン" +"指定子も可能ですので、 詳細については :ref:`仕様 ` を見て" +"ください。" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" +"動的であるとマークされることがしばしばではありますが、このフィールドは必須の" +"ものです" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" +"これによって、 ``__version__`` 要素や Git のタグからバージョンを充当するよう" +"な使い方が可能になります。もっと詳しいことは、 :ref:`single-source-version` " +"の議論を見てみてください。" + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "依存関係と要求事項" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "``dependencies``/``optional-dependencies``" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "もしプロジェクトに依存関係があるなら、このように列挙してください:" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" +"バージョンに制限をかけるために使えるあらゆるシンタックスについては、 :ref:`依" +"存関係指定子 ` を参照してください。" + +#: ../source/guides/writing-pyproject-toml.rst:161 +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/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" +"キーのぞれぞれが \"余分のパッケージング \" を定義します。上" +"の例では、プロジェクトを例えば GUI サポート付きでインストールするためには " +"``pip install your-project-name[gui]`` を使うことができます。" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "``requires-python``" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" +"これによってサポートされている Python の下限のバージョンを宣言することができ" +"ます [#requires-python-upper-bounds]_ 。" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "実行可能なスクリプトを作成する" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" +"パッケージの一部としてコマンドをインストールするためには、 " +"``[project.scripts]`` テーブルで宣言してください。" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" +"この例では、プロジェクトをインストールした後に ``spam-cli`` コマンドが利用で" +"きるようになるでしょう。このコマンドを実行することで、 ``import sys; from " +"spam import main_cli; sys.exit(main_cli())`` と同等のことを行うでしょう。" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" +"Windows では、このやり方でパッケージされたスクリプト群はターミナルを必要とし" +"ますので、グラフィカルなアプリケーションの内部から起動した場合にはターミナル" +"がポップアップすることでしょう。これが起きないようにするためには、 " +"``[project.scripts]`` の代わりに ``[project.gui-scripts]`` テープルを使ってく" +"ださい。" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" +"そうすることで、コマンドラインからスクリプトを起動してスクリプトがバックグラ" +"ウンドで走らせることですぐに制御を取り戻すことができるでしょう。" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" +"Windows 上では、 ``[project.scripts]`` と ``[project.gui-scripts]`` の間の差" +"異だけが実質的に効果を持ちます。" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "あなたのプロジェクトについて" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "``authors``/``maintainers``" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" +"これらのフィールドは両方とも名前とメールアドレスの両方またはいずれかで識別さ" +"れる人々のリストを含みます。" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "``説明 ``" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" +"これは、PyPI におけるプロジェクトページの \"ヘッドライン\" (`例 `_) や検索結果 (`例 `_) のような他の場所で表示されるも" +"のなので、１行でプロジェクトの説明をしたものであるべきです。" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "``readme``" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" +"これはプロジェクトの長めの説明文で、PyPI のプロジェクトページに表示されます。" +"典型的には、プロジェクトには ``README.md`` か ``README.rst`` のファイルが存在" +"するものなので、その場合にはここにはそのファイル名だけを書いておけば良いで" +"しょう。" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "README のフォーマットは拡張から自動的に検出されます:" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "``README.md`` → `GitHub 流のマークダウン `_ 、" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" +"``README.rst`` → `reStructuredText _`_ (ただし Sphinx 拡張なし)。" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "次のようにしてフォーマットを明示的に指定することもできます:" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "``license`` と ``license-files``" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" +":pep:`639` によれば、ライセンスはふたつのフィールドで宣言されるべきです:" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" +"``license`` は、ひとつかより多くの :term:`license identifiers ` から構成される :term:`SPDX license expression ` です。" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "``license-files`` は、ライセンスファイルの glob パターンのリストです。" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" +"以前の PEP では、 ``license`` が ``file`` キーもしくは ``text`` キーを伴った" +"テーブルであると指定していましたが、この書式は現在では非推奨になっています。" +"ほとんどの :term:`build backends` は、今では、以下のテーブルに" +"示される新書式をサポートしています。" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr ":pep:`639` のサポートを導入したビルドバックエンドのバージョン" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "hatchling" + +#: ../source/guides/writing-pyproject-toml.rst:313 +msgid "setuptools" +msgstr "setuptools" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "flit-core [#flit-core-pep639]_" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "pdm-backend" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "poetry-core" + +#: ../source/guides/writing-pyproject-toml.rst:317 +msgid "uv-build" +msgstr "uv-build" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "1.27.0" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "77.0.3" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "3.12" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "2.4.0" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "2.2.0" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "0.7.19" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "``ライセンス``" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" +"``licanse`` のための新書式は、ひとつもしくはそれ以上の :term:`ライセンス識別" +"子` から構成される正当な :term:`SPDX ライセンス表現 ` で" +"す。ライセンスの完全なリストは、 `SPDX ライセンスリストページ " +"`_ で利用可能です。サポートされているリストバージョンは " +"3.17 かそれ以降の互換性のあるものです。" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" +"``license`` が辞書かテーブルであるべきだとのビルドエラーを受け取るようなら、" +"そのビルドバックエンドは、まだ、新書式をサポートしていません。さらなる文脈的" +"理解のためには、 `above section `_ を見て下さい。" +"今では非推奨となった書式は、 `PEP 621 に述べられています `__ 。" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" +"一般的な規則としては、標準的でよく知られたライセンスを使うことは良い考えで" +"す、というのは、混乱を避けることにもなるし、中には内部で認可済みのライセンス" +"でなければソフトウェアを使えない組織もあるからです。" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" +":term:`配布物アーカイブ ` が使っているライセンスが既存" +"の SPDX 識別子を持っていない時は、 ``LicenseRef-[idstring]`` の書式で作成する" +"ことができます。カスタム識別子は、バージョン 2.2 かそれより新しい互換のバー" +"ジョンの `clause 10.1 `_ という SPDX 仕様に従わなければなりま" +"せん。" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "``license-files``" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" +"これは、そのパッケージとともに配布したいと望む、ライセンスファイルとその他の" +"法律関係の情報を含むファイルのリストです。" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "glob パターンは、次の仕様に従わなければなりません:" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" +"英数字・アンダースコア (``_``) ・ハイフン (``-``) ・ドット (``.``) が文字通り" +"に合致するでしょう。" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" +"特殊文字: ``*`` ・ ``?`` ・ ``**`` と文字の帯域: [] がサポートされています。" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "パスデリミタは、正スラッシュ (``/``) でなければなりません。" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" +"パターンは、 :file:`pyproject.toml` を含むディレクトリに対する相対パスで、" +"従ってスラッシュ文字で始まることはできません。" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "親ディレクトリ表示子 (``..``) を使用してはなりません。" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "各 glob は、少なくとも一つのファイルにマッチしなければなりません。" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" +"字義通りのパスは、正当な glob です。この仕様でカバーされていない文字や文字の" +"並びは、すべて、正当なものではありません。" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "``keywords``" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" +"これは、 PyPI 上の検索でキーワードが与えられた時にこのプロジェクトをサジェス" +"トするのを助けます。" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "``分類詞 ``" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" +"プロジェクトに合致する PyPI 分類子 のリスト。 `可能な分類子のリ" +"スト `_ を参照してください。" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" +"あるプロジェクトが Python のどのバージョンをサポートしているのかを宣言するた" +"めに分類子 がよく使われますが、この情報は PyPI 上のプロジェクト" +"を検索し閲覧するためにのみ使われるのであって、プロジェクトをインストールする" +"ためには使われません。あるプロジェクトが Python のどのバージョンでならインス" +"トールされ得るのかを実際に制約するためには、 :ref:`requires-python` 引数を" +"使ってください。" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" +"パッケージが PyPI にアップロードされるのを防ぐには、 ``Private :: Do Not " +"Upload`` 分類子を使いましょう。``Private ::`` で始まる分類子を付けられたパッ" +"ケージを PyPI は常に拒否します。" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "``urls``" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" +"プロジェクトに関連のある URL のリストで、PyPI 上のプロジェクトページの左サイ" +"ドバーに表示されるもの。" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" +"PyPI やその他のパッケージングツールがそれぞれどのラベルを認識するかについての" +"リストを見たければ :ref:`well-known-labels` を、 PyPI に特有の URL 処理につい" +"て見たければ `PyPI のプロジェクトメタデータ説明文書 `_ を見て下さい。" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" +"もしラベルが空白文字を含んでいるなら、例えば ``Website = \"https://" +"example.com\"`` ではなくて ``\"Official Website\" = \"https://" +"example.com\"`` のように引用符で囲む必要があります。" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" +"(パッケージインデックスのような) メタデータの消費者側がその存在を特別なものに" +"することができるように、ユーザにはそのプロジェクトの適切な URL のため" +"に :ref:`well-known-labels` を使用することを推奨します。" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" +"後続するメタデータの中での例としては、 ``MyHomepage`` も ``\"Download " +"Link\"`` のいずれもよく知られたラベルではなく、従って、これらは文字通りに展開" +"されます:" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" +"一方で、このメタデータ ``HomePage`` および ``DOWNLOAD`` は、どちらにも、よく" +"知られた同等物 (``homepage`` と ``download``) があり、そのような文脈で提示さ" +"れ得ることを心に留めておいて下さい (順にそれぞれプロジェクトのホームページ、" +"および、その外部のダウンロードできる場所)。" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "先進的なプラグイン" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" +"パッケージの中にはプラグインを使って拡張できるものがあります。例としては、" +"Pytest_ や Pygments_ が挙げられます。そのようなプラグインを作成するためには、" +"以下のように ``[project.entry-points]`` のサブテーブルで宣言する必要がありま" +"す:" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" +"詳しくは、 :ref:`プラグインガイド ` を見てください。" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "完全な例" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" +"ここで ``requires-python = \"<=3.10\"`` のような上限を設定する前に、よくよく" +"考えてください。起きる可能性のある問題に関するいくらかの情報が `このブログ記" +"事 `_ にあります。" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" +"flit-core は、 `まだ `_ 、 SPDX ライセンス表現の WITH をサ" +"ポートしていません。" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +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）" + +#: ../source/index.rst:25 +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." +msgstr "" +"*Python パッケージングユーザガイド* へようこそ、チュートリアルとリファレンス" +"であなたが近代的なツールを使ってパッケージを配布・インストールするのをお手伝" +"いします。" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" +"このガイドは、:doc:`Python パッケージングオーソリティ ` によって " +"`GitHub`_ 上で維持管理されています。:doc:`貢献とフィードバック ` " +"を大いに歓迎します。😊" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "概要と流れ" + +#: ../source/index.rst:40 +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." +msgstr "" +"Python のパッケージングに関する理解を醸成することは旅をするようなものです。忍" +"耐と継続的な改善が成功への鍵となります。概要と流れの章では、Python のパッケー" +"ジングのエコシステムを理解するための出発点を提供します。" + +#: ../source/index.rst:44 +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." +msgstr "" +":doc:`概要 ` では、 Python でのパッケージングとプロジェクトを準備し" +"て配布する時にどのように使うかを説明します。この節では、ツールの選定やユース" +"ケースに最適なプロセスについての理解を醸成します。パッケージングとは何か、そ" +"れが解決する問題、そして鍵となる考慮事項を含みます。" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" +"あなたのソースコードを公開するために用いられるワークフローの概要を得たけれ" +"ば、 :doc:`パッケージングフロー ` を見てください。" + +#: ../source/index.rst:57 +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:" +msgstr "" +"チュートリアルでは、初めてプロジェクトを完成させる際に必要な諸段階を一通り眺" +"めます。チュートリアルは、将来の探検のための出発点を提供することであなたの成" +"功を助けます。 :doc:`チュートリアル ` の節には次のものが含ま" +"れます:" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" +":doc:`パッケージをインストールするためのチュートリアル `" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" +"バージョンを管理しているプロジェクトでの :doc:`アプリケーションの依存関係を管" +"理するためのチュートリアル `" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" +"あなたのプロジェクトの :doc:`パッケージングと配布のためのチュートリアル " +"`" + +#: ../source/index.rst:71 +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." +msgstr "" +"ガイド文書は、特定のタスクを実行するためのステップを提供します。ガイド文書" +"は、すでに Python のパッケージングに慣れていて、特定の情報を探しているような" +"ユーザに、より強く焦点を合わせています。" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" +":doc:`ガイド ` 節では、パッケージインストール; パッケージの作成" +"と配布; その他の話題という３個の主要な分野について \"ハウツー \" とな" +"る指示を提供します。" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "説明と議論" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" +":doc:`議論 ` の節は、以下に述べるような話題に関する詳細に" +"渡る説明と議論を提供します:" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +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 "参考文献" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" +"パッケージングに関する相互運用性の仕様については、 :doc:`仕様 " +"` を見てください。" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" +"Python パッケージングオーソリティのメンバーが維持管理している :doc:`他のプロ" +"ジェクト群 ` のリスト。" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" +"Python パッケージングで使われる用語の定義についての :doc:`語彙集 " +"` 。" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "プロジェクト概要" + +#: ../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/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "PyPA プロジェクト群" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "bandersnatch" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`説明文書 `__ | `課題リスト `__ | `GitHub `__ | `PyPI `__" + +#: ../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:37 +msgid "build" +msgstr "ビルド" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +":any:`文書 ` | `課題リスト `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" +"``build`` は :pep:`517` 互換の Python パッケージビルダです。Python API と同様" +"に、パッケージをビルドする CLI を提供します。" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "cibuildwheel" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" +"`説明文書 `__ | `課題リスト `__ | `GitHub `__ | `PyPI `__ | `議論 " +"`__ | `Discord " +"#cibuildwheel `__" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" +"``cibuildwheel`` は、プラットフォーム・ Python バージョン・ CIシステムのよく" +"ある組み合わせの全部について :term:`wheels ` をビルドする Python パッ" +"ケージです。" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "distlib" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +":doc:`文書 ` | `課題リスト `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:73 +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." +msgstr "" +"``distlib`` は、 Python ソフトウェアのパッケージングや配布に関係する低レベル" +"の機能を実装しているライブラリです。 ``distlib`` はいくつかの関連する PEP " +"(Python Enhancement Proposal standards) を実装していて、サードパーティのパッ" +"ケージングツールの開発者にとってバイナリやソースコードの :term:`配布物 " +"` を作成・アップロードしたり、相互運用性を確保したり、" +"依存関係を解決したり、パッケージリソースを管理したり、その他の類似の機能を実" +"行したりするのに便利です。" + +#: ../source/key_projects.rst:82 +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." +msgstr "" +"近代的な Python パッケージングにおける相互運用性標準に特に気を配って実装され" +"た、より厳格な :ref:`packaging` プロジェクト (後述) とは異なり、 ``distlib`` " +"は近代的な相互運用性標準ができる前の昔ながらのパッケージやメタデータで今と" +"なってはその標準に外れたことになっているものを扱うように言われた時には合理的" +"なフォールバック動作も提供しようとしています。" + +#: ../source/key_projects.rst:93 +msgid "distutils" +msgstr "distutils" + +#: ../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/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 "" +"パッケージングシステムを維持管理する際の難題には機能向上が言語ラインタイムの" +"更新と密接に結びついていることが挙げられますが、そのせいで :ref:`distutils` " +"を直接に使用することは強い非推奨事項にずっとなり続けてきており、代わり" +"に :ref:`Setuptools` を使うことが望ましいとされています。 :ref:`Setuptools` " +"は、 :ref:`distutils` そのものが提供していない機能 (例えば依存関係の宣言やエ" +"ントリポイントの宣言) を提供できるだけでなく、守備一貫したビルド用のインタ" +"フェイスやサポートするすべてのバージョンの Python のすべてについて設定できる" +"機能を提供しています。" + +#: ../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 "" +"従って、 :ref:`distutils` は :pep:`632` によって Python 3.10 で非推奨にな" +"り、 Python 3.12 で標準ライブラリから :doc:`削除 ` され" +"ました。Setuptools にはスタンドアローンの distutils が同梱されていて、< 3.12 " +"の Python 上であっても setuptools をインポートするか pip を使うと注入されま" +"す。" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "flit" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" +"`説明文書 `__ | `課題リスト `__ | `PyPI `__" + +#: ../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/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/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/key_projects.rst:142 +msgid "hatch" +msgstr "hatch" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`説明文書 `__ | `GitHub `__ | `PyPI `__" + +#: ../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/key_projects.rst:157 +msgid "packaging" +msgstr "packaging ライブラリ" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +":doc:`説明文書 ` | `課題リスト `__ | `GitHub `__ | " +"`PyPI `__" + +#: ../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/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 "" +"packaging ライブラリの core utilities は、バージョンの取り扱い、識別子、マー" +"カ、依存先パッケージ、タグ、その他これに類似した属性やタスクを取り扱います。 " +"Python ユーザのほとんどは、明示的に呼び出す必要に迫られることはなくともこのラ" +"イブラリに依存しています; ここにリストされているような Python のパッケージン" +"グや配布やインストールを扱う他のパッケージを開発する者は、パースしたり検出し" +"たりそうでなければ依存関係の属性を取り扱うようなこのライブラリの機能をしばし" +"ば利用しています。" + +#: ../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 "" +"`説明文書 `__ | `課題リスト `__ | `GitHub `__ | `PyPI `__" + +#: ../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 パッケージをインストールするに当たっての最もよく知られたツールで、" +"Python の新しめのバージョンには同梱されているもの。" + +#: ../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 "" +"PyPI やその他の Python パッケージインデックスのパッケージを探索・ダウンロー" +"ド・インストールするための基本的な機能を提供するとともに、コマンドラインイン" +"タフェイス (CLI) を通じて広範囲の開発ワークフローに組み込むことができます。" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "Pipenv" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +msgstr "" +":doc:`説明文書 ` | `ソースコード `__ | `課題リスト `__ | `PyPI " +"`__" + +#: ../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/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/key_projects.rst:225 +msgid "Pipfile" +msgstr "Pipfile" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "`ソースコード `__" + +#: ../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/key_projects.rst:236 +msgid "pipx" +msgstr "pipx" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" +"`説明文書 `__ | `GitHub `__ | `PyPI `__" + +#: ../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/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" +":doc:`説明文書 ` | `課題リスト `__ | `GitHub `__" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "このガイド!" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "readme_renderer" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" +"`GitHub および説明文書 `__ | `PyPI " +"`__" + +#: ../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/key_projects.rst:274 +msgid "Setuptools" +msgstr "Setuptools" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`説明文書 `__ | `課題リスト " +"`__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" +"(``easy_install`` を含む) Setuptools は Python の distutils への拡張を集めた" +"もので、特に他のパッケージに依存関係がある場合に、より簡単に Python " +"の :term:`配布物 ` をビルドし配布することが可能となりま" +"す。" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "trove-classifiers" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" +"`課題リスト `__ | `GitHub " +"`__ | `PyPI `__" + +#: ../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/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/key_projects.rst:314 +msgid "twine" +msgstr "twine" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`説明文書 `__ | `課題リスト " +"`__ | `GitHub `__ | `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/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "virtualenv" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`説明文書 `__ | `課題リスト " +"`__ | `GitHub `__ | `PyPI `__" + +#: ../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/key_projects.rst:350 +msgid "Warehouse" +msgstr "Warehouse" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" +"`説明文書 `__ | `課題リスト `__ | `GitHub `__" + +#: ../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/key_projects.rst:364 +msgid "wheel" +msgstr "wheel" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`説明文書 `__ | `課題リスト " +"`__ | `GitHub `__ | `PyPI `__" + +#: ../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/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/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "非 PyPA プロジェクト" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "buildout" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" +"`説明文書 `__ | `課題リスト `__ | `PyPI `__ | `GitHub `__" + +#: ../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 "" +"Buildout は Python ベースのビルドシステムで、非 Python ベースのものを含む複数" +"の部品から構成されるアプリケーションの生成・組み立て・配置ができます。" +"buildout の設定を作っておけば、後で同じソフトウェアを再生成することができま" +"す。" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "conda" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr ":doc:`説明文書 `" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" +"Conda は、任意の言語 -- Python ・ R ・ Ruby ・ C/C++ ・ Fortran ・その他向け" +"のパッケージ・依存関係・環境の管理システムです。 Python で書かれており、非 " +"Python のライブラリや拡張をサポートしているために、 Python の科学計算コミュニ" +"ティで広く使われています。 Anaconda, Inc. が出している Python 配布物である " +"`Anaconda `__ の基礎として使われていま" +"す。元々は科学計算コミュニティを目標にしたものですが、しかし、それ自身" +"や :doc:`miniconda `" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" +"Conda は、 :ref:`pip` や virtualenv や wheel とは全く別のツールですが、パッ" +"ケージ管理・仮想環境管理・バイナリ拡張のデプロイメントなどの、これらのツール" +"を合わせたような機能を提供します。" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" +"Conda は、 PyPI あらパッケージをインストールすることはしません -- " +"`anaconda.org `__ もしくは (例えば イントラネットのよう" +"な) ローカルのパッケージサーバのような \"conda channel\" から利用可能な、特" +"に conda 用にビルドされたパッケージを管理することができるだけです。 " +"`Anaconda, Inc. `__ が維持管理する \"default\" " +"チャンネルに加えて、コミュニティがサポートする `conda-forge project `__ にも広範囲にわたるパッケージがあります。" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" +"PyPI からの :term:`distributions ` を維持管理するため" +"に、 conda と並列に :ref:`pip` をインストールすることが可能で、並列に動作する" +"ということを覚えておいて下さい。また、 `conda skeleton `__ 、これは PyPI 上で利用可能な Python パッケージから conda " +"パッケージを自動的に作成するツールですが、そのようなツールを使って、 conda " +"パッケージ群を Python ソースコードパッケージからビルドすることもできます。" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "devpi" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" +"`説明文書 `__ | :gh:`課題リスト ` | `PyPI `__" + +#: ../source/key_projects.rst:441 +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." +msgstr "" +"devpi は、 PyPI 互換の強力なサーバと PyPI プロクシキャッシュの機能を持ってい" +"て、 Python を使ったパッケージングやテスティングやリリース活動を推進するため" +"の補完的なコマンドラインツールを備えています。devpi は、また、閲覧と検索が可" +"能なwebインタフェイスも備えています。devpi は、 PyPI のミラーを作成する機能、" +"継承関係を持った複数の :term:`パッケージインデックス ` を扱う" +"機能、これらのインデックスの間の同期機能、インデックスの複製とフェイルオーバ" +"とパッケージのアップロードの機能を提供できます。" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "dumb-pypi" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" +"`GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:457 +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/key_projects.rst:464 +msgid "enscons" +msgstr "enscons" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" +":gh:`ソースコード ` | :gh:`課題リスト ` | `PyPI `__" + +#: ../source/key_projects.rst:470 +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/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "Flask-Pypi-Proxy" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" +"`説明文書 `__ | :gh:`GitHub " +"` | `PyPI `__" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "もはや保守されておらず、アーカイブされたプロジェクト" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" +"Flask-PyPI-Proxy は PyPI に対するキャッシュ付きのプロクシという形の :term:`" +"パッケージインデックス ` です。" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "Hashdist" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" +"`説明文書 `__ | `GitHub `__" + +#: ../source/key_projects.rst:504 +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/key_projects.rst:516 +msgid "Maturin" +msgstr "Maturin" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" +"`説明文書 `__ | `GitHub `__" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" +"Maturin は Rust 拡張モジュール用のビルドバックエンドで、Rust で書かれていま" +"す。Windows ・ Linux ・ macOS および FreeBSD 上で python 3.7+ の wheel をビル" +"ドすることができ、それを PyPI にアップロードすることができ、また、 PyPy と " +"GraalPy に対する基本的なサポートもあります。" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "meson-python" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" +"`説明文書 `__ | `GitHub " +"`__" + +#: ../source/key_projects.rst:534 +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/key_projects.rst:544 +msgid "multibuild" +msgstr "multibuild" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "`GitHub `__" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" +"Multibuild は、Linux ・ macOS 向けや (柔軟性は落ちるが) Windows 向けの " +"Python :term:`wheels ` をビルドしテストする一揃いの CI スクリプトで" +"す。 :ref:`cibuildwheel` も見てください。" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "nginx_pypi_cache" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr ":gh:`GitHub `" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" +"nginx_pypi_cache は、 `nginx `_ を用いた :term:`パッ" +"ケージインデックス ` のキャッシュ機能付きプロクシです。" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "pdm" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`説明文書 `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:570 +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/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`説明文書 `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:582 +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/key_projects.rst:594 +msgid "pip-tools" +msgstr "pip-tools" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`説明文書 `__ | `GitHub " +"`__ | `PyPI `__" + +#: ../source/key_projects.rst:600 +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." +msgstr "" +"pip-tools は、Python システムの管理者やリリースマネージャで、特にビルドが必ず" +"できるように保ちたいけれども依存先の新バージョンに追随して最新の状態にもして" +"おきたいという人々のための一揃いのツール群です。ユーザはハッシュ値を与えるこ" +"とで依存先の特定のリリースを指定することや、そのプログラムの他の部分にある情" +"報から適切な書式の requirements を簡単に作成すること、すべての依存先を更新す" +"ること (これは現時点の :ref:`pip` にはない機能です) 、プログラムが従うべき制" +"約条件の層を作成することができます。" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "pip2pi" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +":gh:`GitHub ` | `PyPI `__" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" +"pip2pi は、特定のパッケージ群が手動で同期される :term:`パッケージインデック" +"ス ` です。" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "piwheels" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" +"`Web サイト `__ | :doc:`説明文書 " +"` | `GitHub `__" + +#: ../source/key_projects.rst:629 +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 "" +"piwheels は、ソースコード配布物パッケージを PyPI から取得して Raspberry Pi 計" +"算機へのインストールに最適化されたバイナリ wheel ファイルにコンパイルするよう" +"な Web サイトであり、それを支えるソフトウェアです。 Raspberry Pi OS では、 " +"pip が PyPI に加えて piwheel.org を追加のインデックスとして使うように予め設定" +"されています。" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "poetry" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`説明文書 `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:644 +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." +msgstr "" +"poetry は、 Python パッケージのビルドやパッケージングに加えて、依存先のインス" +"トールや隔離を取り扱うコマンドラインのツールです。 :ref:`pip` に含まれる解決" +"機能に依存する代わりに ``pyproject.toml`` を使って自分自身の依存関係解決機能" +"を提供します。依存関係に関するメタデータをローカルにキャッシュすることでイン" +"ストールや依存関係解決のユーザ体験を高速化しようとしています。" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "proxpi" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +":gh:`GitHub ` | `PyPI `__" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" +"proxpi は、PyPI や他のインデックスをキャッシュ付きでプロクシする単純" +"な :term:`パッケージインデックス ` です。" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "Pulp-python" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" +"`説明文書 `__ | :gh:`GitHub ` | `PyPI `__" + +#: ../source/key_projects.rst:671 +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." +msgstr "" +"Pulp-python は、 `Pulp ` 向けの Python :term:`パッ" +"ケージインデックス ` プラグインです。 Pulp-python は、ローカル" +"か `AWS S3`_ にファイルを置くミラー機能や、複数のパッケージインデックスへのプ" +"ロクシ機能をサポートします。" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "PyPI クラウド" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" +"`説明文書 `__ | :gh:`GitHub ` | `PyPI `__" + +#: ../source/key_projects.rst:687 +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." +msgstr "" +"PyPI クラウドは、`AWS S3`_ や他のクラウドストレージサービス、あるいはローカル" +"のファイル群で裏打ちされた :term:`パッケージインデックス ` で" +"す。PyPI クラウドは、認証や認可と同様に PyPI に対するリダイレクト機能やプロク" +"シ機能をサポートします。" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "pypiprivate" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +":gh:`GitHub ` | `PyPI `__" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" +"pypiprivate は、 :term:`パッケージインデックス ` としてローカ" +"ルの (または `AWS S3`_ でホストされた) パッケージディレクトリを提供します。" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "pypiserver" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" +"`GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:711 +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." +msgstr "" +"pypiserver は、単純な API とブラウザ向けのインターフェースを実装した (ローカ" +"ルディレクトリ上の) 組織内部向けプライベート Python :term:`パッケージインデッ" +"クス ` を提供するミニマリストのアプリケーションです。公衆向け" +"に公開することなく標準のツールを使って外部非公開のパッケージをアップロードす" +"ることもできますし、それを :ref:`pip` でダウンロード・インストールすることも" +"できます。 pypiserver を用いる組織では、通常は pypiserver と PyPI の両方から" +"パッケージをダウンロードします。" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "PyScaffold" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`説明文書 `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:728 +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/key_projects.rst:739 +msgid "pywharf" +msgstr "pywharf" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +":gh:`GitHub ` | `PyPI `__" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" +"pywharf は、ローカルから、もしくは `GitHub `_ からファイ" +"ルを提供する :term:`パッケージインデックス ` です。" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "scikit-build" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`説明文書 `__ | `GitHub " +"`__ | `PyPI `__" + +#: ../source/key_projects.rst:758 +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:769 +msgid "scikit-build-core" +msgstr "scikit-build-core" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" +"`説明文書 `__ | `GitHub " +"`__ | `PyPI `__" + +#: ../source/key_projects.rst:775 +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." +msgstr "" +"Scikit-build-core は、CPython C/C++/Fortran/Cython による拡張モジュールのため" +"のビルドバックエンドです。追加のコンパイラやビルドシステムやクロスコンパイ" +"ル、また、依存関係とそれに付随するビルド時の要求事項を解決する点でより良いサ" +"ポートを提供するために、ユーザが `cmake `__ " +"(PyPI から利用可能) を使って拡張を書くことができるようにします。 CMake/Ninja " +"は、もしシステム上に利用可能なものがなければ、 PyPI から自動的にダウンロード" +"されます。" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "shiv" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`説明文書 `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:791 +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." +msgstr "" +"shiv は、 :pep:`441` に概要が示されている完全自己完結型 Python zipapp である" +"が必要な依存先をすべて内包したものをビルドするためのコマンドラインユーティリ" +"ティです。このツールの第一の目標は、Python アプリケーションとコマンドライン" +"ツールを素早く簡便に配布できるようにすることです。" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "simpleindex" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +":gh:`GitHub ` | `PyPI `__" + +#: ../source/key_projects.rst:804 +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." +msgstr "" +"simple index は、 URL を (PyPI を含む) 複数のパッケージインデックスに振り分" +"け、ローカルの (または、カスタムプラグインを使って例えば `AWS S3`_ のようなク" +"ラウドにホストされた) パッケージディレクトリからファイルを提供し、カスタムプ" +"ラグインをサポートしている :term:`パッケージインデックス ` で" +"す。" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" +":doc:`説明文書 ` | `GitHub `__ " +"| `論文 `__ | `スライド `__" + +#: ../source/key_projects.rst:819 +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/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" +"Spack は (まだ) PyPI にありませんが、 GitHub からクローンした直後にインストー" +"ル作業なしで使用できます。" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "zest.releaser" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`説明文書 `__ | `GitHub " +"`__ | `PyPI `__" + +#: ../source/key_projects.rst:839 +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." +msgstr "" +"``zest.releaser`` は、 :ref:`twine` の上に抽象レイヤを提供する Python パッ" +"ケージのリリースツールです。 Python 開発者は ``zest.releaser`` を使ってパッ" +"ケージバージョンを増加させたり、変更履歴 (Changelog) を更新したり、ソースコー" +"ド管理の側でリリースタグを挿入したり、新しいパッケージを PyPI にアップロード" +"することを自動化することができます。" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "標準ライブラリ内のプロジェクト群" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "ensurepip" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" +"`説明文書 `__ | `課題リス" +"ト `__" + +#: ../source/key_projects.rst:856 +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." +msgstr "" +"このパッケージはPython の標準ライブラリ内のパッケージで、既存のインストール済" +"み Python 環境や仮想環境に :ref:`pip` を組み込むためのサポートを提供します。" +"ほとんどの場合にはエンドユーザがこのモジュールを使うことはなく、どちらかと言" +"えば Python 配布物のビルドの際に使われるでしょう。" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "http.server" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" +":doc:`説明文書 ` | :gh:`課題リスト `" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" +"ウェブサイトとして、つまり例えば :term:`パッケージインデックス ` として、ディレクトリを扱うことができるパッケージとコマンドラインイン" +"タフェース (:ref:`自分用のシンプルなリポジトリをホストする ` を参照してください) 。" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "venv" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" +"`説明文書 `__ | `課題リスト " +"`__" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" +"(Python 3.3 から始まる) Python の標準ライブラリに存在する :term:`仮想環境 " +"` を生成するためのパッケージ。更なる情報について" +"は :ref:`仮想環境を作って使う ` を見" +"てください。" + +#: ../source/news.rst:2 +msgid "News" +msgstr "ニュース" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" +"この文書は現在では更新されていません。以前は、Python パッケージングでの変更点" +"をハイライトしていました。" + +#: ../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 "" +"GitHub Actions を経由して配布物を公開するためのガイドを追加。 (:pr:`647`)" + +#: ../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 "" +"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`)" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" +"Sphinx のバージョンを上げ、papa.io の intersphinx を削除した。 (:pr:`625`)" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr ":file:`find_namespace_packages` に言及した。 (:pr:`622`)" + +#: ../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 "" +":file:`python_requires` の使い方をパッケージングチュートリアルに追記した。 " +"(:pr:`613`)" + +#: ../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/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" +":file:`shiv` への言及を嗅ぎとなるプロジェクト群の節に追加した。 (:pr:`608`)" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "virtualenv に関する強調を減少させた。 (:pr:`606`)" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "2019年3月" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" +"「パッケージのバージョンを１箇所で管理する」の項を Python 3 側に移した。 " +"(:pr:`605`)" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "RTD の詳細について貢献方法のところでカバーした。 (:pr:`600`)" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "2019年2月" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" +"チュートリアルの内容と実際のパッケージングプロセスの間の差異について詳しく述" +"べた。 (:pr:`602`)" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" +"Python の CLI アプリケーションをインストールするための指示書きを追加した。 " +"(:pr:`594`)" + +#: ../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/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "Sphinx と Nox について更新した。 (:pr:`591`)" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "Python 3 の項に Twine への言及を追加した。 (:pr:`581`)" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "2018年12月" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "事務所にプログラマが居ません！" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "2018年11月" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "PyPI 移行ガイドへのランディングページリンクを削除した。 (:pr:`575`)" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "bumpversion を bump2version に変更した。 (:pr:`572`)" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "パッケージバージョンの一元管理の例を追加した。 (:pr:`573`)" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "ドキュメント作成のためのガイドを追加した。 (:pr:`568`)" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "2018年10月" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "Nox パッケージの名称を更新した。 (:pr:`566`)" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "ガイドの中で Sphinx 拡張について言及した。 (:pr:`562`)" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "2018年9月" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "RST マークアップの検査に関する節を追加した。 (:pr:`554`)" + +#: ../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/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +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`)" + +#: ../source/news.rst:81 +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`)" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "2018年7月" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "バイナリ拡張に関する説明文書を改善した。 (:pr:`531`)" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "scikit-build を主要プロジェクトに追加した。 (:pr:`530`)" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "2018年6月" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "pypa.io に関する相互運用性 PEP のカテゴリ分けを修正した。 (:pr:`527`)" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "descriptions をマークダウンで書く場合の説明を更新した。 (:pr:`522`)" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "2018年5月" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "Provides-Diet と Obsolete-Diet の課題を注記した。 (:pr:`513`)" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" +"Pipenv で異なるバージョンの Python を使う場合の警告が古くなっていたので削除し" +"た。 (:pr:`501`)" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "パッケージングのチュートリアルを簡素にした。 (:pr:`498`)" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "明確性のため、 Windows ユーザ向けの指示を更新した。 (:pr:`493`)" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "完全性のためにライセンスの節の記述を更新した。 (:pr:`492`)" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "「貢献するには」の節に仕様のスタイルの記述を追加した。 (:pr:`489`)" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "「貢献するには」ガイドにドキュメントのタイプを追記した。 (:pr:`485`)" + +#: ../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 "" +"(パッケージを?) 公開するチュートリアルから GPG の参照情報を削除した。 " +"(:pr:`466`)" + +#: ../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/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" +"あるバージョンの Python を徐々に使わなくするガイドを追加した。 (:pr:`459`)" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" +"変種の GFM をデフォルトの Description-Content-Type とした。 (:pr:`462`)" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "2018年3月" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "「科学計算分野のパッケージ群」を更新した。 (:pr:`455`)" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" +"PEP 556 に従う :file:`long_description_content_type` を追加した。 (:pr:`457`)" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" +"pypi.org における long description 分類子について明確化した。 (:pr:`456`)" + +#: ../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 "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" +"Debian でのインストール指示に python3-venv と python3-pip を追記した。 " +"(:pr:`445`)" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "PyPI 移行情報を更新した。 (:pr:`439`)" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" +"複数のバージョンの pipenv を取り扱う際の注意事項を追記した。 (:pr:`430`)" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" +"コアとなるメタデータの項に複数の電子メールアドレスの例を追加した。 " +"(:pr:`429`)" + +#: ../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/news.rst:137 +msgid "January 2018" +msgstr "2018年1月" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "PyPI にある分類子のリストへのリンクを追加した。 (:pr:`425`)" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "README.rst についての説明を更新した。 (:pr:`419`)" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "2017年12月" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" +"ガイドやチュートリアルで :file:`~` を :file:`$HOME` に置き換えた。 " +"(:pr:`418`)" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" +"環境マーカとともにどのフィールドを使うことができるのかについて注記した。 " +"(:pr:`416`)" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "Requires-Python の節を更新した。 (:pr:`414`)" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "ニュースのページを追加した。 (:pr:`404`)" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "2017年11月" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" +"Pipenv を基盤とした依存関係の管理に関するチュートリアルを新たに追加した。 " +"(:pr:`402`)" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" +"*パッケージバージョンの一元管理* のチュートリアルが pip の現在の戦略を反映す" +"るように更新した。 (:pr:`400`)" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" +"``setup`` に対する ``py_modules`` 引数について説明を追加した。 (:pr:`398`)" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr ":file:`manifest.in` 節での用語を簡素化した。 (:pr:`395`)" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "2017年10月" + +#: ../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/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" +"``pip`` や ``virtualenv`` を用いてパッケージを管理するためのガイドを新設し" +"た。 (:pr:`385`)" + +#: ../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/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +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`)" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "2017年8月" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" +"``Pipenv`` を用いてパッケージをインストールする方法について新たに試験的な" +"チュートリアルを追加した。 (:pr:`369`)" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "``TestPyPI`` を使う方法について新たにガイドを追加した。 (:pr:`366`)" + +#: ../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 "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" +"本ガイドの ``readme`` にローカル環境でこのガイドをビルドする方法を追加して更" +"新した。 (:pr:`356`)" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" +"ホームページにpypi.org に関する注記を加えることで、新しい ``TestPyPI`` の " +"URL がより目立つようにした。 (:pr:`354`)" + +#: ../source/news.rst:187 +msgid "" +"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 "" +":file:`PyPI.org` へのアップロード方法の変更について説明を追加した。 " +"(:pr:`339`)" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "``python_requires`` について説明を追加した。 (:pr:`338`)" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" +"*推奨されるツール* のチュートリアル内で PyPI の移転に関する注記を追加した。 " +"(:pr:`335`)" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +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`)" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "2017年5月" + +#: ../source/news.rst:206 +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`)" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" +"プロジェクト単位の索引における ``pip`` と ``easy_install`` の差異について説明" +"した。 (:pr:`233`)" + +#: ../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 "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" +"wheel ファイルを生成するための ``wheel`` パッケージへの要求条件に言及するよう" +"にした。 (:pr:`299`)" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" +"*パッケージを配布する* チュートリアルにおいて ``twine register`` への参照を削" +"除した。 (:pr:`271`)" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "プラグインの検索に関する話題を追加した。 (:pr:`294`, :pr:`296`)" + +#: ../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 "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" +"開発モードの説明文書を更新して、ローカルパッケージの記入順に意味があることに" +"言及するようにした。 (:pr:`208`)" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" +"ホストしているプロジェクトのところで readthedocs の引っ越しに合わせてリンク" +"を ``.org`` から ``.io`` に変更した。 (:pr:`239`)" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" +"順序が意味を持つので、アップロードコマンドの :file:`setup.py` の引数の順序を" +"入れ替えた。 (:pr:`260`)" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" +"サポートされていないソースからヘルパーアプリケーションを用いてインストールす" +"る方法について説明した。 (:pr:`289`)" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "2017年3月" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" +"*プラットフォームWheels* の項で ``manylinux1`` をカバーした。 (:pr:`283`)" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "2017年2月" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr ":pep:`518` を追加した。 (:pr:`281`)" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "Python におけるパッケージングに関する概要" + +#: ../source/overview.rst:7 +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." +msgstr "" +"汎用プログラミング言語として Python は数多くの用途に使えるように設計されてい" +"ます。ウェブサイト構築にも産業用ロボットにもあなたが友達と一緒に遊ぶゲームに" +"ももっと他の用途にも、同じコア技術が使えるのです。" + +#: ../source/overview.rst:12 +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." +msgstr "" +"Python は自由度が高いので、プロジェクトの利用者について、また、それに対応して" +"プロジェクトが動作するであろう環境について、すべての Python プロジェクトにお" +"いて最初に考えなければなりません。コードを書く前にパッケージングについて考え" +"ておくというのは奇妙に見えるかもしれませんが、この作業こそが将来の頭痛の種を" +"摘み取るという驚くべきことを起こすのです。" + +#: ../source/overview.rst:18 +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." +msgstr "" +"この概要文書は、 Python の過剰とも言える多数のパッケージング手段からどれを選" +"択するかについての汎用の決定木を提供します。読み進めて、あなたの次のプロジェ" +"クトにとっての最適解を選んでください。" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "デプロイメントについて検討する" + +#: ../source/overview.rst:25 +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:" +msgstr "" +"パッケージはインストールされる(あるいは *配置* される)ために存在しているの" +"で、なにかをパッケージ化する前に次のような配置のための質問にいくらかの答えを" +"持っておきたいと思うでしょう:" + +#: ../source/overview.rst:29 +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?" +msgstr "" +"あなたのソフトウェアのユーザはどんな人たちでしょうか？ソフトウェアを開発する" +"他の開発者たちがインストールするのでしょうか、データセンタでオペレーションを" +"する人々でしょうか、それとも、ソフトウェアを知り尽くしているとは言えないよう" +"な人たちでしょうか？" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" +"あなたのソフトウェアは、単独でインストールされるものですか、それとも、巨大な" +"デプロイメントバッチの一部として？" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "Python のライブラリやツールをパッケージングする" + +#: ../source/overview.rst:45 +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`." +msgstr "" +"PyPI や ``setup.py`` 、 ``wheel`` ファイルについて聞いたことがあるかもしれま" +"せん。これらは Python のソースコードを開発者に配布するための Python エコシス" +"テムのほんの一部で、これらについては :doc:`guides/distributing-packages-" +"using-setuptools` に説明があります。" + +#: ../source/overview.rst:50 +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`." +msgstr "" +"パッケージングに関する以下のアプローチは、開発環境における技術に明るい聞き手" +"が用いるライブラリやツールを念頭に置いています。技術にあまり明るくない聞き手" +"向けに Python をパッケージする方法や、製品使用環境での方法を探している場合" +"は、 :ref:`アプリケーションをパッケージングする` まで飛ばしてください。" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "Python モジュール" + +#: ../source/overview.rst:58 +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." +msgstr "" +"標準ライブラリだけに依存している Python のファイルは、再配布して再利用するこ" +"とができます。他には正しいバージョンの Python 用に書かれていることと、標準ラ" +"イブラリだけに依存していることを確実にしておけば良いでしょう。" + +#: ../source/overview.rst:63 +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 " +"`." +msgstr "" +"この方法は、単純なスクリプトやスニペットを互換性のあるバージョンの Python を" +"持っている人たちどうしで (電子メールや StackOverflow や GitHub gists などで) " +"共有するには優れた方法です。例えば :doc:`bottle.py ` " +"や :doc:`boltons ` のように、 Python ライブラリ全体をこ" +"のやり方で共有することをオプションの一つとして提供しているものさえあります。" + +#: ../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/overview.rst:75 +msgid "Python source distributions" +msgstr "Python ソースコード配布物" + +#: ../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/overview.rst:81 +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." +msgstr "" +"パッケージは複数のファイルで構成されるので、その配布がやや難しくなります。ほ" +"とんどのプロトコルではたった一個のファイルしか一度に送ることができません (リ" +"ンクをクリックしたら複数のファイルをダウンロードしたことあります？)。不完全な" +"転送になってしまうことは容易く、送り先でソースコードの完全性を保証することは" +"困難です。" + +#: ../source/overview.rst:87 +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." +msgstr "" +"あなたのソースコードが純粋な Python コード以外は何も含んでいない間は、そし" +"て、配置先の環境であなたが想定しているバージョンの Python が動作することを" +"知っていれば、 Python 由来のパッケージングツールを使って *ソースコード" +"* :term:`配布パッケージ ` もしくは 短縮系で*sdist* を使" +"えば良いでしょう。" + +#: ../source/overview.rst:92 +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." +msgstr "" +"Python の *sdists* は圧縮済みのアーカイブ (``.tar.gz`` ファイル) で、ひとつか" +"それ以上のパッケージないしモジュールを内包しています。もしあなたのソースコー" +"ドが純粋に Python だけで書かれていて、他の Python パッケージに依存しているだ" +"けなら、 :ref:`ソースコード配布物フォーマット ` " +"仕様を見ればもっと詳しく知ることができます。" + +#: ../source/overview.rst:97 +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." +msgstr "" +"もし非 Python のソースコード、あるいは、非 Python のパッケージ (`lxml " +"`_ における `libxml2 `_ や、`numpy `_ における BLAS ライブラリなど) に依存しているなら、純 Python で書かれ" +"たライブラリにとっても多くの利点がある、次の節で詳細に説明されるフォーマット" +"を使う必要があるでしょう。" + +#: ../source/overview.rst:104 +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!" +msgstr "" +"Python と PyPI は、同一のパッケージの異なる実装を提供する複数の配布物をサポー" +"トしています。例えば、もはや保守されてはいないが先駆的で重要な `PIL 配布物 " +"`_ が PIL パッケージを提供しているし、 PIL か" +"らフォークして今も活発に保守されている `Pillow `_ も同様です！" + +#: ../source/overview.rst:111 +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``." +msgstr "" +"この Python パッケージングの素晴らしいパワーで、あなたのプロジェクトの " +"``install_requires`` か ``requirements.txt`` を変更するだけで Pillow が PIL " +"に対して単純に入れ替えるだけで済む代替物になっているのです。" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "Python バイナリ配布物" + +#: ../source/overview.rst:118 +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." +msgstr "" +"Python の実際的な力の多くは、ソフトウェアのエコシステム、とりわけ C ・ C++ " +"・ Fortran ・ Rust ・その他の言語で書かれたライブラリと統合できる能力からもた" +"らされます。" + +#: ../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." +msgstr "" +"このようなコンパイルを必要とする言語で書かれた部品をビルドするのに適切なツー" +"ルや経験をすべての開発者が持っているわけではないので、ライブラリをコンパイル" +"済みの状態で出荷するように設計された :term:`Wheel` を Python は作りました。実" +"際に、 Python のパッケージインストーラである ``pip`` は、インストールが素早く" +"できるので常に wheel ファイルを選好するし、純 Python のパッケージでさえも " +"wheel ファイルの方がうまく動作します。" + +#: ../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 "" +"バイナリ配布物は、対応するソースコード配布物と一緒に配布されるのが最良です。 " +"あらゆるオペレーティングシステム用のソースコードの wheel ファイルをアップロー" +"ドしていないとしても、sdist をアップロードすることで他のプラットフォームの" +"ユーザたちがビルドすることができるかもしれません。あなたが極めて特殊なユース" +"ケース向けにプログラムを作成していて、受け取る人たちがいずれか一方しか必要と" +"しないことを熟知しているので *ない限り* 、 sdist と wheel の両方を一緒に公開" +"することをデフォルトにしてください。" + +#: ../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." +msgstr "" +"Python と PyPI を使えば、wheel ファイルと sdist ファイルを一緒にアップロード" +"するのが簡単になります。 :doc:`tutorials/packaging-projects` のチュートリアル" +"に従うだけです。" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "ツールやライブラリ向けの Python のパッケージング機能の概要。" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" +"Python が推奨するライブラリやツールをパッケージングする技術。`パッケージング" +"の変遷 (2017) `_ から抜粋。" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "Python アプリケーションをパッケージングする" + +#: ../source/overview.rst:154 +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." +msgstr "" +"ここまで、 Python に元々組み込まれている配布ツールについてだけ議論してきまし" +"た。この導入部分に基づいて、これらのビルトインされたアプローチが Python のあ" +"る環境だけを対象にしたもので、聞き手は Python パッケージのインストール方法を" +"知っているものと推測するのは正しいでしょう。" + +#: ../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/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/overview.rst:169 +msgid "" +"Libraries are building blocks, not complete applications. For distributing " +"applications, there's a whole new world of technologies out there." +msgstr "" +"ライブラリは部品であって完成したアプリケーションではありません。アプリケー" +"ションを配布するには、全く新しい技術の世界が広がっています。" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "フレームワークに依存する" + +#: ../source/overview.rst:180 +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." +msgstr "" +"ウェブサイトのバックエンドやその他のネットワークサービスのような、いくつかの" +"種類の Python アプリケーションでは、その開発とパッケージングを可能にするフ" +"レームワークが存在することは極めてありふれたことです。動的ウェブのフロントエ" +"ンドやモバイルクライアントのような他の種類のアプリケーションはとても複雑で、" +"フレームワークが単に便利という以上の存在になっています。" + +#: ../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." +msgstr "" +"これら全てのケースで、フレームワークのパッケージングと配置の物語から振り返っ" +"てみるのが妥当でしょう。いくつかのフレームワークは、このガイドの残りの部分で" +"概要を描き出す技術を内包する配置システムを含んでいます。このような場合には、" +"最も簡単で最も信頼できる製品レベルの経験を積むまで、あなたのフレームワークの" +"パッケージングガイドを延期しておきたくなるでしょう。" + +#: ../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." +msgstr "" +"このようなプラットフォームやフレームワークが内部でどのように動作しているのか" +"と不思議に思うのであれば、いつでもその先の節を読めば良いでしょう。" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "サービスプラットフォーム" + +#: ../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/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/overview.rst:209 +msgid "Web browsers and mobile applications" +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/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/overview.rst:220 +msgid "`Kivy `_" +msgstr "" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "`Beeware `_" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "`Brython `_" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "インストール済みの Python に依存する" + +#: ../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/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "このモデルを支える技術:" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr ":gh:`PEX ` (Python EXecutable)" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" +":doc:`zipapp ` (依存関係を管理する助けにはならない。" +"Python 3.5+ が必要。)" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr ":gh:`shiv ` (Python 3 が必要)" + +#: ../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/overview.rst:249 +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 "" +"一般に、インストール先の環境に対する依存を減少させるとパッケージ側のサイズは" +"大きくなるので、ここで述べる解決策は、おおまかに出力となるパッケージのサイズ" +"の増える順番に整理しています。" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "個別のソフトウェア配布エコシステムに依存する" + +#: ../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/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/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "Anaconda エコシステム向けにビルドし公開するための指示書き:" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" +"`conda でライブラリやアプリケーションをビルドする `_" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" +"`Python 由来のパッケージを Anaconda へ移行する `_" + +#: ../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/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" +"`ActiveState ActivePython `_" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "`WinPython `_" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "自分の Python 実行形式を持ち込む" + +#: ../source/overview.rst:290 +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." +msgstr "" +"我々が知るところのコンピューティングは、プログラムを実行する能力として定義さ" +"れます。それぞれのオペレーティングシステムは、そのまま実行することが可能なひ" +"とつかもっと多くのプログラムフォーマットを元々サポートしています。" + +#: ../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/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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "Python フリーザの選択肢:" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" +"`pyInstaller `_ - クロスプラッ" +"トフォーム" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" +"`cx_Freeze `_ - クロスプラット" +"フォーム" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" +"`constructor `_ - コマンドラインインス" +"トーラ向け" + +#: ../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 "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" +"上記のものはほとんどが単独のユーザでの配置です。複数部分から構成されるサーバ" +"アプリケーション向けには :gh:`Chef Omnibus ` を見てください。" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "自分自身のユーザスペースを持ち込む" + +#: ../source/overview.rst:321 +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*." +msgstr "" +"オペレーティングシステム -- Linux や Mac OS や Windows を含む -- で、しばし" +"ば `オペレーティングシステムレベルの仮想化 `_ もしくは *コンテナ化* として参照され" +"る相対的に新しい手法を用いた、軽量のイメージとしてパッケージされたアプリケー" +"ションを走らせるように設定することができるものが数を増しています。" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" +"このような手法は Python 単体もしくは Python パッケージではなく OS のファイル" +"システム全体をパッケージ化するので、ほとんどの場合には Python を直接にサポー" +"トしているわけではありません。" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" +"(訳注、このような技術の) 取り入れが最も広範囲に渡るのは、この技術の発祥の地で" +"あり下に述べる技術が最もうまく動作する Linux サーバです:" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "`AppImage `_" + +#: ../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 "" +"Most desktop 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 "" +"ほとんどのデスクトップオペレーティングシステムでは、何らかの形であるオペレー" +"ティングシステム全体を内包するイメージの形にパッケージされたアプリケーション" +"を動作させることができるような、古典的な仮想化がサポートされています。このよ" +"うな仮想マシンもしくは VM を動作させることは枯れた方法論で、データセンタ環境" +"に広く普及しています。" + +#: ../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:" +msgstr "" +"複雑なアプリケーションの中にはこのパッケージング方法から利益を得るものもあり" +"ますが、このような手法はたいていの場合はデータセンタにおけるかなり大規模な配" +"置のために使用します。技術としては Python を直接サポートしているわけではな" +"く、次のものを含みます:" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "Linux 上の KVM" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "Windows 上の Hyper-V" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" +"`VHD `_ や `AMI `_ や :doc:`他のフォーマット " +"`" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" +"`OpenStack `_ - 大規模な VM サ" +"ポート機能が付いていて Python で書かれたクラウド管理システム" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "自分自身のハードウェアを持ち込む" + +#: ../source/overview.rst:362 +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." +msgstr "" +"最もすべてを包含した方法は、あなたのソフトウェアを何らかのハードウェア上にイ" +"ンストールして出荷することです。この方法では、あなたのソフトウェアのユーザは" +"電力供給しか要求されません。" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "Python アプリケーションをパッケージするのに使われる技術の概要。" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" +"Python アプリケーションをパッケージするのに使われる技術の単純化された全体像。" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "これは何..." + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "オペレーティングシステムレベルのパッケージ" + +#: ../source/overview.rst:390 +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/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" +"ほとんどの配置パイプラインでは、 OS パッケージ管理機構は全体から見ればほんの" +"一部です。" + +#: ../source/overview.rst:407 +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." +msgstr "" +":doc:`Virtualenvs ` は、複数世代の Python 向け" +"に開発をする者にとっては以前から避けられないツールであり続けてきたが、高レベ" +"ルのツール群がラップするようになったので徐々に見えなくなりつつあります。特に" +"パッケージングの観点では、共に virtualenvs を内包する形でラップしてい" +"る :doc:`the dh-virtualenv tool ` や `osnap `_ では virtualenvs はプリミティブとして使われてい" +"ます。" + +#: ../source/overview.rst:416 +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." +msgstr "" +"開発環境ではありがちですが、商用環境への配置ではインターネットから " +"virtualenv への ``python -m pip install`` を走らせることに信用をおいてはなり" +"ません。上に述べた概要には、より良い解決策がたくさんあります。" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "セキュリティ" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" +"あなたのパッケージの部品を更新することは、ここまで積み上げてきたものよりさら" +"に困難なものになるでしょう。あらゆるものがより緊密に互いに固着しているので" +"す。" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" +"例えば、仮にあなたがコンテナ型の仮想環境を配置していて、カーネルのセキュリ" +"ティ問題が発生したとすれば、アプリケーションに新たなビルドを要求することなく" +"ホスト側のカーネルが更新されるかもしれません。もしあなたが VM イメージを配置" +"しているなら、それを再ビルドする必要があるかもしれません。このような動的な挙" +"動をよりセキュアにするひとつのオプションは、以前から少々議論の的になっている" +"がまだ決着のついていない `静的リンク対動的リンク `_ ということになります。" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "まとめ" + +#: ../source/overview.rst:437 +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." +msgstr "" +"Python におけるパッケージングは、凸凹道を車で行くようなもので苦労が多いという" +"評判も少しあります。このような感想は、ほとんどの場合は Python が多用途に使え" +"ることの裏返しです。それぞれのパッケージング方法の間にある自然な境界線を理解" +"しさえすれば、さまざまに異なる風景が、もっともバランスが取れていて自由度の高" +"い言語を使うということのために Python プログラマが支払う小さな代償であること" +"に気づくことでしょう。" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "バイナリ配布物のフォーマット" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" +"このページでは、Python パッケージのバイナリ配布物フォーマット、これは wheel " +"フォーマットとも呼ばれているものですが、これについて仕様を記述します。" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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/binary-distribution-format.rst:22 +msgid "Details" +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/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "Wheel によるインストールは、概念上、ふたつの段階から構成されています:" + +#: ../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 "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" +"インストーラが Wheel のバージョンと互換であることを確認します。マイナーバー" +"ジョンが大きければ警告し、メジャーバージョンが大きければ処理を中断します。" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" +"もし、 Root-Is-Purelib == 'true' であれば、アーカイブを purelib (site-" +"packages) へアンパックします。" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" +"そうでなければ、アーカイブを platlib (site-packages) へアンパックします。" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "広げる。" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" +"アンパックされたアーカイブは、 ``distribution-1.0.dist-info/`` と (データ部分" +"があれば) ``distribution-1.0.data/`` を含んでいます。" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" +"``distribution-1.0.data/`` の下の全てのサブツリーを、その目的地となるディレク" +"トリパスに移動しましょう。 ``distribution-1.0.data/(purelib|platlib|headers|" +"scripts|data)`` のような ``distribution-1.0.data/`` の下のサブディレクトリ" +"は、それぞれ、目的地となるディレクトリの辞書のキーになっています。このような" +"サブディレクトリ群は、 :ref:`sysconfig によって定義されるインストールパス群 " +"` です。" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" +"もし該当するならば、 ``#!python`` から始まるスクリプト群が適切なインタープリ" +"タを指し示すように更新します。" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" +"``distribution-1.0.dist-info/RECORD`` をインストール先のディレクトリパスに更" +"新します。" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "空の ``distribution-1.0.data`` ディレクトリを削除します。" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" +"インストールされた .py のファイルを全て .pyc にコンパイルします。 (アンインス" +"トーラは、 RECORD で言及されていなくても .pyc ファイルを削除できるほどに賢く" +"あるべきです。)" + +#: ../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 "" +"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 "" +"wheel では、スクリプトは ``{distribution}-{version}.data/scripts/`` にパッ" +"ケージされます。 ``scripts/`` ディレクトリにあるファイルの先頭行が正確に " +"``b'#!python'`` で始まっている場合には、正確なインタープリタを指し示すように" +"書き換えられます。アーカイブが Windows で作成されていれば、 Unix でのインス" +"トーラがこのようなファイルに +x ビットを追加設定する必要があるでしょう。" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" +"``b'#!pythonw'`` と書く慣習も許容されています。 ``b'#!pythonw'`` というのはコ" +"ンソール版ではなくて GUI 版のスクリプトであることを示します。" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "スクリプトラッパを生成します。" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" +"wheel では、 Unix システム上でパッケージされたスクリプトには .exe ラッパーが" +"随伴していないことが普通でしょう。 Windows インストーラは、インストールする際" +"にそれらを追加したくなるかもしれません。" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "推奨されるアーカイバの機能" + +#: ../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 "" +"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 "" +"アーカイバには、 ``.dist-info`` ファイルをアーカイブの物理的な末尾に置くこと" +"が推奨されています。こうすることで、アーカイブ全体を書き換えなくてもメタデー" +"タを修正することができる点を含む、 ZIP のいくつかの潜在的に興味深いトリックを" +"使うことができるようになります。" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "ファイルフォーマット" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "ファイル名の慣習" + +#: ../source/specifications/binary-distribution-format.rst:92 +msgid "" +"The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" +"{abi tag}-{platform tag}.whl``." +msgstr "" +"wheel のファイル名は(訳注、慣習として) ``{配布物}-{バージョン}(-{ビルドタ" +"グ})?-{python タグ}-{abi タグ}-{プラットフォームタグ}.whl <{distribution}-" +"{version}(-{build tag})?-{python tag}-{abi tag}-{platform tag}.whl>`` です。" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "distribution" +msgstr "ディストリビューション" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "配布物の名前、例えば 'django' や 'pyramid' 。" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../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 "" +"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 "" +"省略可能なビルドナンバー。数字で始まらなければなりません。ふたつの wheel ファ" +"イルのファイル名がこの部分を除いて (すなわち名称やバージョンやその他のタグ" +"が) 同一であった場合のタイブレーカ (訳注、いずれかに決めるための方法) として" +"働きます。指定されていれば先頭の数字を ``int`` として解釈して第１要素とし残り" +"を ``str`` として解釈して第２要素とするような要素数が２個のタプルとして解釈さ" +"れ、指定されていない場合には空欄のタプルとして解釈されます。" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" +"ビルド番号に係るよくあるユースケースは、CPython のリリース前のバージョンを" +"使って manylinux で配布物をビルドしている場合のように、ビルド環境に変化があっ" +"たためにバイナリ配布物を再ビルドする時です。" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" +"ビルド番号は、配布物のバージョンの一部ではなく、従って外部からの、特に " +"Python エコシステムのツール類や標準類の外側からの参照は困難です。配布物が外部" +"からの参照を必要とするようなケースとしては、セキュリティ上の脆弱性を解決しよ" +"うとする場合がよくあるケースです。" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" +"この制約のゆえに、外部から参照される必要がある新たな配布物は、新しい配布物を" +"ビルドする際にビルド番号を使う **べきではありません** 。そのような場合には、" +"代わりに **新しい配布物バージョン** が作成されるべきです。" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "言語の実装とバージョンタグ" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "例えば、 'py27' ・ 'py2' ・ 'py3' 。" + +#: ../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/binary-distribution-format.rst:135 +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." +msgstr "" +"例えば、 ``distribution-1.0.1-py27-none-any.whl`` とは、 'distribution' と呼" +"ばれるパッケージの最初のビルドであって、 Python 2.7 (任意の Python 2.7 実装) " +"で動作し、 ABI を持たず (即ち純 Python) 、任意の CPU アーキテクチャで動作する" +"ということです。" + +#: ../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/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "エスケープとユニコード" + +#: ../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/binary-distribution-format.rst:150 +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." +msgstr "" +"配布物の名前の部分では、 ``-_.`` (HYPHEN-MINUS ・ LOW LINE ・ FULL STOP) の文" +"字は、すべて ``_`` (LOW LINE) で置き換えられるべきで、かつ、大文字はすべて対" +"応する小文字に置き換えられるべきです。これは、通常の :ref:`名前の正規化 " +"` の後に ``-`` を ``_`` で置き換えるのと同じです。 wheel " +"ファイルを入力とするツールは、 ``.`` (FULL STOP) や大文字を受け入れる準備がで" +"きていなければなりませんが、しかし、それはこの仕様の初期のバージョンで許され" +"ていたからです。" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" +"バージョン番号は、 :ref:`バージョン指定子仕様 ` に従って" +"正規化されなければなりません。正規化済みのバージョン番号は ``-`` を含んでいて" +"はなりません。" + +#: ../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: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/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" +"アーカイブのファイル名は Unicode です。いくつかのツールでは非 ASCII 文字の" +"ファイル名をサポートするように更新されるまでに幾らかの時間がかかるかもしれま" +"せんが、しかし、この仕様ではサポートされているのです。" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" +"アーカイブの *中にある* ファイルのファイル名は、 UTF-8 でエンコードされていま" +"す。 ZIP クライアントのいくつかは共通して UTF-8 のファイル名を正常に表示しま" +"せんが、このエンコーディングは ZIP の仕様でも Python の ``zipfile`` の仕様で" +"も、共にサポートされています。" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "ファイルの内容" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" +"{distribution} の部分を例えば ``beaglevote`` のようなパッケージ" +"の :ref:`normalized name ` で置き換え、 {version} を例え" +"ば ``1.0.0`` のような :ref:`normalized version ` で置き換えた時 (両方のフィールドでダッシュ文字/``-`` をアン" +"ダースコア文字/``_`` で置換) 、 wheel ファイルの内容は、以下の要素から構成さ" +"れます:" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" +"アーカイブのルートディレクトリに当たる ``/`` は、``WHEEL`` で指定されている通" +"り ``purelib`` または ``platlib`` にインストールされるファイルをすべて含んで" +"います。通常は、 ``purelib`` や ``platlib`` はいずれも ``site-packages`` で" +"す。" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "``{distribution}-{version}.dist-info/`` はメタデータを含んでいます。" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" +":file:`{distribution}-{version}.dist-info/licenses/` はライセンスファイル群を" +"含んでいます。" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" +"``{distribution}-{version}.data/`` は、すでにカバーされているものは別として、" +"サブディレクトリ名がインストールパスの辞書への (例えば、 ``data``, " +"``scripts``, ``headers``, ``purelib``, ``platlib`` のような) 指示子になってい" +"るような、空ではないそれぞれのインストールスキームに対応したディレクトリを含" +"みます。" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" +"Python スクリプトは ``scripts`` ディレクトリに置かなければならず、また、イン" +"ストール時のスクリプトラッパの生成や ``#!python`` 書き換えといった利点を活用" +"するために、正確に ``b'#!python'`` で始まっていなければなりません。 " +"``scripts`` ディレクトリには、通常ファイルしか置けません。" + +#: ../source/specifications/binary-distribution-format.rst:197 +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/binary-distribution-format.rst:199 +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/binary-distribution-format.rst:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "``Wheel-Version`` は、Wheel の仕様のバージョン番号です。" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" +"``Generator`` は、そのアーカイブを作成したソフトウェアの名前で、バージョン番" +"号を付加しても構いません。" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" +"``Root-Is-Purelib`` は、アーカイブの最上位のディレクトリが pure lib へインス" +"トールされるべきものであれば true で、そうでなければ platlib へインストールさ" +"れます。" + +#: ../source/specifications/binary-distribution-format.rst:215 +msgid "" +"``Tag`` is the wheel's expanded compatibility tags; in the example the " +"filename would contain ``py2.py3-none-any``." +msgstr "" +"``Tag`` は、 wheel の拡張互換性タグで、例の中ではファイル名の ``py2.py3-none-" +"any`` の部分です。" + +#: ../source/specifications/binary-distribution-format.rst:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" +"``Build`` は、ビルドナンバーで、もしビルドナンバーがなければ省略されます。" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" +"wheel インストーラは、もし自身がサポートしているものより Wheel-Version が大き" +"ければ警告するべきですし、 Wheel-Version のメジャーバージョンがサポートしてい" +"るものより大きい場合にはフェイルするべきです。" + +#: ../source/specifications/binary-distribution-format.rst:221 +msgid "" +"Wheel, being an installation format that is intended to work across multiple " +"versions of Python, does not generally include .pyc files." +msgstr "" +"Wheel は複数のバージョンの Python を跨いでも動作するように意図されたインス" +"トール用のフォーマットですが、通常は .pyc ファイルを含みません。" + +#: ../source/specifications/binary-distribution-format.rst:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "Wheel は、 setup.py ないし setup.cfg を含みません。" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" +"このバージョンの wheel 仕様は、distutils のインストール方法論に基づいていて、" +"ファイルを他の場所にインストールする方法については定義していません。既存の " +"wininst や egg バイナリフォーマットが提供する機能の上位互換のレイアウトを提案" +"します。" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr ".dist-info ディレクトリ" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" +"Wheel の .dist-info ディレクトリは、最低限でも METADATA ・ WHEEL ・RECORD を" +"含みます。" + +#: ../source/specifications/binary-distribution-format.rst:236 +msgid "" +"METADATA is the package metadata, the same format as PKG-INFO as found at " +"the root of sdists." +msgstr "" +"METADATA はパッケージのメタデータで、 sdists のルートディレクトリにある PKG-" +"INFO と同じフォーマットで記述されます。" + +#: ../source/specifications/binary-distribution-format.rst:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" +"WHEEL は、パッケージをビルドする部分に特化した wheel のメタデータです。" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" +"RECORD は、 wheel に含まれる (ほとんど) 全てのファイルとそのセキュアなハッ" +"シュ値のリストです。 PEP 376 とは異なり、自分自身のハッシュ値を内包することは" +"不可能な RECORD を除く個々のファイルのハッシュ値が含まれていなければなりませ" +"ん。ハッシュ計算のアルゴリズムは sha256 以上でなければならず、特に md5 と" +"sha1 は許されません。" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "PEP 376 の INSTALLER と REQUESTED はアーカイブに含まれません。" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" +"RECORD.jws および RECORD.p7s は非推奨になりました。これらがまだ使われている場" +"所では、 RECORD.jws と RECORD.p7s のいずれも RECORD の中で言及してはなりませ" +"ん。ビルドバックエンドとその他のツール類はもはやこれらを wheel ファイルに追加" +"してはならず、 インストーラはこれらのファイルがまだその一部をなすような " +"wheel ファイルも存在するということを認識しておくべきです。" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" +"展開中に wheel インストーラは RECORD 内のハッシュ値と実際のファイルの内容 (の" +"ハッシュ値) をすべて検証します。 RECORD ・ RECORD.jws ・ RECORD.p7s による検" +"証とは別に、アーカイブの中のいずれかのファイルが RECORD にリストされていない" +"か、または、ハッシュ値が正しくない時には、インストールがフェイルするでしょ" +"う。" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr ":file:`.dist-info/` 内のサブディレクトリ群" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" +":file:`.dist-info/` の下のサブディレクトリは、将来の使用のために予約されてい" +"ます。 :file:`.dist-info/` の下のサブディレクトリ名で以下のものが特定の用途の" +"ために予約されています:" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "Subdirectory name" +msgstr "サブディレクトリ名" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "PEP / Standard" + +#: ../source/specifications/binary-distribution-format.rst:264 +msgid "``licenses``" +msgstr "``licenses``" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr ":pep:`639`" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "``license_files``" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "``LICENSES``" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "`REUSE ライセンシングフレームワーク `__" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "``sboms``" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr ":pep:`770`" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr ":file:`.dist-info/licenses/` ディレクトリ" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" +"メタデータバージョンが 2.4 かそれ以上で、一つないしそれ以上の ``License-" +"File`` フィールドが指定された場合は、 :file:`.dist-info/` ディレクトリに" +"は :file:`licenses/` サブディレクトリがなければならず、そこに" +"は :file:`METADATA` ファイル内の ``License-File`` フィールド" +"に :file:`licenses/` ディレクトリからの相対パスの形で列挙されたファイル群を含" +"んでいなければなりません。" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "The :file:`.dist-info/sboms/` ディレクトリ" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" +":file:`.dist-info/sboms/` ディレクトリにあるすべてのファイルは、配布物アーカ" +"イブ内に含まれるソフトウェアを記述するソフトウェア部品表 (SBOM) のファイルでなければなりません。" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr ".data ディレクトリ" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" +"site-packages 内に通常通りにインストールされなかったファイルはどれで" +"も、.dist-info ディレクトリと同様に命名されるが .data/ 拡張子をつけられ" +"て .data ディレクトリに行きます::" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" +".data ディレクトリでは、配布物からのスクリプト・ヘッダー・説明文書などをサブ" +"ディレクトリに収めています。インストール中に、これらのサブディレクトリの内容" +"を行き先となるパスへ動かします。" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "FAQ" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" +"Wheel は .data ディレクトリを定義します。すべてのデータをそこに入れるべきで" +"しょうか？" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" +"この仕様では、あなたがあなたのソースコードをどのように組織立てて置くべきかに" +"ついては特に意見を表明していません。 .data ディレクトリは、 ``site-" +"packages`` 内や PYTHONPATH 内に通常ならインストールされない全てのファイルを置" +"く場所というだけのことです。換言すれば、 *そのような* ファイル群が通常なら " +"*wheel の* ``.data`` ディレクトリに置く形で配布されない時でさえも、 " +"``pkgutil.get_data(package, resource)`` を使い続けても構わないのです。" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "\"pure lib\" と \"plat lib\" って、どう扱えばいいの？" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" +"Wheel は \"purelib\" と \"platlib\" を区別して扱いますが、これらはプラット" +"フォームによっては大きな違いがあります。例えば、 Fedora では純 Python のパッ" +"ケージを '/usr/lib/pythonX.Y/site-packages' にインストールし、プラットフォー" +"ムに依存しないパッケージを '/usr/lib64/pythonX.Y/site-packages' にインストー" +"ルします。" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" +"``{name}-{version}.data/purelib`` 内の全てのファイルについて \"Root-Is-" +"Purelib: false\" という設定になっている wheel ファイルは、同じファイルがルー" +"トディレクトリ内にあって \"Root-Is-Purelib: true\" になっている wheel ファイ" +"ルと相同であり、 \"purelib\" と \"platlib\" の両カテゴリにファイル群が存在す" +"ることには問題がありません。" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" +"実際のところ、 wheel は、それが純 Python なのかそうでないのかによって " +"\"purelib\" または \"platlib\" のいずれか一方しか持たず、 \"Root-Is-" +"purelib\" を適切に設定しつつファイル群をルートディレクトリに置くべきです。" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" +"Python のソースコードを wheel ファイルから直接にインポートすることはできます" +"か？" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" +"技術的な話としては、単純に展開するだけでインストールできる機能と " +"``zipimport`` と互換性のあるアーカイブフォーマットの両方をサポートしているの" +"で、一部の wheel ファイルは ``sys.path`` に直接に置くことを *サポートしていま" +"す* 。しかし、このような動作はフォーマット設計の自然な結果とはいうものの、実" +"際にはこれに依存することは一般的には推奨されていません。" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" +"第一に、wheel は一義的に配布物のフォーマットとして *設計されている* ので、イ" +"ンストールの段階を省略するということは、完全なインストールがなされているもの" +"と仮定している機能 (例えば、正当性監査やセキュリティアップデートのために正し" +"く追跡することができるひとつの方法であるところの ``pip`` や ``virtualenv`` の" +"ような標準ツールを使った依存関係の捕捉や管理の機能、あるいは、ヘッダファイル" +"を適切な場所に公開することによって C 言語拡張をビルドする標準的な機構を完全に" +"統合する機能) への信頼を故意に避けることになります。" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" +"第二に、 Python のソフトウェアの中には zip アーカイブから直接に動作させること" +"をサポートするように書かれているものもありますが、やはり完全にインストールさ" +"れることを前提にして書かれたソースコードが今も普通です。 zip アーカイブからソ" +"フトウェアを走らせようと試みてこの仮定を崩すと、 (とりわけ失敗動作がサード" +"パーティのライブラリで起きる場合には) しばしば失敗動作がわかりにくく原因究明" +"が困難になるでしょう。この問題の最もありがちなふたつの根源は、 C 言語拡張を " +"zip アーカイブからインポートすることが CPython では *サポートされていない* こ" +"と (というのは、どんなプラットフォームの動的ローディング機構でもこのような動" +"作が直接にはサポートされていないから) 、および、 zip アーカイブから動作する際" +"には ``__file__`` 属性がもはや普通のファイルシステム上のファイルパスを参照し" +"ておらず、 zip アーカイブのファイルシステム上の置き場所のパスとアーカイブ内の" +"モジュールへの相対パスの両方を含んだ連結パスになることです。ソフトウェア内で" +"は抽象化された資源への API 群を正しく扱えたとしても、外部の部品とのインタフェ" +"イスは依然として実際にディスク上に存在するファイルがないと動作できないかもし" +"れません。" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" +"メタクラスと同様に、モンキーパッチングとメタパスからのインポートは、この機能" +"を使う利点をあなたが本当に必要としていると確信しているのでなければ、おそらく" +"あなたはこの機能を使う必要がないと思われます。兎にも角にもこれを使う *意思を" +"固めた* のであれば、 (訳注、この機能を使った時に生じた) ある動作不良を真性の" +"バグであると認めてもらう前に、多くのプロジェクトではそれを完全インストールの" +"状態で再現するように要求されるであろうということを認識しておいてください。" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "歴史" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "2013年2月: :pep:`427` を通じてこの仕様書が承認されました。" + +#: ../source/specifications/binary-distribution-format.rst:383 +msgid "" +"February 2021: The rules on escaping in wheel filenames were revised, to " +"bring them into line with what popular tools actually do." +msgstr "" +"2021年2月: 他の普及しているツールが実際にやるのと同じやり方に合わせて、 " +"wheel のファイル名におけるエスケーピングの規則が修正されました。" + +#: ../source/specifications/binary-distribution-format.rst:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" +"2024年12月: ``scripts`` フォルダには、通常ファイルだけが含まれているべきであ" +"ると明確化された (このフォルダ内でシンボリックリンクやサブディレクトリに遭遇" +"した場合に消費する側のツール類がどのように振る舞うことを期待されているかにつ" +"いての公式には定義されていないので、ツールが異なれば動作が異なるかもしれませ" +"ん) 。" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" +"2022年12月: :pep:`639` を通じて、 :file:`.dist-info/licenses/` ディレクトリが" +"仕様化された。" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" +"2025年1月: 名称とバージョン番号が ``.dist-info`` と ``.data`` のディレクトリ" +"のために標準化される必要があると明確化された。" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" +"2026年1月: :pep:`815` で RECORD.jws および RECORD.p7s が非推奨になりました。" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "補遺" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "urlsafe-base64-nopad の実装の例::" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "v1.0" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr ":file:`build-details.json`" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" +"``build-details.json`` ファイルは、バージョン番号や拡張 ABI の詳細その他 " +"Python をビルドすることに特に関係する情報のような Python のインストール関係の" +"ビルドに特化した情報を提供する標準化されたファイルフォーマットです。" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" +"Python 3.14 以降、 ``build-details.json`` ファイルは、プラットフォーム非依存" +"の標準ライブラリディレクトリ (``stdlib`` 、例えば ``/usr/lib/" +"python3.14.build-details.json``) にインストールされます。" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" +"その仕様については、 :ref:`最新版 ` を参照してください。" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "例" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "Changelog" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "仕様" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr ":ref:`build-details-v1.0`" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "スキーマ" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr ":pep:`739` で導入された、当初のバージョン。" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "``build-details.json`` v1.0" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" +"*build-details.json -- Python インストール状態のビルドの詳細を伴った静的な記" +"述ファイル*" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "型" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*object*" +msgstr "*オブジェクト*" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "プロパティ" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "**schema\\_version**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Schema version." +msgstr "スキーマバージョン。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" +"これは、```` と ```` がパディングされていない番号でバージョン番" +"号の **メジャー** 部分と **マイナー** 部分を表現するものとして、 ``." +"`` フォーマットに続く文字列です。バージョン番号は、バージョン文字列を" +"10進数の数として解釈することによって、算術的に比較しても構いません。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" +"この仕様のバージョン番号にとって、この値は定数であって ``1.0`` で **なければ" +"なりません** 。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" +"スキーマの将来のバージョン番号は、より大きなバージョン番号を使わなければ **な" +"りません** 。このスキーマの将来のバージョン番号は、その仕様が後方互換性を尊重" +"しているのでなければ、他のスキーマバージョンと同じ **メジャー** バージョン部" +"分を使っては **なりません** -- 現在の仕様のどの一部分であってもデータの解釈が" +"異なる意味になるようなやり方や、追加のプロパティ (``additionalProperties`` に" +"よって引き起こされたエラー) を例外として新仕様の下で正当なデータが旧仕様の下" +"では不当なものになるようなやり方で、変更したり拡張したりすることはできませ" +"ん。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "*文字列 *" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "定数 " + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "1.0" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "**base\\_prefix**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "Python インストールのベースプレフィクス。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "絶対パスか、そのファイルの一からの相対パスのいずれか。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "examples" +msgstr "例" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "/usr" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "../.." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "base\\_interpreter" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "ベースシステムにインストールされた Python インタープリタへのパス。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "絶対パスか、 ``base_prefix`` に対する相対パス。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" +"実行可能なインタープリタがインストールされているなら、このフィールドが **存在" +"しなければなりません** 。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "/usr/bin/python" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "bin/python" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "**platform**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "システムのプラットフォーム文字列。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" +"このフィールドは、 ``sysconfig.get_platform()`` と **同等であるべきです** 。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "linux-x86\\_64" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "**language**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "Python 言語の仕様に関係した詳細を含むオブジェクト。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**version**" +msgstr "**version**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" +"Python 言語のバージョンを文字列で表現したもの -- *メジャー* 部分と *マイナー" +"* 部分だけから構成されるバージョン文字列。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" +"このフィールドは、 ``sysconfig.get_python_version()`` と同等である **べき** " +"です。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "3.14" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "version\\_info" +msgstr "version\\_info" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr ":py:data:`sys.version_info` のフォーマットのオブジェクト。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "この節は、 :py:data:`sys.version_info` と同等である **べき** です。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "メジャー" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "3" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "マイナー" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "14" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "マイクロ" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "1" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "リリースレベル" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "ファイナル" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "シリアル" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "0" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "**メジャー**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*number*" +msgstr "*数*" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "**マイナー**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "**マイクロ**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "**リリースレベル**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "enum" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "アルファ・ベータ・候補・最終" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "**シリアル**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "additionalProperties" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "偽" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**implementation**" +msgstr "**実装**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "Python の実装に関係した詳細を含むオブジェクト。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" +"この節は、 :py:data:`sys.implementation` と同等である **べき** です。それは、" +"要求されたキー群に加えて実装特有のキー群も存在することが可能で、しかし、プレ" +"フィクスとしてアンダースコアがついていなければならないという、 PEP 421 で定義" +"された仕様に従います。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "**名称**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "Python 実装の名前を小文字で。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "cpython" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "pypy" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" +"実装のバージョン番号を含んだ、 :py:data:`sys.version_info` のフォーマットのオ" +"ブジェクト。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "7" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "16" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "True" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "abi" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "ABI に関連した詳細を含むオブジェクト。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**flags**" +msgstr "**flags**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "拡張のサフィックスを計算するために使われた、ビルド設定のフラグ。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" +"フラグは、拡張のサフィックスに出現する順序に従って定義されなければ **なりませ" +"ん** 。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "*array*" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "t" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "d" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "extension\\_suffix" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" +"現在の実装のバージョン番号に対してビルドされた拡張に使われるサフィックス。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" +"Python 実装が拡張をサポートするのであれば、このフィールドは存在してい **なけ" +"ればならず** 、そうでないならこのエントリは存在しないことでしょう。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr ".cpython-314-x86\\_64-linux-gnu.so" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "stable\\_abi\\_suffix" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "安定飯の ABI に対してビルドされた拡張に使われるサフィックス。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" +"Python 実装が安定版の ABI 拡張のサフィックスを持つなら、このフィールドは存在" +"していなければ **ならず** 、そうでなければこのエントリは欠けていることでしょ" +"う。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr ".abi3.so" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "suffixes" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "型ごとにグループ化された、正当なモジュールサフィックス群。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" +"インストール済 Python が外部ファイルのインポートをサポートしているなら、この" +"セクションは存在していなければ **ならず** 、また、それは、 " +"``importlib.machinery.*_SUFFIXES`` アトリビュートと同等のものである **べき** " +"です。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" +"さらに、 Python 実装が ``importlib.machinery`` モジュールに列挙されたもの以外" +"の拡張の種類を提供しているなら、サブセクションを追加しても **構いません** 。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "source" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr ".py" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "bytecode" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr ".pyc" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "optimized_bytecode" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "debug_bytecode" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extensions" +msgstr "extensions" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr ".cpython-313-x86\\_64-linux-gnu.so" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr ".so" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "libpython" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "``libpython`` ライブラリに関係する詳細を含んだオブジェクト。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" +"インストール済 Python が ``libpython`` ライブラリを提供しているなら、このセク" +"ションは存在していなければ **なりません** し、そうでなければこのセクションは" +"欠けていることでしょう。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "dynamic" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" +"ダイナミックな (訳註: 共有ライブラリのことか) ``libpython`` ライブラリへのパ" +"ス。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" +"インストール済 Python が動的な ``libpython`` ライブラリを提供しているなら、こ" +"のフィールドは存在していなくては **ならず** 、そうでなければこのエントリは欠" +"けていることでしょう。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "/usr/lib/libpython3.14.so.1.0" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "lib/libpython3.14.so.1.0" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "dynamic\\_stableabi" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "安定版の ABI のための動的な ``libpython`` ライブラリへのパス。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" +"インストール済 Python が安定版の ABI をターゲットとした動的な ``libpython`` " +"ライブラリを提供しているなら、このフィールドは存在していなければ **ならず" +"** 、そうでなければこのエントリは欠けていることでしょう。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" +"このキーが存在するなら、 ``dynamic`` もまた設定されていなければ **なりません" +"** 。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "/usr/lib/libpython3.so" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "lib/libpython3.so" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "static" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "静的な ``libpython`` ライブラリへのパス。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" +"インストール済 Python が静的な ``libpython`` ライブラリを提供しているなら、こ" +"のフィールドは存在していなければ **ならず** 、そうでなければ欠けていることで" +"しょう。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "link\\_extensions" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" +"拡張は、動的な ``libpython`` がリンクするようにビルドされているべきですか？" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "*boolean*" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "c\\_api" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "Python C API に関連した詳細を含んだオブジェクト。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" +"Python 実装が C API を提供しているなら、このフィールドは存在していなければ **" +"ならず** 、そうでなければ欠けていることでしょう。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**headers**" +msgstr "**headers**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "C API のヘッダファイル群へのパス。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "/usr/include/python3.14" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "include/python3.14" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "pkgconfig\\_path" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "pkg-config 定義ファイル群へのパス。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" +"Python 実装が pkg-config 定義ファイル群を提供しているなら、このフィールドは存" +"在していなければ **ならず** 、そうでなければ欠けていることでしょう。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "/usr/lib/pkgconfig" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "lib/pkgconfig" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "arbitrary\\_data" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "余分で任意のデータを含むオブジェクト。" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" +"これは、この仕様でカバーされなかったすべての適切なデータを含めるための脱出用" +"ハッチ として使われることを意図しています。このセクションにど" +"んなデータを提供するかは実装の側が選択してもかまいません。" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "コアとなるメタデータの仕様" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "このページは、 2025年9月に承認されたバージョン 2.5 を記述しています。" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" +"この後の仕様の中で定義されるフィールドは、正当かつ完全であって、変更の可能性" +"がないものと見做されるべきです。必須のフィールドは以下の通り:" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "``Name``" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "これら以外のすべてのフィールドは必須のものではありません。" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" +"(:doc:`wheels ` および :doc:`インストール済みのプ" +"ロジェクト ` の両文書に含まれる) メタデータのた" +"めの標準的なファイルフォーマットは、電子メールのヘッダーのフォーマットに基い" +"ています。しかしながら、電子メールのフォーマットは何度か修正が入っています" +"が、正確にはどの電子メールの RFC がパッケージングのメタデータに適用されるのか" +"については指定がありません。精密な定義が欠落しているので、標準ライブラリ" +"の :mod:`python:email.parser` モジュール" +"が :data:`~.python:email.policy.compat32` のポリシーを用いて読み込むことがで" +"きるものを実務上の標準として設定しています。" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" +"メタデータをバイト列 (例えばファイルに保存するために) にシリアル化する際には" +"いつでも、文字列を UTF-8 エンコーディングを用いてシリアル化しなければなりませ" +"ん。" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" +":pep:`566` でメタデータを JSON 互換の辞書型に変換する一つの方法を定義していま" +"すが、標準の交換フォーマットとしてはまだ使われていません。既に何年間も使われ" +"てきた既存のパッケージと共に動作するツールが必要なので、新しいフォーマットに" +"移行することは困難なのです。" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" +"*古い形式のメタデータを翻訳する:* :pep:`566` では、バージョン指定子フィールド" +"のフォーマット仕様がよく用いられている公開ツール群で使われる構文を受け入れる " +"(正確にはバージョン指定子が丸括弧で囲まれていなければならないという要求事項を" +"削除することによって) ようにと緩められました。メタデータを使う側としては、メ" +"タデータファイルが名ばかりのものとなっている 2.1 よりも前のバージョンであって" +"さえも、もっと寛容なフォーマット規則を使いたいかもしれません。" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "Metadata-Version" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" +"ファイルフォーマットのバージョン番号; 合法な値は次のとおり\"1.0\", \"1.1\", " +"\"1.2\", \"2.1\", \"2.2\", \"2.3\", \"2.4\" および \"2.5\"。" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" +"メタデータを処理する自動化ツールは、 ``metadata-version`` が自身のサポートす" +"る最大のものより大きい場合には警告を行うべきであり、かつ、 ``metadata-" +"version`` が自身のサポートする最大のメジャーバージョンより大きいメジャーバー" +"ジョンを持つ場合には異常終了しなければなりません (:ref:`バージョン指定子仕様 " +"` に記述されている通り、メジャーバージョンとはバージョン" +"のうち最初のドットよりも前の部分です) 。" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" +"より広く互換性を保つために、ビルドツールは、必要なフィールドをすべて含む前提" +"で最も古いバージョンのメタデータ仕様を使って配布物のメタデータを生成するとい" +"う選択を行なっても構いません。" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "例::" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" +":ref:`名称のフォーマット ` から採用したフォーマットに対する制限" +"を追加した。" + +#: ../source/specifications/core-metadata.rst:80 +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 "" +"配布物の名称。name フィールドは配布物の最も基本的な識別子です。 :ref:`名称" +"フォーマット仕様 ` を満たしていなければなりません。" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" +"比較の目的のためにも、名前は比較の前に :ref:`正規化 ` さ" +"れているべきです。" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" +"配布物のバージョン番号を格納する文字列。このフィールドは :ref:`バージョン指定" +"子仕様 ` で規定されるフォーマットでなければなりません。" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "Dyanamic (複数回の使用可)" + +#: ../source/specifications/core-metadata.rst:113 +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:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" +"ソースコード配布物のメタデータ中に見つかった場合には、以下の規則を適用します:" + +#: ../source/specifications/core-metadata.rst:120 +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:124 +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 "" +"フィールドが ``Dynamic`` とマークされている場合、 (ひとつも存在しない場合も含" +"めて) sdist からビルドされた wheel 内のどんな正当な値を取っても構いません。" + +#: ../source/specifications/core-metadata.rst:127 +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:131 +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:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" +"事前ビルド済の wheel を持っているなら、一部の wheel は sdist から直接にビルド" +"されるわけではなく、既存の wheel (例えば、 ``auditwheel`` ツールはこれをやり" +"ますし、 PyPI 用に wheel をビルドするときには一般的に使われます)から変換して" +"作られるので、 ``動的 `` とマークされていないフィールドが他の wheel " +"でも同じ値を持つであろうということを、特に覚えておいてください。このような変" +"換には、 (動的ではないメタデータであってさえも) メタデータの変更をも含む *か" +"もしれません* 。同様に、 sdis と、自分でその sdist から ビルドしたわけではな" +"い wheel が手元にある時、 ``動的`` とマークされていないフィールドであってさえ" +"も、 wheel のメタデータが sdist のそれと一致すると仮定することはできません。" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "``Dynamic`` の詳細かつ完全な意味は :pep:`643` に記述されています。" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "Platform (複数回の使用可)" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" +"Platform の仕様は、その配布物がサポートするオペレーティングシステムを記述した" +"もので、 \"Operating System\" Trove 分類子には記載されていないもの。後述の " +"\"分類子 \" を見てください。" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "例 ::" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "Supported-Platform (複数回の使用可)" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" +"PKG-INFO ファイルを含むバイナリ配布物は、内包するメタデータの中の Supported-" +"Platform フィールドを使って当該バイナリ配布物がどの OS や CPU 向けにコンパイ" +"ルされたかを指定することになるでしょう。 Supported-Platform フィールドのセマ" +"ンティクスは PEP には定義されたものがありません。" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "Summary" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "その配布物が何をするものかを１行で記述した要約。" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "このフィールドの代わりにメッセージ本体で指定しても構いません。" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" +"配布物に関する長めの説明文で、いくつかの段落に渡ってもかまいません。取扱説明" +"書並みの記述をするべきではありませんが、メタデータを扱うソフトウェアはこの" +"フィールドに最大長さがあるものと仮定すべきではありません。" + +#: ../source/specifications/core-metadata.rst:217 +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/core-metadata.rst:223 +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]_." +msgstr "" +"空行および RFC 822 に従う字下げをサポートするために、すべての CRLF 文字には７" +"個の空白文字と１個のパイプ文字 (\"|\") がこの順に並ぶ文字列が後続しなければな" +"りません。その結果として、Description フィールドが RFC 822 構文解析器 [2]_ で" +"解析可能な形の改行可能なフィールドにエンコードされます。" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" +"このエンコーディングが意味するところは、その折り畳まれたフィールドをRFC822 読" +"み取り器で読み取る時には、CRLF と７個の空白文字とそれに引き続くパイプ文字が出" +"現するたびにそれを単独の CRLF に置き換えなければならないということです。" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" +"代替策として、配布物に関する説明を代わりにメッセージボディに書く (つまり、字" +"下げやその他の特別なフォーマットを使わずに、ヘッダの並びの後の完全な空行に続" +"けて書く) こともできます。" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "Description-Content-Type" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" +"配布物の説明で使われるマークアップ構文 (もしあれば) を述べる文字列で、ツール" +"の側が頭の良いやり方で説明を表示することができます。" + +#: ../source/specifications/core-metadata.rst:260 +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/core-metadata.rst:273 +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:" +msgstr "" +"このフィールドのフォーマットは HTTP (すなわち `RFC 1341 `_) における ``Content-Type`` ヘッダの" +"それと同じです。端的に言えば、これは ``type/subtype`` の部分を持っていて、オ" +"プションとしていくつかのパラメータを取ることができるというものです:" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "フォーマット ::" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "``type/subtype`` 部分はいくつかの正当な値を取ります:" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "``text/plain``" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "``text/x-rst``" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "``text/markdown``" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" +"``charset`` パラメータは、description のキャラクターのエンコーディングを指定" +"するために使われます。唯一の正当な値は ``UTF-8`` です。省略時には ``UTF-8`` " +"であるものと仮定します。" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" +"サブタイプを選択するために他のパラメータが指定される場合もあります。例えば、 " +"``markdown`` サブタイプを指定する際に、使われている Markdown の異種 (指定がな" +"い場合にはデフォルトでは ``GFM``) を指定することができるオプションの " +"``variant`` パラメータが存在します。現時点ではふたつの異種が認識されます:" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "``GFM`` すなわち :rfc:`Github-flavored Markdown <7764#section-3.2>`" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "``CommonMark`` すなわち :rfc:`CommonMark <7764#section-3.5>`" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" +"``Description-Content-Type`` が指定されていない場合には、アプリケーションとし" +"ては、まず ``text/x-rst; charset=UTF-8`` として表示を試み、正当な rst ではな" +"い場合に ``text/plain`` にフォールバックするべきです。" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" +"``Description-Content-Type`` が認識できない値である場合には、内容の型が " +"``text/plain`` であるものと仮定します (とはいえ、認識できない値であれば何で" +"あっても PyPI が拒否することになるでしょう) 。" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" +"``Description-Content-Type`` が ``text/markdown`` で、 ``variant`` が指定され" +"ない場合や認識できない値が指定された場合には、 ``variant`` が ``GFM`` である" +"ものと仮定されます。" + +#: ../source/specifications/core-metadata.rst:329 +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/core-metadata.rst:338 +msgid "Keywords" +msgstr "キーワード" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" +"より大きなカタログで配布物を検索する助けとなるべく使用される、コンマで区切ら" +"れた追加のキーワードのリスト。" + +#: ../source/specifications/core-metadata.rst:351 +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/core-metadata.rst:360 +msgid "Author" +msgstr "Author" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" +"少なくとも作者の名前を含む文字列で、連絡先となる情報を追加しても構いません。" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "Author-email" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" +"作者の電子メールアドレスを含む文字列。 RFC-822 の ``From:`` ヘッダの記述形式" +"として正当な形で名前と電子メールアドレスを含んでいても構いません。" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" +"RFC-822 によれば、このフィールドには、複数の電子メールアドレスをコンマで区" +"切って記述しても構いません ::" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "メンテナ" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" +"少なくともメンテナの名前を含む文字列で、連絡先となる情報を追加しても構いませ" +"ん。" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" +"当該プロジェクトが元々の作者とは異なる誰かによって保守されている場合にこの" +"フィールドを使うことを想定しているということを覚えておいてください: もし " +"``Author`` と同一人物であれば、このフィールドを省略するべきです。" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "Maintainer-email" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" +"メンテナの電子メールアドレスを含む文字列。 RFC-822 の ``From:`` ヘッダの記述" +"形式として正当な形で名前と電子メールアドレスを含んでいても構いません。" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" +"当該プロジェクトが元々の作者とは異なる誰かによって保守されている場合にこの" +"フィールドを使うことを想定しているということを覚えておいてください: もし " +"``Author-email`` と同一であれば、このフィールドを省略するべきです。" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "License" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "``License-Expression`` に従って。" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" +"Metadata 2.4 の時点では、 ``License`` と ``License-Expression`` は、相互に排" +"他的に扱われます。両者が同時に指定された場合は、メタデータをパースするツール" +"は ``License`` を無視するでしょうし、 PyPI はアップロードを拒否するでしょ" +"う。 `PEP 639 `__ " +"をみてください。" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" +"\"License\" Trove 分類子から選択したものではないライセンスの場合は、配布物を" +"カバーするライセンスを示すテキスト。後述の :ref:`\"Classifier\" ` を見てください。このフィールドは、 ``Classifier`` フィールドを経" +"由して名指しされたライセンスの特定のバージョンを指定したり、そのようなライセ" +"ンスに対する変種や例外事項を示したりするのに使っても構いません。" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "License-Expression" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" +":doc:`/specifications/license-expression` で指定された、正当な SPDX :term:`ラ" +"イセンス表現 ` であるテキスト文字列。" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" +"このフィールドの表現が、このフィールド (例えば、 :term:`ソースコード配布物 " +"` や :term:`Wheel`) を伴うメタデータを含" +"む :term:`配布物アーカイブ ` にだけ適用されるのであっ" +"て、プロジェクト全体やプロジェクトに関係する (他の配布物アーカイブを含む) 他" +"のファイルことに注意してください。" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "License-File (複数回使用)" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" +"各エントリは、ライセンス関連のファイルのパスの文字列表現です。パスは、プロ" +"ジェクトのソースコードツリー内に位置していて、プロジェクトのルートディレクト" +"リからの相対ぱすです。詳細については、 :pep:`639` をみてください。" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "Classifier (複数回の使用可)" + +#: ../source/specifications/core-metadata.rst:532 +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/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" +"``License::`` 分類子の使用は Metadata 2.4 の時点で非推奨になっており、代わり" +"に ``License-Expression`` を使ってください。 `PEP 639 `__ を見てください。" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "このフィールドでは、セミコロンの後に環境指標を続けても構いません。" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "Requires-Dist (複数回の使用可)" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" +"フィールドの仕様は、人気のある公開ツール群が用いる構文を許容するように緩めら" +"れました。" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" +"それぞれのエントリは、この配布物が要求する他の distutils のプロジェクトを名指" +"しする文字列を含みます。" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "要求事項を示す文字列のフォーマットは、１個から４個の部分を含みます:" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" +"``Name:`` フィールドと同じフォーマットのプロジェクト名。これだけが必須部分で" +"す。" + +#: ../source/specifications/core-metadata.rst:567 +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/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" +"バージョン指定子。この部分をパースするツールはバージョンを囲む括弧を許容しな" +"ければならないが、生成する際には括弧を使ってはなりません。" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" +"セミコロンの後ろに環境マーカ。要求事項が必要となるのが指定された条件の時のみ" +"であることを示します。" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "許容されるフォーマットの詳細については :pep:`508` を見てください。" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" +"プロジェクト名称は、 `Python Package Index`_ に出現する名前に対応していなけれ" +"ばなりません。" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" +"バージョン指定子は :doc:`version-specifiers` に記述された規則に従っていなけれ" +"ばなりません。" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +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:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" +"値は、 :doc:`version-specifiers` で指定されたフォーマットでなければなりませ" +"ん。" + +#: ../source/specifications/core-metadata.rst:606 +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/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "このフィールドでは、環境マーカを後ろに付けることはできません。" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "Requires-External (複数回の使用可)" + +#: ../source/specifications/core-metadata.rst:623 +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/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" +"要求事項の文字列のフォーマットは外部の依存先の名前で、必須ではありませんが括" +"弧に入れたバージョンの宣言を後ろにつけても構いません。" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" +"それらは非 Python のソフトウェアリリースを参照するものですので、このフィール" +"ドでのバージョン番号は :ref:`バージョン指定子仕様 ` で指" +"定されたフォーマットに適合することを **要求されていません** : それらは、外部" +"依存関係によって使われるバージョンスキームに対応するべきです。" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "使用される文字列に対して特に規則がないという点に注意してください。" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "Project-URL (複数回の使用可)" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" +"そのプロジェクトの閲覧可能な URL とラベルを含む文字列をコンマで区切ったもの。" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "このラベルは32 文字以内のフリーテキストです。" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" +":pep:`753` に始まって、プロジェクトメタデータの消費者 (the Python Package " +"Index など) は、 \"well-known\" なラベル、それは人間による消費のために展開さ" +"れる時には特定の特別な表現方法を与えることができますが、それを探索するために" +"標準標準化プロセスを使うことができます。 :ref:`well-known-project-urls` を見" +"てください。" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "Provides-Extra (複数回の使用可)" + +#: ../source/specifications/core-metadata.rst:677 +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/core-metadata.rst:682 +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/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" +"指定された名前は、追加的な機能が要求されたか否かに応じて依存関係を構築するた" +"めに使われます。" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +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/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" +"``Requires-Diet:`` のどこからも参照されていなくても、 ``Provides-Extra:`` を" +"指定しても構いません。" + +#: ../source/specifications/core-metadata.rst:715 +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/core-metadata.rst:720 +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." +msgstr "" +"メタデータの古めのバージョンから読み込む時、このフィールドの値が新しめのメタ" +"データバージョンとして正当でない場合にツールが警告するべきです。コアとなるメ" +"タデータのバージョンで ``Name:`` に対する規則に照らして値が正当ではないとすれ" +"ばユーザは警告されるべきで、その値は曖昧さを避けるために無視されるべきです。" +"古めのメタデータバージョンとして不当な名前を読み取った場合には、ツールはエ" +"ラーを発出することを選択しても構いません。" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "Import-Name (複数回の使用可)" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" +"インストール時にプロジェクトが排他的に提供するインポートネームを含む文字列。" +"指定されたインポートネームは、正当な Python 識別子でなければなりませんが、空" +"でも構いません。このフィールドに列挙されたインポートネームは、プロジェクトが" +"プロジェクトの同じバージョン用の *幾つかの* プラットフォームにインストールさ" +"れる時にインポート可能でなければなりません。これは、プロジェクトのあるリリー" +"スのすべての sdist と wheel を通じて、メタデータが守備一貫していなければなら" +"ないと言うことを意味します。" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" +"インポートネームは、セミコロンの前後には空白文字がいくつあっても構わない形" +"で、 (例えば ``; private`` のように) セミコロンと \"private\" と言う用語を" +"伴っても構いません。これによって、ツール類に対して、インポートネームがプロ" +"ジェクトの公開の API の一部では無いことを伝えます。" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" +"プロジェクトは、そのプロジェクトによって独占的に提供される、最短インポート" +"ネームをすべて列挙するべきです。最短ネームがドットで区切られたネームであるな" +"ら、そのネームからトップレベルのネームに至る中間のネームもまた、 ``Import-" +"Name`` および/または ``Import-Namespace`` に適切に列挙されるべきです。" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" +"あるプロジェクトが同じネームを ``Import-Name`` と ``Import-Namespace`` の両方" +"に列挙している場合、ツール類は、曖昧さの故にエラーを発しなければなりません。" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" +"ツール類は、まさにインストールされようとしているふたつのプロジェクトがそれぞ" +"れの ``Import-Name`` エントリに重複したネームを列挙している時や、あるプロジェ" +"クトが ``Import-Name`` 内に持つエントリがもう一つのプロジェクトの ``Import-" +"Namespace`` エントリと重複する時には、エラーを発生させるべきです。これは、プ" +"ロジェクトが意図せずもう一つのプロジェクトのソースコードを覆い隠してしまうこ" +"とを避けるためです。ツール類は、既にインストールされているプロジェクトとの間" +"でインポートネームの重複が起きるような既存環境にプロジェクトをインストールす" +"る時には、警告するかエラーを発生させて構いません。" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" +"プロジェクトは、プロジェクトがインポートネームを持っていないこと (すなわち、" +"配布物のファイルの中にはどんな種類の Python モジュールも存在しないこと) を表" +"現するために、そのメタデータ内に空の ``Import-Name`` フィールドを持っても構い" +"ません。" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" +"(プロジェクトが古いメタデータバージョンを使っているために、もしくは、一つも指" +"定していないために) プロジェクトが ``Import-Name`` メタデータを持たなくても構" +"わないので、ツール類は、そのプロジェクトがどんなネームを提供するのかについて" +"何も情報を持ちません。しかしながら、実際には、プロジェクトの大多数は、それら" +"のインポートネームであろうものと一致するようなプロジェクト名を持っています。" +"そういうことですので、何らかの答えが必要とされるなら、何らかの形で (例えば " +"``packaging.utils.canonicalize_name(name, validate=True).replace(\"-\", " +"\"_\")`` のように) インポート名を標準化したプロジェクト名を使うことが可能で" +"す。" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "Import-Namespace (複数回の使用可)" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" +"インストール時にプロジェクトが提供したインポートネームだが、独占的に提供した" +"ものではないものを含んだ文字列。指定されたインポートネームは、 Python の正当" +"な識別子でなければなりません。このフィールドは、複数のプロジェクトが同じイン" +"ポート名前空間に貢献することができるように、名前空間パッケージ用に用いられま" +"す。同じインポートネームを ``Import-Namespace`` に列挙するプロジェクト群は、" +"互いに隠蔽してしまうことなく一緒にインストールすることができます。" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" +"このフィールドに列挙されたインポートネームは、同じバージョンのプロジェクト用" +"の *いくつかの* プラットフォームにプロジェクトがインストールされる時に、イン" +"ポート可能でなければなりません。これは、プロジェクトのリリースのすべての " +"sdist や wheel でメタデータが整合していなければならないということを意味してい" +"ます。" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" +"``Import-Name`` では空値が許されますが、 ``Import-Namespace`` は空値であるこ" +"とはできないことに留意してください。" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "稀に使われるフィールド" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" +"この節のフィールドは、 Linux のパッケージ管理システムにおける類似の機構に触発" +"されて設計されましたが、 `PyPI `__ のような開放的なインデッ" +"クスサーバの文脈でツールがどのように翻案するべきかが全く明らかではないので、" +"現在ではほとんど使われません。" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" +"その結果として、人気のあるインストールツールでは完全に無視されていて、そのた" +"めに今度はパッケージを公開する側でもこれらのフィールドを適切に設定しておく誘" +"因がほとんどなくなっています。しかしながら、これらのフィールドは、情報提供の" +"目的ではまだ潜在的に役に立つことと、細かく注釈をつけるようなパッケージリポジ" +"トリと組み合わせれば本来意図された目的に用いることができることから、メタデー" +"タの仕様には残されています。" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "Provides-Dist (複数回の使用可)" + +#: ../source/specifications/core-metadata.rst:847 +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/core-metadata.rst:852 +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/core-metadata.rst:859 +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." +msgstr "" +"配布物は、また、個別に配布されているどんなプロジェクトにも紐付かない \"仮想の" +"\" プロジェクト名を持っていても構いません: そのような名前は、複数のプロジェク" +"トのうちのひとつで供給される抽象的な能力を示すために使われるかもしれません。" +"例えば、複数のプロジェクトがとある ORM で使われる RDBMS バインディングを提供" +"していても構いません: それぞれのプロジェクトが、他のプロジェクトが依存する時" +"にはそのうちの高々１個だけがインストールされていれば十分な ``ORM-bindings`` " +"を提供すると宣言していても構わないのです。" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" +"バージョンの宣言があっても構いませんが、 :doc:`バージョン指定子 ` に記述された規則に従ったものでなければなりません。もし指定されて" +"いなければ、配布物のバージョン番号が暗黙理に使われます。" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "Obsoletes-Dist (複数回の使用可)" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" +"それぞれのエントリは、この配布物が出たことで旧式化した、従ってこれらふたつの" +"プロジェクトが同時にインストールされるべきではない distutils プロジェクトの配" +"布物を記述する文字列を含みます。" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" +"バージョンの宣言があっても構いません。バージョン番号は :doc:`バージョン指定" +"子 ` で指定されたフォーマットでなければなりません。" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" +"このフィールドの最もよくある使い方は、例えば Gorgon 2.3 が Torqued Python " +"1.0 の一部として組み込まれた時のように、プロジェクトの名前が変更された場合で" +"しょう。 Torqued Python をインストールするなら、 Gorgon 配布物は削除されるべ" +"きです。" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "非推奨となったフィールド" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" +"非推奨となったフィールドは避けられるべきですが、しかし、まだ正当なメタデータ" +"フィールドです。それらは、将来のコアとなるメタデータ標準 (その時点では、取り" +"除くのに先立って、メタデータのバージョン番号を指定したファイル内でのみ正当で" +"あるという状態になることでしょう) のバージョンで取り除かれるかもしれません。" +"ツールの側では、ユーザに対して非推奨のフィールドが使われていることを警告する" +"べきです。" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "Home-page" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" +":pep:`753` に従って、代わりに :ref:`core-metadata-project-url` を使ってくださ" +"い。" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "配布物のホームページを示す URL を含んだ文字列。" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "Download-URL" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" +"そこからこのバージョンの配布物をダウンロードすることができる URL を含んだ文字" +"列。 (これが意味するところは、 URL は何か \"``.../BeagleVote-latest.tgz``\" " +"のようなものでは駄目で、 \"``.../BeagleVote-0.45.tgz``\" のようにバージョンを" +"含むものでなければならないということです。)" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "要求事項" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "``Requires-Dist`` に従って" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" +"それぞれのエントリは、このパッケージが必要とする他のモジュールやパッケージを" +"記述した文字列を含みます。" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" +"要求事項の文字列のフォーマットは、 ``import`` ステートメントで使うことができ" +"るモジュールやパッケージの名前のフォーマットと同一のもので、オプションとして" +"カッコ内に入れたバージョン宣言を伴うことがあります。" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" +"バージョン宣言は、一連の比較演算子とバージョン番号をカンマで区切ったもので" +"す。比較演算子は、\"<\", \">\", \"<=\", \">=\", \"==\", \"!=\" のいずれかひと" +"つでなければなりません。バージョン番号は、 " +"``distutils.version.StrictVersion`` によって受け入れられるフォーマットでなけ" +"ればなりません: 二つか三つの数字部分をドットで区切ったもので、オプションとし" +"て 'a' か 'b' の後ろに数字が続く形の \"pre-release\" タグを末尾につけたもの。" +"バージョン番号の例としては、 \"1.0\" や \"2.3a2\" や \"1.3.99\" 、" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" +"例えば \">1.0, !=1.3.4, <2.0\" という文字列が正当なバージョン宣言であるよう" +"に、比較演算子はいくつでも指定することができます。" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" +"次に示すすべての要求仕様文字列 は実際に可能なものです: " +"\"rfc822\", \"zlib (>=1.1.4)\", \"zope\"。" + +#: ../source/specifications/core-metadata.rst:980 +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/core-metadata.rst:993 +msgid "Provides" +msgstr "提供する" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "``Provides-Dist`` を支持して " + +#: ../source/specifications/core-metadata.rst:999 +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/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "古くなった " + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "``Obsoletes-Dist`` に従って" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" +"それぞれのエントリには、あるパッケージなりモジュールなりがあることで、この" +"パッケージが使われなくなっている ということを記述する、すなわち、" +"これら二つのパッケージは同時にはインストールされるべきではないことを示す、そ" +"のような文字列が含まれます。バージョン宣言を書いておくことができます。" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" +"このフィールドの最もよくある使い方は、例えば Gorgon 2.3 が Torqued Python " +"1.0 の一部として組み込まれた時のように、プロジェクトの名前が変更された場合で" +"しょう。 Torqued Python をインストールするなら、 Gorgon パッケージは削除され" +"るべきです。" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" +"2001年3月: :pep:`241` を通じてコアとなるメタデータ 1.0 が承認されました。" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" +"2003年4月: :pep:`314` を通じてコアとなるメタデータ 1.1 が承認されました。" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" +"2010年2月: :pep:`345` を通じてコアとなるメタデータ 1.2 が承認されました。" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" +"2018年2月: :pep:`566` を通じてコアとなるメタデータ 2.1 が承認されました。" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "``Description-Content-Type`` と ``Provides-Extra`` を追加しました。" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "メタデータを JSON に変換する正規化された方法を追加しました。" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "``Name`` フィールドの文法に制限を加えました。" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" +"2020年10月: :pep:`643` を通じてコアとなるメタデータ 2.2 が承認されました。" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "``Dynamic`` フィールドを追加しました。" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" +"2022年3月: :pep:`685` を通じてコアとなるメタデータ 2.3 が承認されました。" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "その他の名称 の標準化に制限を加えました。" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" +"2024年8月: :pep:`639` を通じて、コアとなるメタデータ 2.4 が承認されました。" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "``License-Expression`` フィールドを追加しました。" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "``License-File`` フィールドを追加しました。" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" +"2025年8月: ``動的 `` 指定がそのフィールドの取り扱いに影響を与えるの" +"は、 sdist から wheel をビルドする時だけであって、 wheel を変換するするときに" +"は影響を与えないのだということが明確化された。" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" +"2025年9月: :pep:`794` を通じてコアとなるメタデータ 2.5 が承認されました。" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "``Import-Name`` フィールドを追加しました。" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "``Import-Namespace`` フィールドを追加しました。" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" +"2025年10月: ``License-Expression`` は、含まれている配布物のファイルに適用され" +"るのであって、プロジェクトそれ自体に適用されるものではないことを明確にした。" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "reStructuredText マークアップ言語: https://docutils.sourceforge.io/" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "RFC 822 長形式ヘッダフィールド: :rfc:`822#section-3.1.1`" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "依存関係グループ" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" +"この仕様では、ビルド時にプロジェクトメタデータに含まれなかったパッケージ要求" +"事項を ``pyproject.toml`` 内に保存するための機構であるところの、依存関係グ" +"ループ を定義しています。" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" +"依存関係グループは、関連するスクリプトの集合のような配布物作成のためにビルド" +"されたのではないプロジェクト向けと同様に、静的解析ツール (lint) や試験用ツー" +"ルのような内部開発でのユースケース向けに適切です。" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" +"基本的に、依存関係グループは、(``pip`` に特有の) ``requirements.txt`` ファイ" +"ルできることを標準化したサブセットであるものと考えるべきです。" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" +"これは、 ``docs`` グループと ``test`` グループを示す単純なテーブルです::" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" +"そして ``docs`` や ``test`` と ``coverage`` の各グループを定義するよく似た" +"テーブル::" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "``[dependency-groups]`` テーブル" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" +"依存関係グループは、 ``pyproject.toml`` の中の ``dependency-groups`` という名" +"前のテーブルとして定義されています。 ``dependency-groups`` テーブルには、任意" +"の数のユーザが定義したキーを含み、そのそれぞれが要求事項をその値に取ります。" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" +"``[dependency-groups]`` キーは、ある時には \"group names\" とも呼ばれます" +"が、 :ref:`正当な非標準化名称 ` でなければなりません。依存関係グ" +"ループ を取り扱うツール類は、比較の前にこのような名称" +"を :ref:`標準化 ` しなければなりません。" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" +"ツール類は、オリジナルの非標準化名称をユーザに表示することを選好するべきで、" +"標準化後に名称の重複が検出された場合にはツール類はエラーを発するべきです。" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" +"要求事項リスト、つまり ``[dependency-groups]`` 内の値は、文字列やテーブル " +"(Python の ``dict``) やその混合物を含んでいても構いません。文字列は正当" +"な :ref:`依存関係指定子 ` でなければならず、テーブルは" +"正当な Dependency Group Includes でなければなりません。" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "Dependency Group Include" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" +"Dependency Group Include は、現在のグループに他の依存関係グループをインクルー" +"ドするものです。" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" +"include は正確に一つだけのキーを持つテーブルで ``\"include-group\"`` といい、" +"その値は他の依存関係グループの名称文字列です。" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" +"Include は指定された依存関係グループの内容と厳密に同等になるように定義されて" +"いて、それが現在のグループの include の位置に挿入されます。例えば、 ``foo = " +"[\"a\", \"b\"]`` がひとつのグループで ``bar = [\"c\", {include-group = " +"\"foo\"}, \"d\"]`` がもうひとつのグループであるなら、依存関係グループが転換さ" +"れた時には、 ``bar`` は ``[\"c\", \"a\", \"b\", \"d\"]`` と評価されるべきで" +"す。" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" +"依存関係グループ引用では、同じパッケージを複数回にわたって指定しても構いませ" +"ん。ツールは重複排除を行うべきではなく、そうでなければ引用 によって" +"生成されたリストの内容を改変してしまうことになります。例えば、次のテーブルが" +"あるとして:" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" +"``all`` を解決して得られた値は、 ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]`` であるはずです。ツールは、このようなリストを、同じ要求事項に異" +"なるバージョン制約が課されたものを、複数回にわたって処理するように依頼されて" +"いるような他のどんなケースでも正確に同じように取り扱うべきです。" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" +"依存関係グループ引用 は、依存関係グループ引用を含" +"むグループを引用 しても構いませんし、そのような引用されグループも同" +"様に展開されるべきです。依存関係グループ引用はループを引用してはならず、ツー" +"ルはループを検出した時にはエラーを報告するべきです。" + +#: ../source/specifications/dependency-groups.rst:102 +msgid "Package Building" +msgstr "パッケージビルディング" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" +"ビルドバックエンドは、ビルドした配布物の中の依存関係グループのデータを、パッ" +"ケージのメタデータとして含めてはなりません。これが意味するところは、 sdist " +"の ``PKG-INFO`` や wheel の ``METADATA`` ファイルが依存関係グループを含む参照" +"可能なフィールドを含んでいてはならないということです。" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" +"しかしながら、動的なメタデータの評価で依存関係グループを使うことは正当なこと" +"であり、 sdist に含まれる ``pyproject.toml`` ファイルは依然として ``[dynamic-" +"groups]`` を含んでいることでしょう。しかしながら、このテーブルの内容は、ビル" +"ドされたパッケージのインタフェースの一部分ではありません。" + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "" +"依存関係グループ と追加物 をインストールする" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" +"依存関係グループをインストールしたり参照したりするインタフェースに関する文法" +"も定義済みの仕様も存在しません。ツール類には、この目的のために専用のインタ" +"フェースを提供することが期待されています。" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" +"ツール類は、依存関係グループとの相互作用を行うためのインタフェースとして、追" +"加物 を管理する時と同一またはよく似たものを提供することを選択しても" +"構いません。ツール類の作者には、依存関係グループと名前が一致する追加物を持つ" +"ことを仕様は禁じていない、と助言しておきます。これとは別に、ユーザには、追加" +"物の名前と一致する依存関係グループを作成しないように、そのような一致があると" +"ツール類がエラーとして取り扱うかもしれませんよ、と助言しておきます。" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "正当性検証と互換性" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" +"依存関係グループをサポートするツール類は、データを使う前に正当性を検証したい" +"と望むかもしれません。そのような正当性検証を実装する時には、作者は、不要なエ" +"ラーや警告を発することのないように、この仕様に対する将来の拡張の可能性を意識" +"しておくべきです。" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" +"ツール類は、依存関係グループ内で認識できないデータを評価または処理しようとし" +"た時にはエラーを発するべきです。" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" +"ツール類は、そうする必要がない限り、 *すべての* 依存関係グループの内容の正当" +"性評価を好んで行うべきではありません。" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" +"これが意味するところは、以下のデータがあるとすると、ほとんどのツールは " +"``foo`` グループが使われることを許すべきで、 ``bar`` グループが使われた時にの" +"みエラーを発生させるべきです:" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" +"ツールがより厳密に取り扱う良い理由のあるケースがいくつか知られています。静的" +"解析ツール や正当性確認ツール はひとつの例で、その目的" +"がすべての依存関係グループの内容の正当性を検証することだからです。" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +msgid "Reference Implementation" +msgstr "参照実装" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" +"次に示す参照実装は依存関係グループの内容を改行で区切って標準出力に書き出しま" +"す。その出力は、従って、正当な ``requiurements.txt`` データです。" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "2024年10月: :pep:`735` を通じてこの仕様が承認されました。" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "依存関係指定子" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" +"元々は :pep:`508` で指定されていた依存関係指定子のフォーマットを、この説明文" +"書は記述します。" + +#: ../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/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" +"定義された言語は、簡潔な行単位のフォーマットであって pip の requirements ファ" +"イルで既に広く使われているものですが、そのようなファイル群を許容するようなコ" +"マンドラインオプションを指定することはしていません。ひとつ注意しなければなら" +"ないのは、 :ref:`バージョン指定子仕様 ` で指定されている" +"ような URL を参照する形式は実は pip では実装されていないのに、現在の pip の本" +"来のフォーマットよりもむしろそちらのフォーマットを使っているという点です。" + +#: ../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 "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" +"依存関係の指定では、常に、配布物の名前を指定します。名前で指定された配布物で" +"特定の追加機能を有効にするように依存関係を拡張するような追加物 を含ん" +"でいても構いません。インストールされたバージョンをバージョンリミットで制御す" +"ることもできますし、特定のアーティファクトをインストールするために URL を与え" +"ることもできます。依存関係は最終的に環境マーカを用いて条件別に作成することも" +"できます。" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "文法" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" +"最初に文法について簡単に触れた後、それぞれの節の意味論 について深" +"く掘り下げることにしましょう。" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" +"配布物の仕様は ASCII テキストで書かれています。厳密な文法としては parsley " +"[#parsley]_ の文法を使っています。この仕様は、コメントや継続による複数行サ" +"ポートやその他の機能の枠組みを与えるもっと大きなシステムの中に組み込まれるこ" +"とを期待しています。" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" +"役に立つ構文解析ツリーを構成するための注釈機能を含む完全な文法は、この説明文" +"書の末尾に置きました。" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" +":ref:`バージョン指定子仕様 ` の規則に従ってバージョンを指" +"定しても構いません。(ノート: URI は :rfc:`std-66 <3986>` で定義されていま" +"す)::" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" +"環境マーカを使うことで、ある仕様が特定の環境でのみ有効であることを示すことが" +"できます::" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" +"配布物のうちの必須ではない部分については extras フィールドを使って指定するこ" +"とができます::" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" +"行を分割するものではない空白文字には特に意味はなく、ほとんどの場合には必須で" +"はないものです。唯一の例外は、 URL による要求事項の末尾を検出するためのもので" +"す。" + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "名前 " + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" +"Python の配布物の名前は、現時点では :pep:`345` で定義されています。名前は配布" +"物の最も基本的な識別子として働きます。(名前は) あらゆる依存関係の指定に出現" +"し、それだけで十分に指定することができます。しかしながら、 PyPI では名前に厳" +"密な制約を課しています - 名前は大文字小文字を区別しない正規表現に合致しなけれ" +"ば受け入れられません。従って、この説明文書では、その正規表現に合致する識別子" +"だけを受け入れ可能な値として扱うことにしましょう。名前の完全な再定義はメタ" +"データ PEP として将来に出現するかもしれません。ここでいう (re.IGNORECASE とと" +"もに評価されるべき) 正規表現とは、次のようなものです::" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "追加物 " + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" +"追加物とは、配布物の必須ではない部分のことです。配布物では追加物を幾つでも指" +"定することができ、追加物が依存関係の指定場所で使われた **場合** には、それぞ" +"れの追加物が配布物の追加的な依存関係を宣言する結果になります。例えば::" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" +"追加物 の依存関係の合併とは、その追加物が添付されている配布物 " +" の依存関係と一緒に定義されることです。上に示した例では、結果と" +"して requests がインストールされることになり、requests は自身の依存関係を持つ" +"ので requests の \"security\" 追加物 に列挙されたすべての依存関係 " +"(先) もインストールされることになります。" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" +"複数の追加物 が列挙されている場合には、すべての依存関係の合併集合が依" +"存関係になります。" + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "バージョン指定子" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" +"バージョン番号やその比較方法について、詳しくは :ref:`バージョン指定子仕様 " +"` をみてください。バージョン仕様は、配布物のバージョンと" +"して使うことができる範囲を定めています。これは、名前によって参照される配布物" +"にのみ適用されるのであって、URL を通じて指定されるものには該当しません。バー" +"ジョン番号の比較は、また、マーカー機能においても使われます。バージョンの周囲" +"にある必須でない括弧は :pep:`345` との互換性を保つために存在していますが、そ" +"のようなものを生成すべきではなくて受容するだけにとどめるべきです。" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "環境マーカ" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" +"環境マーカは、依存関係の指定においてその依存関係がいつ使われるべきであるかを" +"記述する規則を提供します。例えば、あるパッケージが argparse を必要とするとし" +"ましょう。Python 2.7 では argparse は常に存在します。もっと古いバージョンの " +"Python では依存関係としてインストールされなければなりません。これは次のように" +"表現することができます::" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" +"マーカ表現は評価されると真か偽に帰着します。偽と評価された場合には、その依存" +"関係の指定は無視されなければなりません。" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" +"マーカ言語は Python そのものに触発されたもので、セキュリティ上の脆弱性になり" +"かねない任意コードの実行を伴わずに安全に評価を行うことができるので選ばれまし" +"た。マーカは:pep:`345` で初めて標準化されました。この説明文書で" +"は、 :pep:`426` に記述されたデザインに見られるいくつかの問題点を修正していま" +"す。" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" +"マーカ表現の比較は比較演算子とマーカ値の型によって分類されます。 " +" の中に入っていない 演算子は、マーカ値それ自身が文字" +"列であるか集合であるかに基づいて、 Python における文字列または集合 で" +"のそれと同様に動作します。 演算子は、定義されている場合 (つまり" +"両側に正当はバージョン指定子を伴う場合) には、 :ref:`バージョン指定子仕様 " +"` のバージョン比較規則を採用しています。演算子の動作がこ" +"の仕様で定義されておらず、かつ、その演算子が Python に存在する場合には、当該" +"演算子は該当する型の Python での動作にフォールバックします。そうでない場合に" +"はエラーを発生させるべきです。例えば、次の表現はエラーを発生させる結果となる" +"でしょう::" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" +"ユーザ側から供給された定数は、常に ``'`` または ``\"`` なる引用記号を伴った文" +"字列として符号化されます。バックスラッシュによるエスケープは定義されていませ" +"んが、現存する実装ではサポートされているということを忘れないでください。この" +"仕様には (バックスラッシュエスケープは) 含まれていませんが、それは、複雑性を" +"増加させてしまうことと、現時点では目に見えるほどの必要性がないことが理由で" +"す。同様に、非 ASCII 文字のサポートも定義していません: 我々が参照するようなラ" +"ンタイムのすべての変数は、 ASCII 文字のみで構成されているものと期待されていま" +"す。" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" +"\"os_name\" のようなマーカの文法内の変数は、 Python のランタイム内でルック" +"アップすることで値へと解決されます。 \"extra\" を例外として、すべての値は現在" +"のすべてのバージョンの Python で定義されています - もし値が定義されていなけれ" +"ば、それはマーカの実装のエラーです。" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" +"未知の変数は、評価して真 か偽 となる比較の結果を返すのではな" +"く、エラーを生成しなければなりません。" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" +"特定の Python 実装で値を計算することができない変数は、バージョンについては " +"``0`` として、その他のすべての変数については空文字列として評価されるべきで" +"す。" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" +"\"extra\" 変数は、扱いが特別です。それは wheel ファイルにおいて、その wheel " +"の ``METADATA`` ファイル内の特定の追加物 にどの仕様を適用するべきであ" +"るかを知らせるために使われますが、 ``METADATA`` ファイルの様式が :pep:`426` " +"のドラフトバージョンに基づいているので、現時点ではその仕様が存在していないの" +"です。それにも関わらず、この特別な扱いが行われる場所ではない文脈においては、 " +"\"extra\" 変数はその他の未知の変数と同様にエラーに帰着するべきです。" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" +"変数の \"extras\" と \"dependency_groups\" もまた特別なものです。これらは、" +"ロックファイル からインストールする際に、要求される追加物 " +" や依存関係グループ を指定するために使われます。" +"ロックファイルの文脈の範囲の外では、他のすべての未知変数と同様に、これら２個" +"の変数はエラーになるべきです。" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "マーカ " + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "Python 同等物" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "種類" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "値の例" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "``OS の名称 ``" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr ":py:data:`os.name`" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "文字列" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "``posix``, ``java``" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "``sys_platform``" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr ":py:data:`sys.platform`" + +#: ../source/specifications/dependency-specifiers.rst:258 +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/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "``platform_machine``" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr ":py:func:`platform.machine()`" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "``x86_64``" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "``platform_python_implementation``" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr ":py:func:`platform.python_implementation()`" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "``CPython``, ``Jython``" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "``platform_release``" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr ":py:func:`platform.release()`" + +#: ../source/specifications/dependency-specifiers.rst:271 +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/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "``platform_system``" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr ":py:func:`platform.system()`" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "``Linux``, ``Windows``, ``Java``" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "``platform_version``" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr ":py:func:`platform.version()`" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "``python_version``" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "``'.'.join(platform.python_version_tuple()[:2])``" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +msgid ":ref:`Version `" +msgstr ":ref:`バージョン `" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "``3.4``, ``2.7``" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "``python_full_version``" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr ":py:func:`platform.python_version()`" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "``3.4.0``, ``3.5.0b1``" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "``implementation_name``" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr ":py:data:`sys.implementation.name `" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "``cpython``" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "``implementation_version``" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "下方の定義を見てください" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "``extra``" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "仕様を通訳する文脈で定義された場合を除くエラー。" + +#: ../source/specifications/dependency-specifiers.rst:302 +msgid "``toml``" +msgstr "``toml``" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "``extras``" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "文字列の集合" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "``{\"toml\"}``" + +#: ../source/specifications/dependency-specifiers.rst:308 +msgid "``dependency_groups``" +msgstr "``dependency_groups``" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "``{\"test\"}``" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" +"``implementation_version`` マーカ変数" +"は、 :py:data:`sys.implementation.version ` から派生した" +"ものです :" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" +"この環境マーカの節は、当初は :pep:`508` を通して定義されました" +"が、 :pep:`345` における環境マーカの節を置き換えます。" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "完全な文法" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "完全な parsley 文法::" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "テストプログラム - もし ``grammar`` 文字列内に文法があれば:" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "2015年11月: :pep:`508` を通じてこの仕様が承認されました。" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" +"2019年6月: ``python_version`` の定義は、Python の将来のバージョンが二桁のメ" +"ジャーバージョンやマイナーバージョンを持つ場合 (例えば 3.10) でもそれを収容で" +"きるように、 ``platform.python_version()[:3]`` から " +"``'.'.join(platform.python_version_tuple()[:2])`` へ `変更されました `_ 。 [#future_versions]_" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" +"2024年6月: 2022年遅くから使われるようになった Python 実装の動作に合致するよう" +"に、末尾のカンマを許容する形に ``version_many`` の定義が変更された。" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" +"2025年4月: :ref:`lock-file-spec` に ``extras`` と ``dependency_groups`` を追" +"加することが :pep:`751` を通じて承認された。" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" +"2025年8月: フィールドの仕様と合致させるために示唆されていた名称正当性確認用正" +"規表現が決定された (以前は ``\\Z`` の代わりに ``$`` で終端していたので、誤っ" +"て後続する行末コード を許容していた)" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" +"2025年12月: あらゆる意味での同一性 の比較がパースされる" +"ことを許すために、 ``==`` より前に ``===`` を (評価することを) 確実に。" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" +"Python のパッケージをインストールする際に推奨されるツールである pip (http://" +"pip.readthedocs.org/en/stable/)" + +#: ../source/specifications/dependency-specifiers.rst:542 +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:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" +"Python の将来のバージョンでは、環境マーカ変数の ``python_version`` の定義が問" +"題をはらむかもしれません。 (https://github.com/python/peps/issues/560)" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "インストールされた配布物の配布元へ直接アクセスする URL を記録する" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" +"この説明文書では、インストール済みの配布物の `*.dist-info` ディレクトリにあ" +"る :file:`direct_url.json` ファイルによって配布物の配布元へ直接アクセスする " +"URL を記録する方法を指定します。 ``*.dist-info`` ディレクトリの一般的な構造と" +"使用方法は、 :ref:`インストール済みパッケージを記録する ` に記述されています。" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" +":file:`direct_url.json` ファイルは、要求事項が指定するダイレクト (VCS の URL " +"を含む) 参照 URL からインストールしている時に、インストーラによっ" +"て :file:`*.dist-info` ディレクトリに生成されなければなりません。" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" +"他のタイプの要求事項 (すなわち、名前とバージョン指定子) から配布物をインス" +"トールする際には、このファイルを生成してはなりません。" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" +"この JSON ファイルは、 :rfc:`8259` に準拠するように UTF-8 で符号化されていな" +"ければならず、シリアル化の方法は :doc:`direct-url-data-structure` でなければ" +"なりません。" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" +"要求された URL が file:// スキームであって VCS からチェックアウトしたものを含" +"むローカルディレクトリを指し示している場合には、インストーラはいかなる VCS 情" +"報をも推定してはならず、従って、いかなる (``vcs_info`` のような) VCS 関連情報" +"をも :file:`direct_url.json` に出力してはなりません。" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" +"一般的な規則として、 :file:`direct_url.json` を生成する際には、インストーラは" +"可能な限り要求された URL に含まれる情報を保存するべきです。例えば、 " +"user:password を環境変数から読み込むなら環境変数を参照するような URL として保" +"存されるべきであり、 ``requested_revision`` は要求された URL の中に出現するも" +"のを極力そのまま反映するべきです。しかしながら、この情報は (``commit_id`` の" +"ような) もっと精密なデータを使って *精製* されます。" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "pip コマンドの例と direct_url.json に与える影響" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "``direct_url.json`` を生成するコマンド:" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (この場合、 ``url`` は git リポジトリのクロー" +"ン先のローカルディレクトリになり、 ``dir_info`` は ``\"editable\": true`` と" +"いう形で存在し、 ``vcs_info`` は設定されないということになるでしょう)" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "``direct_url.json`` を *生成しない* コマンド" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../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 "" +"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/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" +"本稿執筆時点では、ツール群に渡せるようにこのデータ構造の各部分を単一の URL に" +"まとめる方法については公式には指定されていません。よく見られる表現形式は pip " +"URL フォーマット (`VCS サポート `_) で、他の例が :ref:`バー" +"ジョン指定子仕様 ` の中で提供されています。" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" +"直接 URL データ構造は辞書でなければならず、 :rfc:`8259` に従って JSON にシリ" +"アライズできなければなりません。" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +msgstr "" +"少なくとも二つのフィールドが含まれていなければなりません。一つ目は " +"``string`` 型の ``url`` です。その内容は、 `WHATWG URL 標準 `_ に従う正当な URL でなければなりません。" + +#: ../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/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "セキュリティ上の配慮" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" +"固持する場合には、``url`` は、セキュリティ上の理由から、機微に関わる認証情報" +"をすべて削除しておかなければなりません。" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" +"URLの user:password の部分は、しかしながら、次に述べる正規表現に合致する形" +"で、環境変数から構成しても構いません:" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" +"さらに、 URL の user:password 部分は、広く知られたセキュリティ的に問題のない" +"文字列であっても構いません。典型的な例としては、 ``ssh://git@gitlab.com/user/" +"repo`` のような URL における ``git`` を挙げることができます。" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "VCS URL群" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" +"``url`` が VCS リポジトリを参照している場合、 以下のキー群を伴った " +"``vcs_info`` キーが辞書に存在していなければなりません:" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" +"(``git`` ・ ``hg`` ・ ``bzr`` ・ ``svn`` のいずれかのような) VCS の名前を含ん" +"だ ``vcs`` キー (``string`` 型) が存在していなければなりません。その他の VCS " +"については、この仕様を修正するための PEP を書くことによって登録されるべきで" +"す。当該 VCS の checkout/download コマンドへの翻訳をしなくてもインストーラが " +"手を離してしまえるようにするために、 ``url`` の値は対応する VCS と齟齬のない" +"ものでなければなりません。" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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`` 型) は、 (VCS と互換性のあるフォー" +"マットであれば) どのブランチ・タグ・リファレンス・コミット・リビジョンその他" +"を指定するために存在していても構いません。このフィールドは、ユーザが要求する" +"リビジョンに合致しなければなりませんし、ユーザが特定のリビジョンを選択してい" +"ない場合には存在してはなりません。" + +#: ../source/specifications/direct-url-data-structure.rst:70 +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:80 +msgid "Archive URLs" +msgstr "アーカイブ URL 群" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" +"``url`` がソースコードのアーカイブや wheel ファイルを指し示す場合には、 " +"``archive_info`` キーが次のようなキーを持つ辞書の形で存在しなければなりませ" +"ん:" + +#: ../source/specifications/direct-url-data-structure.rst:85 +msgid "" +"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/direct-url-data-structure.rst:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "これらのハッシュの名前は、常に小文字に正規化されているべきです。" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" +":py:mod:`hash lib` 経由で利用可能なハッシュアルゴリズム (とりわ" +"け、 :py:func:`hashlib.new()` に渡すことができて、かつ、それ以上のパラメータ" +"を必要としないもの) はどれでも、ハッシュ値を格納する辞書のキーとして用いるこ" +"とができます。 :py:data:`hashlib.algorithms_garanteed` から安全なアルゴリズム" +"を少なくともひとつ選択して含めるべきです。執筆時点では、 ``sha256`` が特に推" +"奨されています。" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" +"非推奨となった ``hash`` キー (``string`` 型) は、後方互換性を保つ目的でなら " +"``=`` を値に取る形で存在していても構いません。" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" +"データ構造を生成する側では、ひとつまたは複数のハッシュが利用できるなら " +"``hashes`` キーを生成するべきです。以前からそうしていたので既存のクライアント" +"のために後方互換性を保つためなら、生成側は ``hash`` キーの生成を継続するべき" +"です。" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" +"``hash`` と ``hashes`` の両方のキーが存在する時は、 ``hash`` キーの中に現れる" +"ハッシュは、 ``hashes`` の辞書の中にも存在しなければならず、そうすることで利" +"用する側では ``hashes`` キーがあればそれだけを考慮し、なければ ``hash`` に" +"フォールバックすることが可能になります。" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "ローカルディレクトリ" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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/direct-url-data-structure.rst:119 +msgid "" +"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " +"installed in editable mode, ``false`` otherwise. If absent, default to " +"``false``." +msgstr "" +"配布物が編集可能モードでインストールされた/される場合には ``editable`` " +"(``boolean`` 型): ``true`` 、そうでなければ ``false`` 。存在していない場合の" +"デフォルトは ``false`` です。" + +#: ../source/specifications/direct-url-data-structure.rst:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" +"``url`` がローカルのディレクトリを参照している場合、 :rfc:``8089` に適合する " +"``file`` スキームが存在していなければなりません。特にパス部分は絶対パスでなけ" +"ればなりません。相対パスを絶対パスに変換する際には、シンボリックリンクはその" +"まま保存されているべきです。" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "サブディレクトリ内のプロジェクト群" + +#: ../source/specifications/direct-url-data-structure.rst:132 +msgid "" +"A top-level ``subdirectory`` field MAY be present containing a directory " +"path, relative to the root of the VCS repository, source archive or local " +"directory, to specify where ``pyproject.toml`` or ``setup.py`` is located." +msgstr "" +"トップレベルの ``subdirectory`` フィールドは、 ``pyproject.toml`` または " +"``setup.py`` が存在する場所を指定するために、 VCS リポジトリやソースコードの" +"アーカイブやローカルのディレクトリのルートディレクトリに対する相対パスとして" +"示したディレクトリパスを値とするものとして存在することが許されています。" + +#: ../source/specifications/direct-url-data-structure.rst:139 +msgid "Registered VCS" +msgstr "登録済みの VCS" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" +"この節では登録済み VCS; ``vcs`` や ``requested_revision`` やその他の " +"``vcs_info`` 内のフィールドや、さらにある場合には特定の VCS に特有のフィール" +"ドなどの使い方のような拡張された VCS 特有の情報 の一覧を示します。 PEP を書く" +"ことでこの仕様を修正する形で別の VCS を登録することが推奨されていますが、ツー" +"ルの側で他の VCS を (訳注、VCS 登録作業抜きで) サポートしても構いません。 " +"``vcs`` フィールドの値は、 (小文字の) コマンド名であるべきです。当該 VCS をサ" +"ポートするのに必要であると思われるその他のフィールドについては、当該 VCS のコ" +"マンド名で始まる名前にするべきです。" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "Git" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "ホームページ" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "https://git-scm.com/" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "vcs コマンド" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "git" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "``vcs`` フィールド" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "``requested_revision`` フィールド" + +#: ../source/specifications/direct-url-data-structure.rst:163 +msgid "" +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." +msgstr "" +"タグ名・ブランチ名・Git 参照・コミットハッシュ・短縮型コミットハッシュ・その" +"他のコミットハッシュ的なもの。" + +#: ../source/specifications/direct-url-data-structure.rst:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "``commit_id`` フィールド" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "コミットハッシュ (16進数で40文字のSHA1)。" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" +"ツールは、 ``requested_revision`` が Git 参照に対応しているか否かを判断するた" +"めに ``git show-ref`` や ``git symbolic-ref`` コマンドを使うことができます。" +"さらに、 ``refs/tags/`` で始まる参照はタグに対応し、クローンした後に ``refs/" +"remotes/origin/`` で始まる参照はブランチに対応します。" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "Mercurial" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "https://www.mercurial-scm.org/" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "hg" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "タグ名・ブランチ名・チェンジセット ID ・短縮型チェンジセット ID。" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "チェンジセット ID (16 進数で 40 文字)。" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "Bazaar" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "https://www.breezy-vcs.org/" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "bzr" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "タグ名・ブランチ名・リビジョン id 。" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "リビジョン id 。" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "svn" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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/direct-url-data-structure.rst:230 +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/direct-url-data-structure.rst:235 +msgid "JSON Schema" +msgstr "JSON スキーマ" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" +"以下に述べる JSON スキーマを ``direct_url.json`` の内容を検証するために使うこ" +"とができます:" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "ソースコードアーカイブ:" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "タグおよびコミットハッシュ付きの Git のURL:" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "ローカルディレクトリ:" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "編集可能モード状態にあるローカルディレクトリ:" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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/direct-url-data-structure.rst:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" +"2023年1月: ``archive_info.hashes`` キーを追加しました (`議論 `_) 。" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "エントリポイントの仕様" + +#: ../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/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/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/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/entry-points.rst:28 +msgid "Data model" +msgstr "データモデル" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" +"概念的に、エントリポイントは３個の属性を持たなければならないと定義されていま" +"す:" + +#: ../source/specifications/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/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/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/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/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/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" +"エントリポイント用に extras を使うことはもはや推奨されていません。利用する側" +"は、既存の配布物からそれを取り出して解析することをサポートするべきですが、し" +"かし、無視しても構いません。新しい公開用ツールは、 extras を指定することをサ" +"ポートする必要はありません。 extras を扱う機能は setuptools が 'egg' パッケー" +"ジを管理するモデルに紐づいたものですが、しかし、 pip や virtualenv のような" +"もっと新しいツールでは異なるモデルを採用しています。" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "ファイルフォーマット" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" +"エントリポイントは、配布物の `*.dist-info` ディレクトリの中" +"の :file:`entry_points.txt` と呼ばれるファイル内で定義されます。これは、イン" +"ストール済みの配布物に関しては :ref:`インストール済みパッケージを記録する " +"` 、 wheels に関しては :ref:`バイナリ配布物の" +"フォーマット ` に記述されます。このファイルでは " +"UTF-8 エンコーディングを使います。" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" +"ファイルの内容は、 Python の :mod:`configparser` モジュールで読み取ることがで" +"きる INI フォーマットです。しかしながら、 configparser はデフォルトでは変数名" +"を大文字小文字の区別をせずに扱う一方で、エントリポイントでは区別をします。大" +"文字小文字の区別をする configparser はこのようにして作成できます::" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" +"エントリポイントのファイルでは、名前と値を区切るのに常に ``=`` を使わなければ" +"なりません (他方で configparser は ``:`` で区切ることも許容します) 。" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" +"設定ファイルの各セクションはエントリポイントの各グループを表していて、名前は" +"名前であり、値はオブジェクトへの参照と任意の extras の両方をエンコードしま" +"す。 extras が使われる場合には、角括弧の中にコンマ区切りで列挙します。" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" +"値の内部では、読み取る側はコロンの前後・オブジェクト参照と左角括弧の間・extra" +"の名前と角括弧や区切り文字のコロンの間・右角括弧の後にある空白文字 (連続する" +"複数の空白文字を含む) を許容し無視しなければなりません。 extras の文法は公式" +"に :pep:`508` の一部 (の ``extras`` 部分) として指定されており、値に関する制" +"限事項は :pep:`685` で指定されています。ファイルを書き出すようなツールでは、" +"オブジェクト参照と左角括弧の間に限って空白文字を挿入することが推奨されていま" +"す。" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "スクリプト向けの使用法" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" +"``console_scripts`` と ``gui_scripts``: エントリポイントのふたつのグループ" +"は、パッケージング全体の中で特別な重要性を持っています。このふたつのグループ" +"では、エントリポイントの名前は、パッケージがインストールされた後にシステムの" +"シェルでコマンドとして使えるものでなければなりません。オブジェクト参照は、こ" +"のコマンドが動作する際に引数なしで呼び出される関数を指し示しています。関数" +"は、プロセスの終了コードとして使われる整数を返しても構わず、 ``None`` を返す" +"と ``0`` を返したのと同じに扱われます。" + +#: ../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/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/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/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" +"名前からファイルが作られることと、いくつかのファイルシステムでは大文字小文字" +"を区別しないことから、パッケージはこれらのグループについては大文字か小文字か" +"の違いしかないような名前を使うことを避けるべきです。名前が大文字小文字しか違" +"わない場合のインストールツールの挙動は未定義です。" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"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:6 +msgid "Externally Managed Environments" +msgstr "外部から管理される環境" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" +"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." +msgstr "" +"そのような環境下で従来の Python のパッケージングツール類を使おうと試みること" +"は、最もうまくいったときでも混乱を招く結果になり、最悪の場合には根底にあるオ" +"ペレーティングシステム全体を完全に破壊してしまうことにもなりかねません。この" +"ような問題を解決する上では、説明文書と互換性ガイドだけが頼りになります。" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" +"この仕様では ``EXTERNALLY-MANAGED`` というマーカファイルを定義しており、これ" +"によって Python をインストールする際に ``pip`` のような Python に特有のツール" +"群に対してインタプリタのデフォルトのインストール環境にパッケージを" +"インストールしたり取り除いたりしないように指示し、その代わりに、エンドユーザ" +"に対して :ref:`仮想環境 ` を使うようにガイドするべきで" +"す。" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" +"また、 Python 特有のパッケージマネージャがインタープリタ全体のコンテキストで" +"パッケージをインストールしようとしている場合に、外部のパッケージマネージャと" +"相互干渉を避け、また、外部のパッケージマネージャから導入されたソフトウェアを" +"破壊する危険を避けるであろうやり方でインストールすることができるように " +"``sysconifg`` の翻訳を標準化しています。" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "用語集" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" +"この仕様書で用いられる用語のいくつかには、それが置かれた文脈に従って複数の意" +"味を持つものがあります。明確性のために、この仕様書では以下の用語を特定の意味" +"で使用します:" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "配布物 " + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" +"短く言うと \"配布物 \" で、適切に協働した動作をするように理想的" +"に設計され、(この説明文書に適合する文脈で) Python インタープリタそのものを含" +"み、Python で書かれたソフトウェアであり他の言語で書かれたソフトウェアでもあ" +"る、さまざまな種類のソフトウェアの集合体。すなわち、これが \"Linux ディスト" +"ロ \" や \"バークレーソフトウェア配布物 \" といったフレーズで使われる意味です。" + +#: ../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/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" +"Python のパッケージングの文脈では、\"ディストリビューション \" " +"という用語は別の意味、つまり、 Python 言語で書かれたソフトウェアのひとつの部" +"品のソースコード配布パッケージまたはバイナリ配布パッケージ、即ち " +"``setuptools.dist.Distribution`` 乃至 \"sdist\" の意味での配布物という意味を" +"持つので、この文書では短縮された用語である \"ディストロ \" を使いま" +"す。混乱を避けるために、この文書では \"ディストリビューション " +"\" をそのままでは使わないことにします。 Python パッケージングの" +"意味で使う時は完全形の \"配布パッケージ \" または単に " +"\"パッケージ \" を使います (後述します)。" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" +"ディストロを提供する者 - ソフトウェアを収集して公開し、何であれ必要とされる修" +"正を加えるチームまたは企業 - は、その **配布者 ** です。" + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "パッケージ" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" +"インストールすることができ、Python 内で使うことができるソフトウエアの単位。つ" +"まり、これは Python 特有のパッケージングツールが :term:`配布パッケージ " +"` または単に \"配布物\" と呼びがちなものを参照していま" +"す; 口語的な省略形である \"配布物\" は Python Package Index の意味で使われま" +"す。" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" +"この説明文書は \"配布物 \" を Python モジュールを含んでいてインポー" +"ト可能なものの名前という意味では使いませんが、多くの場合、 配布パッケージは同" +"名のインポート可能な単一のパッケージから構成されています。" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" +"この説明文書では、\"パッケージ \" という言葉で (``.deb`` や " +"``.rpm`` ファイルのような) ディストロのパッケージマネージャがインストールする" +"単位を参照することはしません。必要な場合には \"ディストロのパッケージ\" など" +"と言い換えて使います。 (再掲になりますが、多くの場合には、 Python パッケージ" +"がディストロのパッケージとして出荷される場合には Python パッケージの名称に " +"``python-`` を付け加えます。)" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "Python 特有のパッケージマネージャ" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" +"Python パッケージング標準 を満足する形で Python " +"パッケージをインストール・アップグレード・削除するためのツール。最もよく知ら" +"れた Python 特有のパッケージマネージャは pip_ です; 他の例には、 " +"``setup.py`` コマンドを直接に使う方法と同様、古い `Easy Install コマンド " +"`_ が含まれます。" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" +"(``easy_install`` コマンドは、2021 年 1 月 23 日にリリースされた setuptools " +"のバージョン 52 で除去されています。)" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" +"(Conda_ は少々特別なケースです、というのは、 ``conda`` コマンドを使えば単に " +"Python パッケージだけではなくずっと多くのものをインストールすることができるか" +"らで、いくつかの意味ではディストロ 付属のパッケージマネージャにもっ" +"と似ていると言えるでしょう。 ``conda`` コマンドは一般的には Conda が作成した" +"環境の上でのみ動作するので、Python 特有のパッケージマネージャとして動作する場" +"合には、この説明文書における関心のほとんどは ``conda`` には適用されません。)" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "ディストロ パッケージマネージャ" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" +"当該ディストロのインストール済みインスタンス内でディストロ提供のパッケージを" +"インストール・更新・削除するためのツールで、 Python パッケージか非 Python " +"パッケージかに依らずインストールする能力を持つものであり、従って、一般的にそ" +"のツールに特有のインストール済みソフトウェアのデータベースで :ref:`インストー" +"ル済み配布物のデータベース ` とは無関係のものを" +"持つもの。例には ``apt`` ・ ``dpkg`` ・ ``def`` ・ ``rpm`` ・ ``pacman`` ・ " +"``brew`` を含みます。顕著な特徴としては、あるパッケージがディストロのパッケー" +"ジマネージャによってインストールされていた場合に、 Python 特有のパッケージマ" +"ネージャを満足させる方法でそのパッケージを削除したり更新したりすることが、一" +"般にディストロのパッケージマネージャの状態を不整合なまま放置するであろうとい" +"うことです。" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" +"この説明文書は、また、ある種の文脈ではディストロのパッケージマネージャのこと" +"を指し示すのに \"外部パッケージマネージャ \" や " +"\"システムのパッケージマネージャ \" のような言い回" +"しを用います。" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "シャドー " + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" +"インストール済みの Python パッケージをシャドー するというのは、シャ" +"ドーされたパッケージに由来するファイルをひとつも削除することなしに、インポー" +"ト時に別のパッケージを選好させることです。これは ``sys.path`` に複数のエント" +"リーを要求します: パッケージ A 2.0 がある ``sys.path`` エントリに ``a.py`` モ" +"ジュールをインストールし、かつ、パッケージ A 1.0 が ``a.py`` モジュールを後続" +"の ``sys.path`` エントリにインストールしている時に、 ``import a`` が前者のモ" +"ジュールを返し、これを A 2.0 が A 1.0 をシャドーしたと言います。" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "この仕様には二つの部分があります。" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" +"第一に、 **Python インタープリタの配布を行う者が、そのインタープリタをPython " +"の外側にある手段によって管理されるパッケージを持ち** 、従って、 pip のような " +"Python 特有のツール類が、特別にオーバーライドされない限りは、当該インタープリ" +"タのグローバルな ``sys.path`` に存在するインストール済みパッケージを、いかな" +"る意味でも変更 (追加、更新・ダウングレード、あるいは削除) するべきではないと" +"いう印を付ける方法を記述しています。また、代替手段としての仮想環境をどのよう" +"に使うのかを配布者 が指示する手段を提供します。" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" +"これは、オプトインのメカニズムです: デフォルトでは、アップストリームのソース" +"からコンパイルされた Python インタープリタは、そのようにマークを付けられるこ" +"とはなく、また、セルフコンパイルされたインタープリタやディストロのものを使っ" +"て ``pip install`` を実行すると、それまでと同様に動作するはずです。" + +#: ../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 "" +"第二に、パッケージをインタープリタのグローバルコンテキスト (マークされていな" +"いインタープリタの場合やマークをオーバーライドした場合) にインストールする際" +"に、 **Python 特有のパッケージマネージャが修正・削除しても構わないのは、今ま" +"さにファイル群を作成しようとしている sysconfig スキームのディレクトリ内にある" +"ものだけである** というルールを設定します。これによって、 Python インタープリ" +"タの配布者 がふたつのディレクトリをセットアップすることを許し、" +"つまり、一つは自分で管理しているパッケージ群 (のためのディレクトリ) でもう一" +"つはエンドユーザがインストールした管理対象外のパッケージ群 (のためのディレク" +"トリ) で、管理対象外のパッケージをインストールしたとしても外部パッケージマ" +"ネージャ が管理しているファイル群が削除 (または上" +"書き) されることがないことを保証します。" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" +"外部パッケージマネージャ を用いるものとしてイン" +"タープリタにマークを付ける" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" +"Python 特有のパッケージインストーラ (つまり pip のようなツール - apt のような" +"外部ツールではない) がある Python コンテキストにパッケージをインストールする" +"前に、デフォルトで以下の項目を確認するべきです:" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" +"仮想環境の外側で動作しているのか？ ``sys.prefix == sys.base_prefix`` が成立す" +"るか否かで判断することができます。" + +#: ../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 "" +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())`` で同定され" +"るディレクトリの中に ``EXTERNALLY-MANAGED`` ファイルが存在するか否か？" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" +"両方の条件が真であれば、仮想環境の外側ではこの Python インタープリタのディレ" +"クトリへパッケージをインストールすることが無効にされていることを示すエラー" +"メッセージとともに、インストーラは終了するべきです。" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" +"インストーラは、コマンドライン上の ``--break-system-packages`` フラグのよう" +"に、ユーザがこれらのルールをオーバーライドする方法を持っているべきです。この" +"オプションはデフォルトでは無効であるべきで、有効にするとリスクを伴うことを含" +"意する何らかのメッセージを伴うべきです。" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" +"``EXTERNALLY-MANAGED`` ファイルは INI スタイルのメタデータファイルで、標準ラ" +"イブラリの configparser_ モジュールでパースできることを意図しています。この" +"ファイルが UTF-8 エンコーディングを用いて " +"``configparser.ConfigParser(interpolation=None)`` によってパースできて、か" +"つ、ファイル内に ``[externally-managed]`` セクションがあれば、インストーラは" +"このファイル内で指定されたエラーメッセージを探して、エラーの一部として出力す" +"るべきです。 ``locale.getlocale(locale.LC_MESSAGES)`` によって返されるタプル" +"の最初の要素が ``None`` ではない場合には、 ``Error-`` の後に言語コードが続く" +"名前を持つキーの値として提供されるエラーメッセージを探すべきです。そのような" +"キーが存在しない場合でも、言語コードがアンダースコアかハイフンを含むのであれ" +"ば、 ``Error-`` の後に言語コードのアンダースコアかハイフンの前までの部分が続" +"くキーを探すべきです。これらのいずれも発見できない場合や、言語コードが " +"``None`` の場合には、単に ``Error`` というキーを探すべきです。" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" +"インストーラがファイル内のエラーメッセージを見つけられない (ファイルをパース" +"できないか、適切なエラーキーが存在しないのいずれか) 時は、インストーラは自身" +"の内部に予め定義されたエラーメッセージ、それは当該パッケージをインストールす" +"るためにユーザが仮想環境を作成することを示唆するものであるべきですが、それを" +"使うべきです。" + +#: ../source/specifications/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 an ``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 "" +"Python 特有のものではないパッケージマネージャで、その Python パッケージの " +"``sys.path`` 内にあるライブラリを管理するものを持っているソフトウェア配布者" +"は、一般的に、標準ライブラリのディレクトリに ``EXTERNALLY-MANAGED`` ファイル" +"を置いた状態で出荷するべきです。例えば、 Debian では、次に示すような何かで構" +"成された ``/usr/lib/python3.9/EXTERNALLY-MANAGED`` ファイルを同梱して出荷して" +"も構いません" + +#: ../source/specifications/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" +"パッケージのインストールを試みるユーザ向けに役に立つとともにディストロに適合" +"した情報を適合すること。オプションとして、同一ファイル内に提供されるトランザ" +"クション:" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" +"作成後には更新できない単一アプリケーションのコンテナイメージのようなある種の" +"コンテキストでは、配布者 は、このルールを手動でオーバーライドせ" +"ざるを得ないということがなくてもユーザが何であれ彼らの望むものを (その時に) " +"インストールできるように、 ``EXTERNALLY-MANAGED`` ファイルを同梱しない選択を" +"行っても構いません。" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "ターゲットとなる ``sysconfig`` スキームだけを書く" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" +"通常は、 Python パッケージインストーラは、標準ライブラリパッケージの " +"``sysconfig`` によって返されるスキームにあるディレクトリへインストールを行い" +"ます。普通は、これは、 ``sysconfig.get_default_scheme()`` が返すスキームのこ" +"とですが、設定 (例えば ``pip install --user``) に基づいて異なるスキームを用い" +"ることもあります。" + +#: ../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 "" +"インストーラが ``sysconfig`` スキームへインストールする時はいつでも、そのス" +"キームの外側のファイルをインストーラが決して変更したり削除したりするべきでは" +"ないことをこの仕様が宣言しています。例えば、パッケージのアップグレードを行う" +"時にそのパッケージがスキームの外側のディレクトリ (おそらく別のスキームのも" +"の) にすでにインストールされているなら、既存のファイル群をそのままにしておく" +"べきです。" + +#: ../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/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 "" +"インストーラが ``sysconfig`` スキームの外側の場所 (即ち ``pip install --" +"target``) へインストールしようとしているなら、このサブセクションは適用されま" +"せん。" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "ディストロへの推奨" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" +"この節は規範的なものではありません。特に他の理由がなければディストロが従うべ" +"きであると信じられるベストプラクティスを提供するものです。" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "インストールされたものを外部管理のものとしてマークする" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" +"ディストロは、その ``stdlib`` ディレクトリ内に ``EXTERNALLY-MANAGED`` ファイ" +"ルを作成するべきです。" + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "仮想環境へ向かうユーザへのガイド文書" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" +"このファイルは、ディストロのパッケージマネージャを使ってシステムワイドのパッ" +"ケージをインストールする方法と仮想鑑賞を構築する方法の両方を示す、役に立ち、" +"かつ、ディストロに適合したエラーメッセージを含んでいるべきです。もし、その" +"ディストロが ``python3`` コマンドは利用できる (かつ、とりわけ ``pip`` か " +"``get-pip`` が利用できる) が、 ``python3 -m venv`` は動作しない状態で使われる" +"ことが多いのであれば、当該メッセージは、 ``python3 -m venv`` を正しく動作させ" +"るにはどうすれば良いかをはっきりと示すべきです。" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" +"Python 言語で書かれたアプリケーションをインストールするツールである " +"packaging pipx_ を採用して、エラーの中で示唆することを検討してください。 " +"pipx はそのアプリケーションだけのための仮想環境を自動的に構築しますし、何らか" +"の Python 言語で書かれたソフトウェア (であって、ディストロ側では利用可能では" +"ないもの) をインストールしたいけれども自身は Python ユーザではないエンドユー" +"ザにとってはずっと良いデフォルト動作です。 Packaging pipx がディストロ側で準" +"備されていれば、システム側のパッケージ群を破壊することを *避ける* ために " +"``pip install --user --break-system-packages pipx`` を使うようにユーザに指示" +"すると言う皮肉を避けることができます。このように整えることで、ディストロ側" +"パッケージとエンドユーザ用 Python 環境 (例えば、 Fedora での ``python3`` や " +"Debian での ``python3-full`` ) がともに pipx に依存するようにすることができま" +"す。" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "コンテナイメージ内のマーカーファイルを維持する" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" +"単一アプリケーションのコンテナ用の公式イメージ (即ち Docker コンテナイメー" +"ジ) を作成するようなディストロは、 ``EXTERNALLY-MANAGED`` ファイルを維持すべ" +"きで、さらに言えば、ユーザがそのイメージなでパッケージのアップデートをインス" +"トールしたとしても (``RUN apt-get dist-upgrade`` のようなものを考えてみてほし" +"い) 失われることのないようなやり方で行うのが望ましいことです。" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "ディストロとローカルのディレクトリを別々に作成する" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" +"ディストロは、ディストロがインストールしたパッケージのためのものと、ローカル" +"のシステム管理者がインストールしたパッケージのためのものというふたつの別々の" +"パスをシステム側に持っているインタープリタの ``sys.path`` に置くべきであり、" +"また、 ``sysconfig.get_default_scheme()`` が後者のパスを指し示すように設定す" +"るべきです。こうすることで、pip のようなツール類がディストロ側でインストール" +"したパッケージを修正してしまうことがなくなります。ローカルのシステム管理者用" +"のパスは ``sys.path`` 内でディストロ側のパスの前にくるべきで、そうすることで" +"ローカルにインストールされたものがディストロ側のパッケージよりも選好されるよ" +"うになります。" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" +"例えば、Fedora や Debian (およびその派生物) は共に、ローカルにインストールさ" +"れたパッケージ用に ``/usr/local`` を使い、ディストロがインストールしたパッ" +"ケージ用に ``/usr`` を用いることでこの分離を実装しています。Fedora では、 ``/" +"usr/local/lib/python3.x/site-packages`` 対 ``/usr/lib/python3.x/site-" +"packages`` です。 (Debian では ``/usr/local/lib/python3/dist-packages`` 対 " +"``/usr/lib/python3/dist-packages`` をローカルにコンパイルされた Python イン" +"タープリタ用にさらに分離して使っています: もしアップストリームの Python をビ" +"ルドして ``/usr/local/bin`` にインストールしていれば、 ``/usr/local/lib/" +"python3/site-packages`` を見るでしょうし、 Debian ではローカルにビルドされた" +"インタープリタ経由でインストールされたパッケージがディストロ側のインタープリ" +"タ用の ``sys.path`` 上には出現しないことを確実にしようと願っています。)" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" +"``/usr/local`` 対 ``/usr`` の分離が、 ``PATH`` 環境変数が典型的に ``/usr/" +"local/bin:/usr/bin`` を含んでいて、デフォルトで非ディストロのソフトウェアが " +"``/usr/local`` にインストールされることのアナロジーになっていることに注目して" +"ください。この分離は、 `recommended by the Filesystem Hierarchy Standard`__ " +"です。" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" +"これを行うにはふたつの方法があります。ひとつは、Python ライブラリを直接にビル" +"ドしてパッケージしようとしている (例えば、使っているパッケージングヘルパーが " +"wheel をアンパックするか、または、 ``setup.py install`` を呼び出す場合) 時" +"に、 ``sys.path`` には含まれているけれども ``sysconfig`` スキームには入ってい" +"ないようなディレクトリを使って実行するようにそれらツール群を調整することで" +"す。" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" +"もうひとつは、パッケージのビルド中とインストール済みのシステムで実行する時と" +"でデフォルトの ``sysconfig`` スキームを変えるように調整することです。 (アクセ" +"プトされ実装されればですが) bpo-43976_ からの ``sysconfig`` カスタマイズフッ" +"ク群がこれを容易にするでしょう: パッケージングツールに環境変数他のなんらかの" +"検出可能な設定項目を設定させ、 ``get_preferred_schemes`` 関数がパッケージビル" +"ドの中から呼ばれた場合には異なるスキームを返すようにするのです。そうすれば、 " +"``pip install`` をディストロパッケージングの一部として使用できるようになりま" +"す。" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" +"我々は、 pip が指定されたスキームで走るように指示する ``--scheme=...`` " +"オプションを追加することを提案します。(現在の pip がスキームを決定する方法に" +"ついては後述の `Implementation Notes`_ を参照してください。) これが利用可能に" +"なり次第、ローカルのテストやおそらく実際のパッケージングで、 " +"(``get_preferred_schemes`` をバイパスして) 明示的にディストロ側の場所へ" +"パッケージをインストールするために ``pip install --scheme=posix_distro`` のよ" +"うな形で実行することができるようになるでしょう。また、もし本当に必要であれば" +"、 pip を使ってシステム側が管理するディレクトリからパッケージを削除するため" +"に ``pip uninstall --scheme=posix_distro`` を使うことさえできるでしょう。" + +#: ../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 "" +"pip でパッケージをインストールするには、 ``EXTERNALLY-MANAGED`` マーカーファ" +"イルを抑止して pip を実行できるようにするか、コマンドラインでオーバーライドす" +"るかのいずれかが必要です。コンテナイメージ内で作業している時は、ビルドのため" +"に chroot した環境においても同じ方法でマーカーファイルを抑止したくなるかもし" +"れません。" + +#: ../source/specifications/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" +"これらの設定 (ビルド環境ではマーカーファイルを抑止し、 " +"``get_preferred_schemes`` が自動的にディストロのスキームを返すようにするこ" +"と) を自動で行うことのアドバンテージは、素のままの ``pip install`` であっても" +"パッケージビルド内で動作することで、それは一般的にはアップストリームのビルド" +"スクリプトで内部で偶々 ``pip install`` を呼ぶものでも修正なしで正しく動作する" +"ということです。もちろん、パッケージングプロセスが常に ``pip install --" +"scheme=posix_distro --break-system-packages`` を呼び出すようにすることもでき" +"ますし、それも動作します。" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" +"ここでの最善のアプローチは、ディストロの慣習やパッケージング機構に大きく依存" +"します。" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" +"同様に、 ``sysconfig`` パスでインポート可能な Python のコード向けのものではな" +"いもの - つまり、 ``include`` ・ ``platinclude`` ・ ``scripts`` ・ ``data`` " +"- にもふたつの変種があって、ひとつはディストロ側でパッケージしたソフトウェ" +"ア、もう一つはローカルにインストールされたソフトウェアですが、ディストロはこ" +"れらのどちらでも使用できるように設定されているべきです。例えば、典型的な FHS " +"を遵守するディストロでは、 ``/usr/local/include`` をデフォルトのスキームの " +"``include`` 用に、 ``/usr/include`` をディストロ側でパッケージかしたヘッダ" +"ファイル用に使って、両方をコンパイラのサーチパスに含めておくことになるでしょ" +"うし、また、 ``/usr/local/bin`` をデフォルトのスキームの ``scripts`` 用に、 " +"``/usr/bin`` をディストロ側のパッケージのエントリポイント用に使って、両方を " +"``$PATH`` に含めておくでしょう。" + +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" +msgstr "実装に関する覚書" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" +"この節は規範的なものではなく、仕様と潜在的な実装の両方に関連する覚え書きを含" +"んでいます。" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" +"現在 (2021年5月時点) 、 pip はターゲットとなる ``sysconfig`` スキームを選択す" +"る方法を直接には外部に見せていませんが、インストールの際にルックアップする３" +"個の方法があります:" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "``pip install``" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" +"``sysconfig.get_default_scheme()`` を呼び出す方法で、 (アップストリームの " +"CPython や今使われているほとんどのディストロでは) 普通は " +"``get_preferred_scheme('prefix')`` と同じ結果になるもの。" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "``pip install --prefix=/some/path``" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "``sysconfig.get_preferred_scheme('prefix')`` を呼び出す。" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "``pip install --user``" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "``sysconfig.get_preferred_scheme('user')`` を呼び出す。" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" +"最後に、 ``pip install --target=/some/path`` でスキームをルックアップすること" +"なしに ``/some/path`` を書きます。" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" +"Debian は、現在、 (``VIRTUAL_ENV`` 環境変数を確認することを含む) いくつかの発" +"見的な解法を使った `patch to change the default install location inside a " +"virtual environment`__ を入れていて、仮想環境内で使われるディレクトリが " +"``dist-packages`` ではなく ``site-packages`` に留まるようになっています。これ" +"は、この提案に特に影響を与えません、というのは、そのパッチの実装は、実際には" +"デフォルトの ``sysconfig`` スキームを変更するわけではなく、特に " +"``sysconfig.get_path(\"stdlib\")`` の結果を変更しないからです。" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" +"Fedora は、現在、`patch to change the default install location when not " +"running inside rpmbuild`__ を適用していて、「ふたつのシステムワイドな" +"ディレクトリ」のアプローチを使っています。これは、概念としては、 " +"``sysconfig`` スキームを変更するものとしてではなく ``distutils`` への" +"ソースコードパッチとして実装されていることを除けば、 bpo-43976_ によって可視" +"化されたある種のフックです。" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" +"上記の ``is_virtual_environment`` の実装は、 ``EXTERNALLY-MANAGED`` ファイル" +"をロードしてそこからエラーメッセージを探す論理と同様に、実装を中央一括管理に" +"するために標準ライブラリ (順に ``sys`` と ``sysconfig``) に追加されるかもしれ" +"ませんが、まだそのようにはなっていません。" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "著作権" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" +"この説明文書は、パブリックドメインに置かれるか、または、 CC0-1.0-Universal ラ" +"イセンスの下に置かれるかですが、いずれにしてもかなり寛大なものです。" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "2022年6月: :pep:`668` を通じてこの仕様が承認されました。" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "ファイルのヤンク " + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "この仕様は、元々は :pep:`592` で定義されました。" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" +":pep:`592` は、 HTML と JSON のインデックス API への変更を含んでいます。これ" +"らの変更は、 :ref:`HTML - プロジェクトの詳細 ` と :ref:`JSON - プロジェクトの詳細 ` の下で :ref:`simple-repository-api` で文書化されています。" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" +"シンプルなリポジトリの中のリンク群は、値を持たないか任意の文字列を値に取る " +"``data-yanked`` アトリビュートを持っていても **構いません** 。 ``data-" +"yanked`` アトリビュートが存在していれば、この特定のリンクによって指し示された" +"ファイルが \"ヤンクされた \" ものだと解釈される **べきであって** 、特" +"定のシナリオ下を除けば一般的にはインストーラによって選択されるべきものではあ" +"りません。" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" +"``data-yanked`` アトリビュートの値は、もし値が存在するなら、そのファイルがヤ" +"ンクされた理由を表現する任意の文字列です。シンプルなリポジトリ API を処理する" +"ツール類は、エンドユーザ向けにその文字列を表示しても **構いません** 。" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" +"ヤンクされたアトリビュートは一旦設定されると変更できないというわけではなく、" +"将来の時点で廃止されても構いません (そして、一旦廃止されても再設定することが" +"できます) 。そういうことですので、 API ユーザは、ヤンクされたファイルが \"ヤ" +"ンク解除\" され (さらに再びヤンクされ) ることに対処でき **なければなりません" +"** 。" + +#: ../source/specifications/file-yanking.rst:40 +msgid "Installers" +msgstr "インストーラ類" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" +"ユーザにとって望ましい経験とは、あるファイルが一旦ヤンクされたら、人間側が今" +"まさにヤンクされたファイルを直接にインストールしようと試みている時、まるでそ" +"のファイルが削除されたかのように失敗することです。しかしながら、その人が少し" +"前の時点で試みた場合には、今回はコンピュータが機械的にオリジナルの順序にした" +"がって今まさにヤンクされたファイルをインストールし、それがヤンクされたファイ" +"ルなどではなかったかのように振る舞うことです。" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" +"インストーラは、ヤンクされたバージョン以外のもので選択上の制約を満足すること" +"が可能なら、ヤンクされたリリース群を **無視しなければならず** 、要求が全く満" +"たされないことを意味する場合でさえもヤンクされたリリースを **拒否しても構いま" +"せん** 。実装では、上記の意図を汲んだポリシーで、かつ、 \"新しい\" 依存関係を" +"訳されたリリースやファイルに課すことを避けポリシーを **選択するべきです** 。" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" +"これが意味するものは、特定のインストーラの全体的な使い方に一番うまく合致する" +"方法を決定するということで、インストーラの裁量に任されています。" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" +"ヤンクされたファイル群は、それが (``.*`` のような範囲を構成するいかなる修正子" +"も付いていない) ``==`` か ``===`` を使って特定のバージョンに \"ピン留め\" さ" +"れたバージョン指定子に合致する唯一のファイルでない限り、常に無視されます。そ" +"れ以外の場合、このバージョン指定子とのマッチングは、ローカルバージョン・ゼロ" +"でのパディング・その他のような事柄について :ref:`バージョン指定子仕様 " +"` にしたがって行われるべきです。" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" +"ヤンクされたファイル群は、 (``Pipfile.lock`` や ``poetry.lock`` のような) " +"ロックファイルがインストールされるべきものとして指定しているものに合致する唯" +"一のファイル出ない限り、常に無視されます。この場合には、ヤンクされたファイル" +"は、何らかの入力ファイルやコマンドからそのロックファイルを作成したり更新した" +"りする場合には、 **使われるべきではありません** 。" + +#: ../source/specifications/file-yanking.rst:73 +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 "" +"あるインストーラがヤンクされたファイルをいつインストールするのかを決めるにあ" +"たって、ヤンクされたファイルをインストールすると決定した時にインストーラが警" +"告を **発出するべきです** 。そのような警告は、そのファイルがヤンクされた理由" +"についてユーザにより詳しいフィードバックを提供するために、 (もし値があれば) " +"``data-yanked`` アトリビュートの値を **使っても構いません** 。" + +#: ../source/specifications/file-yanking.rst:81 +msgid "Mirrors" +msgstr "ミラー" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "ミラーは、ヤンクされたファイルを次の二つの方法のうちの一つで扱います:" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" +"\"アクティブ\" なヤンクされたものではないファイル群だけを見せるリポジトリの" +"ビューを提供して、シンプルなリポジトリ API から (ヤンクされたファイル群を) 完" +"全に排除する選択をしても構いません。" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" +"ヤンクされたファイルも表示するとともに、 ``data-yanked`` アトリビュートをもミ" +"ラーするという選択をしても構いません。" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" +"ミラーは、 ``data-yanked`` アトリビュートを同時にミラーするのでなければヤンク" +"されたファイルを **ミラーしてはいけません** 。" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "``glob`` のパターン" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" +"PyPA 仕様のいくつか、例えば :ref:`pyproject.toml の license-files ` は、あるワイルドカードや文字範囲を含む文字列をファイル名" +"やディレクトリ名にマッチさせるために、ある種の *glob パターン* を受け付けま" +"す。この仕様では、どのようなパターンが受け入れ可能であるのか、や、それらがど" +"のように扱われるべきか、を定義します。" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "正当な glob パターン" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" +"PyPA の目的 には、 *正当な glob パターン* は、以下に指定する通り、" +"ファイルシステム上のエンティティに対して合致する文字列でなければなりません。" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" +"英数字、アンダースコア (``_``) 、ハイフン (``-``) およびドット (``.``) は、文" +"字通りにマッチされなければなりません。" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" +"glob の特殊文字: ``*`` 、 ``?`` 、 ``**`` 、および、文字範囲: 文字通りにマッ" +"チさせる文字を含む ``[]`` がサポートされていなければなりません。 ``[...]`` の" +"中では、ハイフンは、ロケールに依存しない範囲 (例えば、 Unicode のコードポイン" +"トに基づく順序を備えた ``a-z``) を示します。先頭または末尾のハイフンは文字通" +"りにマッチします。" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" +"パスの区切り文字は、フォワードスラッシュ文字 (``/``) でなければなりません。" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" +"パターンは常に *相対パス* で参照され、例えば、 :file:`pyproject.toml` 内で使" +"われるときには、パターンは常にそのファイルを含むディレクトリに対する相対パス" +"であるべきです。したがって、先頭のスラッシュ文字は使ってはなりません。" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "親ディレクトリ指示子 (``..``) を使ってはなりません。" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" +"この仕様でカバーされていない文字または文字の並びは、すべて不当なものです。プ" +"ロジェクトは、そのような値を使用してはなりません。glob パターンを消費する " +" ツール類は、不当な値をエラーと共に拒絶するべきです。" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" +"リテラルのパス (例えば :file:`LICENSE`) は正当な glob で、これも定義できると" +"いうことになります。" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "glob パターンを消費するツール群:" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" +"それぞれの値を glob パターンであるものとして取り扱わなければならず、また、パ" +"ターンが不当な glob 文法を含んでいればエラーを発生させなければなりません。" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" +"個々のユーザ指定のパターンに合致するファイルが一つもない時は、エラーを発生さ" +"せなければなりません。" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "正当な glob パターンの例:" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "不当な glob パターンの例:" + +#: ../source/specifications/glob-patterns.rst:74 +msgid "Reference implementation in Python" +msgstr "Python における参照実装" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" +"ファイルシステムに対するパターンマッチングの大部分を Python の標準ライブラリ" +"の :mod:`glob` モジュールに引き渡すことは可能です。しかしながら、追加の正当性" +"確認を実行することが必要です。" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "下に示すソースコードは、単純な参照実装としてのものです:" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "PyPA 仕様" + +#: ../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/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "インデックスにホストされた証明 " + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "この仕様は、元々は :pep:`740` で定義されました。" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" +":pep:`740` は、 HTML と JSON のインデックス API に対する変更を含みます。これ" +"らの変更は、 :ref:`simple-repository-api-base` の下の :ref:`simple-" +"repository-api` や :ref:`json-serialization` の中で文書化されています。" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "エンドポイントの変更をアップロードする" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" +"\"レガシー \" なアップロード API は標準化されていません。どのように証" +"明がアップロードされるのかについては、 `PyPI のアップロード API に関するド" +"キュメント `_ を見てください。" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "証明オブジェクト" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" +"証明書 オブジェクトは、いくつかの必須のキーを伴う JSON オブジェ" +"クトです; アプリケーションや署名者は、すべての明示的に列挙されたキーが提供さ" +"れている限りは追加のキーを含めておいても構いません。証明書 に要" +"求されるレイアウトは、下記の仮想ソースコードの形で提供されています。" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" +"``transparency_entries`` 内の各オブジェクト向けの完全なデータモデル" +"は、 :ref:`付属書 ` で提供されています。証明書 オブ" +"ジェクトは、一つ以上の透明ログエントリを含む **べき** であり、 (:rfc:`3161` " +"タイムスタンプ局 ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" +"もっと先進的な実際上の情報についてはこのサイトの :doc:`説明文書群 ` を、あるいは、特定の話題の説明や背景については :doc:`議論 ` を見てください。" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" +":ref:`hatch` ・ :ref:`flit` ・ :ref:`pdm` ・ :ref:`poetry` のように、単一のコ" +"マンドラインインタフェースでプロジェクト管理もパッケージングもできるパッケー" +"ジングツールについて検討しましょう。" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "ノート" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" +"``__init__.py`` ファイルなしの Python パッケージを作ることも技術的には可能で" +"すが、そのようなものは :doc:`名前空間パッケージ ` と呼ばれるもので、 (このチュートリアルでは取り扱わない) **先進的な" +"話題** であると見做されています。Pythonのパッケージングについてやり始めたばか" +"りなのであれば、 *通常のパッケージ* と (空のファイルだとしても) " +"``__init__.py`` から離れないことをお薦めします。" + +#~ msgid "" +#~ "This specification was originally defined in :pep:`518` and :pep:`621`." +#~ msgstr "この仕様は、元々は :pep:`518` 及び :pep:`621` で定義されました。" + +#~ msgid "" +#~ "Refer to the `pkg_resources documentation `__ for more details." +#~ msgstr "" +#~ "さらに詳しい情報については、 `pkg_resources 説明文書 `__ を参照してください。" + +#~ msgid "" +#~ "A complete working example of two pkg_resources-style namespace packages " +#~ "can be found in the `pkg_resources namespace example project`_." +#~ msgstr "" +#~ "pkg_resources 型の名前空間パッケージの動作可能な二つの例が `pkg_resources " +#~ "型名前空間例示プロジェクト`_ で見つかるはずです。" + +#~ msgid "" +#~ "In addition to the general response metadata, the project detail ``meta`` " +#~ "dictionary **MAY** also include the following:" +#~ msgstr "" +#~ "一般的な応答メタデータに加えて、プロジェクト詳細の ``meta`` 辞書には、以下" +#~ "のものを含めても **構いません** :" + +#~ msgid "The ``project-status-reason`` key was added with API version 1.4." +#~ msgstr "" +#~ "``project-status-reason`` キーは、 API バージョン 1.4 で追加されました。" + +#~ msgid "" +#~ "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." +#~ msgstr "" +#~ "RECORD.jws は、デジタル署名のために使われます。これについては RECORD では" +#~ "触れられません。" + +#~ 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 では触れられませ" +#~ "ん。" + +#~ msgid "Signed wheel files" +#~ msgstr "署名済み wheel ファイル" + +#~ 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::" +#~ msgstr "" +#~ "Wheel ファイルは、デジタル署名を可能にした拡張 RECORD ファイルを含みま" +#~ "す。 PEP 376 の RECORD は、 md5sum の代わりにセキュアなハッシュ値 " +#~ "``digestname=urlsafe_b64encode_nopad(digest)`` (末尾に = 文字を追加しない " +#~ "url セーフな base64 エンコード) を二つ目のカラムとするように修正されまし" +#~ "た。生成された .pyc ファイルなども含むすべての可能なエントリにハッシュ値が" +#~ "付加されていますが、 RECORD は自身のハッシュ値を含むことができないので例外" +#~ "です。例えば::" + +#~ 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." +#~ msgstr "" +#~ "署名用のファイルである RECORD.jws と RECORD.p7s は、 RECORD ファイルが作成" +#~ "された後にしか追加できないので、RECORD ファイル内で言及されることは全くあ" +#~ "りません。アーカイブの中の他のファイルはすべて、RECORD ファイル内に正しい" +#~ "ハッシュ値を持たなければならず、そうでなければインストールに失敗します。" + +#~ 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:" +#~ msgstr "" +#~ "JSON ウェブ署名が使われる場合には、ひとつかそれ以上の JSON Web Signature " +#~ "JSON Serialization (JWS-JS) 署名が RECORD ファイルの隣にある RECORD.jws " +#~ "ファイルの中に保存されます。 RECORD ファイルの SHA-256 ハッシュ値を署名の " +#~ "JSON ペイロードに含むことで RECORD ファイルに署名するために JWS が使われま" +#~ "す:" + +#~ msgid "(The hash value is the same format used in RECORD.)" +#~ msgstr "" +#~ "(ハッシュ値の書き方のフォーマットは RECORD で使われるものと同じです。)" + +#~ msgid "" +#~ "If RECORD.p7s is used, it must contain a detached S/MIME format signature " +#~ "of RECORD." +#~ msgstr "" +#~ "RECORD.p7s を使う場合は、このファイルに RECORD ファイルに関する分離型の S/" +#~ "MIME 署名を入れておかなければなりません。" + +#~ 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." +#~ msgstr "" +#~ "wheel インストーラはデジタル署名を理解することを要求されてはいませんが、 " +#~ "RECORD ファイル内のハッシュ値が展開されたファイル内容に対して妥当であるこ" +#~ "とを検証しなければなりません。インストーラが RECORD ファイルに対するハッ" +#~ "シュ値を確認する際には、別途用意された署名検証プログラムは RECORD ファイル" +#~ "が署名に対して妥当であることだけを確認すれば十分です。" + +#~ msgid "See" +#~ msgstr "以下を参照のこと" + +#~ msgid "https://datatracker.ietf.org/doc/html/rfc7515" +#~ msgstr "https://datatracker.ietf.org/doc/html/rfc7515" + +#~ msgid "" +#~ "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" +#~ "serialization-01" +#~ msgstr "" +#~ "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" +#~ "serialization-01" + +#~ msgid "https://datatracker.ietf.org/doc/html/rfc7517" +#~ msgstr "https://datatracker.ietf.org/doc/html/rfc7517" + +#~ msgid "" +#~ "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" +#~ msgstr "" +#~ "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" + +#~ msgid "Why does wheel include attached signatures?" +#~ msgstr "なぜ wheel は添付された署名を持つのか？" + +#~ 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." +#~ msgstr "" +#~ "添付された署名は、アーカイブと一体のものとして転送されるので、分離署名より" +#~ "も便利です。個々のファイルが署名されているだけなので、アーカイブを圧縮し直" +#~ "しても署名が無効にならず、また、アーカイブ全体をダウンロードしなくても個々" +#~ "のファイルの検証を行うことができます。" + +#~ msgid "Why does wheel allow JWS signatures?" +#~ msgstr "なぜ wheel は JWS 署名を許容するのか？" + +#~ msgid "" +#~ "The JOSE specifications of which JWS is a part are designed to be easy to " +#~ "implement, a feature that is also one of wheel's primary design goals. " +#~ "JWS yields a useful, concise pure-Python implementation." +#~ msgstr "" +#~ "JWS がその一部を構成する JOSE の仕様は実装を容易にするように設計されてお" +#~ "り、その性質は wheel の基本的な設計目標のひとつでもあります。 JWS は使いや" +#~ "すくて簡潔な純 Python の実装をもたらします。" + +#~ msgid "Why does wheel also allow S/MIME signatures?" +#~ msgstr "なぜ wheel は S/MIME 署名をも許容するのか？" + +#~ msgid "" +#~ "S/MIME signatures are allowed for users who need or want to use existing " +#~ "public key infrastructure with wheel." +#~ msgstr "" +#~ "S/MIME 署名は、既存の公開鍵基盤を wheel でも採用する必要があるか、または、" +#~ "採用したいユーザのために許容されています。" + +#~ msgid "" +#~ "Signed packages are only a basic building block in a secure package " +#~ "update system. Wheel only provides the building block." +#~ msgstr "" +#~ "署名されたパッケージは、セキュアなパッケージ更新システムを構成するひとつの" +#~ "ビルディングブロックであるというだけのものです。 Wheel としては、単にビル" +#~ "ディングブロックを提供するだけです。" + +#~ msgid "The license expressions for these projects are:" +#~ msgstr "これらのプロジェクトに対するライセンス条項は:" + +#~ msgid "TUF Support - PEP 458" +#~ msgstr "TUF サポート - PEP 458" + +#~ 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." +#~ msgstr "" +#~ ":pep:`458` は、すべての API 応答がハッシュ可能で、リポジトリのルートからの" +#~ "相対パスによって一意に識別できることを要求しています。シンプル API リポジ" +#~ "トリでは、ターゲットのパスは、我々の API のルート (例えば、 PyPI における " +#~ "``/simple/``) です。標準の HTTP クライアントを使う代わりに TUF クライアン" +#~ "トを使って API にアクセスする時にはこれが試練を生み出しますが、それという" +#~ "のは、ハッシュが相異なるような複数の異なる表現形式をターゲットが持っている" +#~ "かもしれないという事実を TUF クライアントが扱えないからです。" + +#~ 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 "" +#~ ":pep:`458` は、どんなターゲットパスがシンプル API 向けであるべきかについて" +#~ "指定していませんが、 TUF はターベットパスが \"ファイルライク \" であることを要求し、換言すれば、 ``simple/PROJECT/.`` のようなパス" +#~ "は技術的にはディレクトリを指し示しているので受け入れ不可能です。" + +#~ 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." +#~ msgstr "" +#~ "欠点を補う取り柄は、シンプル API から持ってきた URL にターゲットパスが実際" +#~ "に *合致していなければならないということはない* ことで、取得する必要のあ" +#~ "る URL の実際の形への変換の方法を取得したコードが知っていることが魔法の印" +#~ "形になり得ます。これと同じことが、 ``Accept`` ヘッダのような実際の HTTP リ" +#~ "クエスト他の側面についても当てはまります。" + +#~ 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." +#~ msgstr "" +#~ "結局、あるディレクトリをファイル名に対応させる方法を解明することはこの仕様" +#~ "のスコープの外にあります (しかし :pep:`458` のスコープの中にはあるでしょ" +#~ "う) が、この仕様では、 :pep:`458` のメタデータの中にこれをどれほど正確に表" +#~ "現するのかについての決断を行うことを遅延させているのです。" + +#~ 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``." +#~ msgstr "" +#~ "しかしながら、 :pep:`458` を実装しようと試みる pip に対する現在の WIP ブラ" +#~ "ンチは、 ``simple/PROJECT/index.html`` のようなターゲットパスを使っている" +#~ "ようです。これは、何か ``simple/PROJECT/vnd.pypi.simple.vN.Format`` のよう" +#~ "なものを使うことで、 API のバージョンやシリアル化フォーマットを包含するよ" +#~ "うに修正できるかもしれません。それで、 v1 の HTML フォーマットは ``simple/" +#~ "PROJECT/vnd.pypi.v1.html`` のように、 v1 の JSON フォーマットは ``simple/" +#~ "PROJECT/vnd.pypi.simple.v1.json`` のようになることでしょう。" + +#~ 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." +#~ msgstr "" +#~ "このケースでは、 ``text/html`` が ``application/vnd.pypi.simple.v1+html`` " +#~ "へのエイリアスであることから、 TUF を通じて相互作用する時にはもっと明示的" +#~ "な名称に正規化する方が最大の意味をなすことになるでしょう。" + +#~ msgid "" +#~ "Likewise the ``latest`` metaversion should not be included in the " +#~ "targets, only explicitly declared versions should be supported." +#~ msgstr "" +#~ "``latest`` メタバージョンがターゲットの中に含まれているべきではないのと同" +#~ "様に、明示的に宣言されたバージョンだけがサポートされるべきです。" + +#~ msgid "`not yet `_" +#~ msgstr "`not yet `_" + +#~ msgid "`Vagrant `_" +#~ msgstr "`Vagrant `_" + +#, fuzzy +#~| msgid ":ref:`pyproject-toml-spec`" +#~ msgid "**Inspiration**: :ref:` pyproject-tool-table`" +#~ msgstr ":ref:`pyproject-toml-spec`" + +#~ 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." +#~ msgstr "" +#~ "ルート URL 以下には、リポジトリに含まれる独立のプロジェクトのそ" +#~ "れぞれに対応する別の URL があります。この URL のフォーマットは ``/" +#~ "/`` で、 ```` の部分はそのプロジェクトの正規化された名称" +#~ "で置き換えられるので、あるプロジェクトの名称が \"HolyGrail\" なら、 URL " +#~ "は ``/holygrail/`` のようになるでしょう。この URL は、プロジェクトのファイ" +#~ "ル一つに対してひとつのアンカーエレメントを伴った正当な HTML5 ページを返さ" +#~ "なければなりません。href アトリビュートは、そのファイルのダウンロードリン" +#~ "クの URL で **なければならず** 、アンカータグのテキストはその URL の最終的" +#~ "なパス構成要素 (ファイル名) に合致して **いなければなりません** 。この URL" +#~ "は、 URL の断片要素の形でハッシュ値を **含んでいるべき** で、その文法は次" +#~ "のようなものです: ``#=`` の形で、 ```` は " +#~ "(``sha256`` のように) ハッシュ関数の名前を小文字で表記したものであり、 " +#~ "```` は16進数にエンコードされたダイジェスト (ハッシュ値) です。" + +#~ msgid "Adding \"Yank\" Support to the Simple API" +#~ msgstr "\"ヤンク \" サポートをシンプルな API に追加する" + +#~ msgid "Signing the distribution packages" +#~ msgstr "配布パッケージに署名する" + +#~ msgid "" +#~ "The following job signs the distribution packages with `Sigstore`_, the " +#~ "same artifact signing system `used to sign CPython `_." +#~ msgstr "" +#~ "以下に述べるジョブは、`CPython ` に署名するのに使われる`_ ものと同じアーティファクトである `Sigstore`_ " +#~ "を使って配布パッケージに署名します。" + +#~ 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 リリー" +#~ "ス説明文書 `_ を見てください。" + +#~ 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." +#~ msgstr "" +#~ "GitHub リリースの作成ができるような ``GITHUB_TOKEN`` パーミッションを維持" +#~ "する必要があります。やり方については、 `GitHub 説明文書 `_ を見てください。具体的に言えば、トークンには ``contents: " +#~ "write`` 権限が必要です。" + +#~ msgid "" +#~ "Finally, the signed distributions are uploaded to the GitHub Release." +#~ msgstr "最後に、署名された配布物が GitHub Release へアップロードされます。" + +#~ 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." +#~ msgstr "" +#~ "これは、 `PyPI から削除された `_ GPG 署名を代替するものです。しかしながら、このジョブは " +#~ "PyPI へアップロードする時に必須のものと言うわけではなく、省略することもで" +#~ "きます。" + +#, fuzzy +#~| msgid "" +#~| "This can take two forms. You can put your license in a file, typically " +#~| "``LICENSE`` or ``LICENSE.txt``, and link that file here:" +#~ msgid "" +#~ "This can take two forms. You can put your license in a file, " +#~ "typically :file:`LICENSE` or :file:`LICENSE.txt`, and link that file here:" +#~ msgstr "" +#~ "これは、ふたつの形式を採ります。典型的には ``LICENSE`` か ``LICENSE.txt`` " +#~ "というファイル名でライセンスをファイルとして置いておいて、ここにはそのファ" +#~ "イルへのリンクを書いて置くこともできます:" + +#~ msgid "or you can write the name of the license:" +#~ msgstr "あるいは、ライセンスの名称を書いておくことも可能です:" + +#, fuzzy +#~| 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.)" +#~ msgid "" +#~ "If you are using a standard, well-known license, it is not necessary to " +#~ "use this field. Instead, you should use one of the :ref:`classifiers` " +#~ "starting with ``License ::``. (As a general rule, it is a good idea to " +#~ "use a standard, well-known license, both to avoid confusion and because " +#~ "some organizations avoid software whose license is unapproved.)" +#~ msgstr "" +#~ "標準的でよく知られたライセンスを使うのであれば、このフィールドを使う必要は" +#~ "ありません。代わりに、 ``License::`` で始まる :ref:`分類子 ` " +#~ "のうちのひとつを書いておけば良いでしょう。 (一般的な規則としては標準的でよ" +#~ "く知られたライセンスを使うことは良い考えです、というのは、混乱を避けるとこ" +#~ "とにもなるし、中には内部で認可済みのライセンスでなければソフトウェアを使え" +#~ "ない組織もあるからです。)" + +#~ 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." +#~ msgstr "" +#~ "このガイドは特に :ref:`setuptools` のユーザに向けて書かれていますので、同" +#~ "様の機能を提供する ``flit`` のような他のパッケージングツールのユーザは適切" +#~ "な文書を参照する必要があるでしょう。" + +#~ msgid "This workflow requires that:" +#~ msgstr "このワークフローは、以下を要求します:" + +#~ msgid "The publisher is using the latest version of :ref:`setuptools`," +#~ msgstr "" +#~ "(パッケージを)公開しようとするものが最新版の :ref:`setuptools` を使ってい" +#~ "て、" + +#~ msgid "The latest version of :ref:`twine` is used to upload the package," +#~ msgstr "最新版の :ref:`twine` を使ってパッケージのアップロードを行い、" + +#~ 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." +#~ msgstr "" +#~ "CLIでオプションを指定することで :file:`setup.cfg` ファイルでの設定を上書き" +#~ "することができるので、あなたのパッケージ生成スクリプトが ``--universal`` " +#~ "オプションを指定していないことを確実にしてください。" + +#~ msgid "1. Download the newest version of Setuptools" +#~ msgstr "1. Setuptools の最新版をダウンロードする" + +#~ msgid "" +#~ "Ensure that before you generate source distributions or binary " +#~ "distributions, you update Setuptools and install twine." +#~ msgstr "" +#~ "ソースコード配布物を生成するにせよ、バイナリ配布物を生成するにせよ、 " +#~ "Setuptools を更新し twine をインストールするようにしてください。" + +#~ msgid "Steps:" +#~ msgstr "手順:" + +#~ msgid "``setuptools`` version should be above 24.0.0." +#~ msgstr "``setuptools`` のバージョンが 24.0.0 以上であること。" + +#~ msgid "" +#~ "The way to set those values is within the call to ``setup`` within " +#~ "your :file:`setup.py` script. This will insert the ``Requires-Python`` " +#~ "metadata values based on the argument you provide in ``python_requires``." +#~ msgstr "" +#~ "このような値の設定は、 :file:`setup.py` スクリプトの中の ``setup`` の呼び" +#~ "出しの中で行えます。 ``python_requires`` 引数に設定した内容に基づいて " +#~ "``Requires-Python`` メタデータの値が挿入されます。" + +#~ msgid "4. Using Twine to publish" +#~ msgstr "4. Twineを使って公開する" + +#~ msgid "" +#~ "Twine has a number of advantages, apart from being faster it is now the " +#~ "supported method for publishing packages." +#~ msgstr "" +#~ "動作が速いことを別にしてもTwineには数多くの利点があり、今ではパッケージを" +#~ "公開するためのメソッドとしてサポートされています。" + +#~ msgid "Make sure you are using the newest version of Twine, at least 1.9." +#~ msgstr "少なくとも1.9以上の最新のTwineを使うようにしてください。" + +#~ msgid "" +#~ "Once you have published a package with the Requires-Python metadata, you " +#~ "can then make a further update removing that Python runtime from support." +#~ msgstr "" +#~ "Requires-Python メタデータ付きでパッケージを公開しさえすれば、次回以降の更" +#~ "新の際にPython ランタイムをサポートから外すことができるようになります。" + +#~ msgid "It must be done in this order for the automated fallback to work." +#~ msgstr "" +#~ "自動フォールバックが正しく動作するためには、この順番で行わなければなりませ" +#~ "ん。" + +#~ msgid "" +#~ "For example, you published the Requires-Python: \">=2.7\" as version " +#~ "1.0.0 of your package." +#~ msgstr "" +#~ "例えば、 Requires-Python: \">=2.7\" の状態であなたのパッケージのバージョ" +#~ "ン 1.0.0 を公開したとしましよう。" + +#~ 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 を受" +#~ "け取ることになるでしょう。" + +#~ msgid "Update this page for build backends other than setuptools." +#~ msgstr "" +#~ "setuptools 以外のビルドバックエンドについてこのページを更新すること。" + +#~ msgid "" +#~ "Read the file in :file:`setup.py` and get the version. Example (from `pip " +#~ "setup.py `_)::" +#~ msgstr "" +#~ ":file:`setup.py` に書かれたファイルを読み込んでバージョンを得ましょう。" +#~ "( `pip setup.py `_ で" +#~ "の) 例はこちら::" + +#~ 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\" をパッケージを" +#~ "インポートする際の名前で置き換えてください) :" + +#~ msgid "" +#~ "As of the release of setuptools 61.0.0, one can specify the version " +#~ "dynamically in the project's :file:`pyproject.toml` file." +#~ msgstr "" +#~ "setuptools 61.0.0 のリリースの時点では、プロジェクト" +#~ "の :file:`pyproject.toml` ファイルの中にバージョンを動的に指定することがで" +#~ "きます。" + +#~ msgid "" +#~ "Please be aware that declarative config indicators, including the " +#~ "``attr:`` directive, are not supported in parameters to :file:`setup.py`." +#~ msgstr "" +#~ "``attr:`` ディレクティブを含む装飾的な設定指示子が、 :file:`setup.py` 向け" +#~ "のパラメータとしてはサポートされていないことに注意してください。" + +#~ msgid "" +#~ "Use an external build tool that either manages updating both locations, " +#~ "or offers an API that both locations can use." +#~ msgstr "" +#~ "外部のビルドツールを使う場合は、両方の場所(ロケーション)を更新できるような" +#~ "もの、あるいは、両方のサイトから使える API を提供しているものを使いましょ" +#~ "う。" + +#~ 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 `_." + +#~ msgid "" +#~ "Set the value to a ``__version__`` global variable in a dedicated module " +#~ "in your project (e.g. :file:`version.py`), then have :file:`setup.py` " +#~ "read and ``exec`` the value into a variable." +#~ msgstr "" +#~ "プロジェクト内にグローバル変数の ``__version__`` に値を設定した専用のモ" +#~ "ジュール (例えば :file:`version.py`) を作って :file:`setup.py` からそれを" +#~ "読み取って ``exec`` で値を変数に取り込むと良いでしょう。" + +#~ msgid "" +#~ "Example using this technique: `warehouse `_." +#~ msgstr "" +#~ "このテクニックを使っている例: `warehouse `_ 。" + +#~ 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` とプロジェクトのソースコードの両方から読み込みます。" + +#~ msgid "" +#~ "An advantage with this technique is that it's not specific to Python. " +#~ "Any tool can read the version." +#~ msgstr "" +#~ "このテクニックを使う利点は、Python に限定されたやり方ではないということで" +#~ "す。どんなツールでもバージョン番号を読み取ることができます。" + +#~ msgid "" +#~ "With this approach you must make sure that the ``VERSION`` file is " +#~ "included in all your source and binary distributions (e.g. add ``include " +#~ "VERSION`` to your :file:`MANIFEST.in`)." +#~ msgstr "" +#~ "このやり方を採用するなら、 ``VERSION`` ファイルがすべてのソースコードとバ" +#~ "イナリの配布物に含まれているように気を付けてください (例え" +#~ "ば :file:`MANIFEST.in` に ``include VERSION`` を追加しておくなど)。" + +#~ 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::" +#~ msgstr "" +#~ ":file:`setup.py` に値を保存して、プロジェクトのソースコードが " +#~ "``importlib.metadata`` API を使ってその値を動作中に取得するようにしましょ" +#~ "う。 (``importlib.metadata`` は Python 3.8 で導入されていて、それより古い" +#~ "バージョンでは ``importlib-metadata`` プロジェクトとして利用可能になってい" +#~ "ます) インストール済みのプロジェクトのバージョン番号をこの API で取り込む" +#~ "には次のようにします::" + +#~ msgid "" +#~ "Be aware that the ``importlib.metadata`` API only knows about what's in " +#~ "the installation metadata, which is not necessarily the code that's " +#~ "currently imported." +#~ msgstr "" +#~ "``importlib.metadata`` API が知っているのはインストールされたパッケージの" +#~ "メタデータだけであって、現在インポートされているソースコードについて知って" +#~ "いるとは限らないことに注意してください。" + +#~ msgid "" +#~ "If a project uses this method to fetch its version at runtime, then its " +#~ "``install_requires`` value needs to be edited to install ``importlib-" +#~ "metadata`` on pre-3.8 versions of Python like so::" +#~ msgstr "" +#~ "あるプロジェクトで動作中にバージョン番号を取得する方法を使っているのであれ" +#~ "ば、Python 3.8 よりも古いバージョンを使う場合はそのプロジェクトの " +#~ "``install_requires`` に ``importlib-metadata`` を書いておかなければなりま" +#~ "せん::" + +#~ msgid "" +#~ "An older (and less efficient) alternative to ``importlib.metadata`` is " +#~ "the ``pkg_resources`` API provided by ``setuptools``::" +#~ msgstr "" +#~ "``importlib.metadata`` に対するもっと古い (かつ、より非効率な) 代替策は、 " +#~ "``setuptools`` が提供する ``pkg_resources`` API です::" + +#~ 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`` が入っていないといけません。" + +#~ msgid "" +#~ "Example using this technique: `setuptools `_." +#~ msgstr "" +#~ "このテクニックを使っている例: `setuptools `_." + +#~ 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`` をインポートしましょう。" + +#~ msgid "" +#~ "Although this technique is common, beware that it will fail if ``sample/" +#~ "__init__.py`` imports packages from ``install_requires`` dependencies, " +#~ "which will very likely not be installed yet when :file:`setup.py` is run." +#~ msgstr "" +#~ "このテクニックはよく知られたものだが、 ``install_requires`` で定義された依" +#~ "存先パッケージを ``sample/__init__.py`` がインポートしている場合には、その" +#~ "ようなパッケージは :file:`setup.py` が実行される時点ではまだインストールさ" +#~ "れていない可能性が高いので、失敗するであろうということに注意してください。" + +#~ 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 `_." +#~ msgstr "" +#~ "ソースコード内ではなくバージョンコントロールシステム (Git, Mercurialなど) " +#~ "のタグの中にバージョン番号を保持して、そこから `setuptools_scm `_ を使って取り出しましょう。" + +#~ 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]`` の二つのテーブルの間には、大きな差異が" +#~ "あります。どんなビルドバックエンドを使うのかに関わりなく前者は常に存在して" +#~ "いなければなりません (というのも、どのツールを使うのかをこのテーブルで定義" +#~ "するからです)。後者は、 *ほとんどの* ビルドバックエンドが理解しますが、一" +#~ "部のバックエンドは異なったフォーマットのものを用います。" + +#~ 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)." +#~ msgstr "" +#~ "これを書いている時点 (2023年11月) では、 ``[project]`` テーブルを使わない" +#~ "ビルドバックエンドとしては、 Poetry_ が有名です (代わりに " +#~ "``[tool.poetry]`` テーブルを使います) 。" + +#~ 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." +#~ msgstr "" +#~ "conda は、 Python 実装である `Anaconda `__ のためのパッケージ管理ツールです。Anaconda Python は、 " +#~ "`Anaconda, Inc `__ が特に科" +#~ "学計算の分野に向けて配布している配布物で、とりわけ通常ならバイナリ拡張のイ" +#~ "ンストールが難しいとされる Windows 用に配布しています。" + +#~ 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." +#~ msgstr "" +#~ "この仕様は、現在の API バージョンを \"1.0\" と定め、シンプルな API をさら" +#~ "に進化させる将来の仕様がマイナーバージョン番号を増加させるであろうことを期" +#~ "待しています。" + +#~ msgid "Additional Fields for the Simple API for Package Indexes" +#~ msgstr "パッケージインデックス用のシンプル API 向けの追加的なフィールド" + +#~ 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:" +#~ msgstr "" +#~ "この仕様では、シンプルなリポジトリ API のバージョン 1.1 を定義します。API " +#~ "の HTML バージョンについては、バージョン 1.0 から何ら変わるところがありま" +#~ "せん。API の JSON バージョンについては、以下のような変更が行われました:" + +#~ msgid "The ``api-version`` must specify version 1.1 or later." +#~ msgstr "" +#~ "``api-version`` に 1.1 またはそれ以降のバージョンを指定しなければなりませ" +#~ "ん。" + +#~ msgid "" +#~ "Two new \"file information\" keys, ``size`` and ``upload-time``, are " +#~ "added to the ``files`` data." +#~ msgstr "" +#~ "\"ファイル情報\" のキー群のふたつのキー、 つまり ``size`` と ``upload-" +#~ "time`` 、が ``files`` データに追加されました。" + +#~ msgid "" +#~ "The ``versions`` and ``size`` keys are mandatory. The ``upload-time`` key " +#~ "is optional." +#~ msgstr "" +#~ "``versions`` キーと ``size`` キーは必須のものです。 ``upload-time`` キーは" +#~ "オプションです。" + +#~ msgid "Additional file information" +#~ msgstr "補足的なファイル情報" + +#~ msgid "Two new keys are added to the ``files`` key." +#~ msgstr "``files`` キーにふたつの新しいキーが追加されました。" + +#~ msgid "Rename dist-info-metadata in the Simple API" +#~ msgstr "シンプル API の dist-info-metadata の名称変更" + +#~ msgid "Servers" +#~ msgstr "サーバ" + +#~ 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." +#~ msgstr "" +#~ "シンプル APIの HTML 表現の中で用いられる時は、 :ref:`API メタデータファイ" +#~ "ルの仕様 ` のメタデータは ``data-" +#~ "core-metadata`` という名称のアトリビュートを使ってサポートされている値が同" +#~ "一のまま発信されなければなりません。" + +#~ 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." +#~ msgstr "" +#~ ":ref:`API メタデータファイルの仕様 ` " +#~ "のメタデータは、シンプル API の :ref:`JSON API 仕様 ` による JSON 表現で使われる場合、サポートされている値は同一に" +#~ "保ったままで ``core-metadata`` キーを使って **送信されなければなりません" +#~ "** 。" + +#~ 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``." +#~ msgstr "" +#~ "以前のキーの名称を使っているクライアントをサポートするためには、 HTML 表現" +#~ "では ``data-dist-info-metadata`` を使って送信しても **構いません** し、そ" +#~ "の場合には ``data-core-metadata`` の値と **合致していなければなりません" +#~ "** 。" + +#~ 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." +#~ msgstr "" +#~ "シンプル API の HTML 表現を消費するクライアントは、もしそれが存在するなら" +#~ "ば、 :ref:`API メタデータファイルの仕様 ` のメタデータを ``data-core-metadata`` キーから **読み込まなければな" +#~ "りません** 。従来の ``data-dist-info-metadata`` キーは存在しているが " +#~ "``data-core-metadata`` は存在していないという場合には、オプションとして前" +#~ "者を **使っても構いません** 。" + +#~ 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." +#~ msgstr "" +#~ "シンプル API の JSON 表現を消費するクライアントは、もしそれが存在するなら" +#~ "ば、 :ref:`API メタデータファイルの仕様 ` のメタデータを ``core-metadata`` キーから **読み込まなければなりま" +#~ "せん** 。従来の ``dist-info-metadata`` キーは存在しているが ``core-" +#~ "metadata`` は存在していないという場合には、オプションとして前者を **使って" +#~ "も構いません** 。" + +#~ msgid "" +#~ "Most build backends automatically include license files in packages. See " +#~ "your backend's documentation for more details." +#~ msgstr "" +#~ "ほとんどのビルドバックエンドは、パッケージ群のライセンスファイルを自動的に" +#~ "取り込みます。詳細については、あなたが使うバックエンドの説明文書を見てくだ" +#~ "さい。" + +#~ 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." +#~ msgstr "" +#~ "ユーザ名とパスワードの入力を促されることでしょう。ユーザ名には " +#~ "``__token__`` を使ってください。パスワードには接頭子の ``pypi-`` を含めた" +#~ "トークンの値を使ってください。" + +#~ 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:`フロントエンド " +#~ "` によってバックエンドに任されます。すべてのバックエンドは" +#~ "標準化されたインターフェースを提供します。" + +#~ 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." +#~ msgstr "" +#~ ":ref:`pip` のようなツールによるインストールや :term:`ビルド済配布物 " +#~ "` の生成のために必要となるメタデータや基本的なソース" +#~ "コードファイル群を提供する :term:`配布物 ` フォー" +#~ "マット (通常は ``python -m build --sdist`` を使って生成されます) 。もっと" +#~ "情報が欲しければ、 :ref:`パッケージフォーマット ` を見て" +#~ "ください。" + +#~ msgid "" +#~ "The standard :term:`Built Distribution` format. See :ref:`package-" +#~ "formats` for more information." +#~ msgstr "" +#~ "標準的な :term:`ビルド済配布物 ` フォーマット。更なる" +#~ "情報が知りたければ :ref:`パッケージフォーマット ` を見てく" +#~ "ださい。" + +#~ msgid "The summary description of the project." +#~ 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." +#~ msgstr "" +#~ "もしあなたが Python のパッケージングやインストールに慣れていて、今どんな" +#~ "ツールが推奨されているかを知りたいだけなら、ここを見てください。" + +#~ msgid "Application dependency management" +#~ msgstr "アプリケーションの依存先管理" + +#~ msgid "" +#~ "Use :ref:`pip` in a `secure manner`_ to install a Python application and " +#~ "its dependencies during deployment." +#~ msgstr "" +#~ "デプロイメントの間に Python アプリケーションとその依存先をインストールする" +#~ "には、:ref:`pip` を `secure manner`_ で使ってください。" + +#~ msgid "" +#~ "Use :ref:`virtualenv` or :doc:`venv ` to isolate " +#~ "application-specific dependencies from a shared Python installation. [4]_" +#~ msgstr "" +#~ "共有された Python のインストール環境からアプリケーションに特有の依存関係を" +#~ "独立させるためには、 :ref:`virtualenv` ないし :doc:`venv ` を使いましょう。 [4]_" + +#~ msgid "" +#~ "Use `pip-tools`_, :ref:`pipenv`, or `poetry`_ to generate the fully-" +#~ "specified application-specific dependencies, when developing Python " +#~ "applications." +#~ msgstr "" +#~ "Python アプリケーションを開発するときに、完全に指定されたアプリケーション" +#~ "特有の依存関係を満たす環境を作るには `pip-tools`_ や :ref:`pipenv` 、ある" +#~ "いは `poetry`_ を使ってください。" + +#~ msgid "Installation tool recommendations" +#~ msgstr "推奨ツールのインストール" + +#~ msgid "" +#~ "Use :ref:`pip` to install Python :term:`packages ` " +#~ "from :term:`PyPI `. [1]_ [2]_ Depending on " +#~ "how :ref:`pip` is installed, you may need to also install :ref:`wheel` to " +#~ "get the benefit of wheel caching. [3]_" +#~ msgstr "" +#~ ":term:`PyPI ` から :term:`パッケージ " +#~ "` をインストールするには :ref:`pip` を使いましょ" +#~ "う。 [1]_ [2]_ :ref:`pip` がどのようにインストールされているかによっては、" +#~ "wheel のキャッシュの利益を得るために :ref:`wheel` を追加でインストールする" +#~ "必要があるかもしれません。 [3]_" + +#~ msgid "" +#~ "Use :ref:`virtualenv` or :doc:`venv ` to isolate " +#~ "project-specific dependencies from a shared Python installation. [4]_" +#~ msgstr "" +#~ "共有された Python のインストール環境からプロジェクトに特有の依存関係を独立" +#~ "させるためには、 :ref:`virtualenv` ないし :doc:`venv ` を使いましょう。 [4]_" + +#~ msgid "" +#~ "If you're looking for management of fully integrated cross-platform " +#~ "software stacks, consider:" +#~ msgstr "" +#~ "完全に統合されたクロスプラットフォームなソフトウェアスタックの管理ツールを" +#~ "探しているのであれば、以下を検討してください:" + +#~ msgid ":ref:`buildout`: primarily focused on the web development community" +#~ msgstr ":ref:`buildout`: 主としてweb開発コミュニティに焦点を合わせている" + +#~ msgid "" +#~ ":ref:`spack`, :ref:`hashdist`, or :ref:`conda`: primarily focused on the " +#~ "scientific community." +#~ msgstr "" +#~ ":ref:`spack` ・ :ref:`hashdist` ・ :ref:`conda`: 主として科学計算分野のコ" +#~ "ミュニティに焦点を合わせている。" + +#~ msgid "Packaging tool recommendations" +#~ msgstr "推奨するパッケージングツール" + +#~ msgid "Use :ref:`setuptools` to define projects. [5]_ [6]_" +#~ msgstr "プロジェクトを定義するために :ref:`setuptools` を用いる。[5]_ [6]_" + +#~ msgid "" +#~ "Use :ref:`build` to create :term:`Source Distributions ` and :term:`wheels `." +#~ msgstr "" +#~ ":term:`ソースコード配布物 ` " +#~ "や :term:`wheels ` を生成するためには、 :ref:`build` を使いましょ" +#~ "う。" + +#~ msgid "" +#~ "Use `twine `_ for uploading distributions " +#~ "to :term:`PyPI `." +#~ msgstr "" +#~ "配布物を :term:`PyPI ` へアップロードするに" +#~ "は、 `twine `_ を使いましょう。" + +#~ msgid "Publishing platform migration" +#~ msgstr "プラットフォームの移行を公開する" + +#~ msgid "" +#~ "The original Python Package Index implementation (previously hosted at " +#~ "`pypi.python.org `_) has been phased out in " +#~ "favour of an updated implementation hosted at `pypi.org `_." +#~ msgstr "" +#~ "元々の Python パッケージインデックスの実装 (以前は `pypi.python.org " +#~ "`_ にホストされていました) は、更新された実装が " +#~ "`pypi.org `_ にホストされたので、すでに停止されていま" +#~ "す。" + +#~ msgid "" +#~ "See :ref:`Migrating to PyPI.org` for more information on the status of " +#~ "the migration, and what settings to change in your clients." +#~ msgstr "" +#~ "この移行の状態に関する詳細やクライアント側での設定変更について" +#~ "は、 :ref:`PyPI.org への移行 ` を見てください。" + +#~ msgid "" +#~ "There are some cases where you might choose to use ``easy_install`` " +#~ "(from :ref:`setuptools`), e.g. if you need to install from :term:`Eggs " +#~ "` (which pip doesn't support). For a detailed breakdown, " +#~ "see :ref:`pip vs easy_install`." +#~ msgstr "" +#~ "例えば (pip がサポートしていない) :term:`Eggs ` からインストールする" +#~ "必要がある場合など、 (:ref:`setuptools` 由来の) ``easy_install`` を使いた" +#~ "くなる場合もあるでしょう、どちらを使うべきかの詳細については、 :ref:`pip " +#~ "vs easy_install` を見てください。" + +#~ msgid "" +#~ "The acceptance of :pep:`453` means that :ref:`pip` will be available by " +#~ "default in most installations of Python 3.4 or later. See " +#~ "the :pep:`rationale section <453#rationale>` from :pep:`453` as for why " +#~ "pip was chosen." +#~ msgstr "" +#~ ":pep:`453` を受け入れるということは、Python 3.4 やそれ以降がインストールさ" +#~ "れていればほとんどの場合にデフォルトで :ref:`pip` が使えるはずだということ" +#~ "になります。なぜ pip が選ばれたのかについては、 :pep:`453` のページ" +#~ "の :pep:`根拠の節 <453#rationale>` を見てください。" + +#~ msgid "" +#~ "`get-pip.py `_ " +#~ "and :ref:`virtualenv` install :ref:`wheel`, whereas :ref:`ensurepip` " +#~ "and :ref:`venv ` do not currently. Also, the common \"python-pip\" " +#~ "package that's found in various linux distros, does not depend on " +#~ "\"python-wheel\" currently." +#~ msgstr "" +#~ "`get-pip.py `_ およ" +#~ "び :ref:`virtualenv` install :ref:`wheel` の場合は必要、他方" +#~ "で :ref:`ensurepip` と :ref:`venv ` は現時点では依存していません。ま" +#~ "た、さまざまな linux ディストロに含まれる通常の \"python-pip\" パッケージ" +#~ "は、現時点では \"python-wheel\" に依存していません。" + +#~ msgid "" +#~ "Beginning with Python 3.4, ``venv`` will create virtualenv environments " +#~ "with ``pip`` installed, thereby making it an equal alternative " +#~ "to :ref:`virtualenv`. However, using :ref:`virtualenv` will still be " +#~ "recommended for users that need cross-version consistency." +#~ msgstr "" +#~ "Python 3.4 以降では、 ``venv`` は ``pip`` がインストール済みの virtualenv " +#~ "環境を生成するので、 :ref:`virtualenv` の代替物となっています。しかしなが" +#~ "ら、バージョンまたぎの一貫性を必要とするユーザ向けには依然とし" +#~ "て :ref:`virtualenv` を使うことを推奨します。" + +#~ msgid "" +#~ "Although you can use pure :ref:`distutils` for many projects, it does not " +#~ "support defining dependencies on other projects and is missing several " +#~ "convenience utilities for automatically populating distribution metadata " +#~ "correctly that are provided by ``setuptools``. Being outside the standard " +#~ "library, ``setuptools`` also offers a more consistent feature set across " +#~ "different versions of Python, and (unlike ``distutils``), recent versions " +#~ "of ``setuptools`` support all of the modern metadata fields described " +#~ "in :ref:`core-metadata`." +#~ msgstr "" +#~ "多くのプロジェクトでは :ref:`distutils` をそのままの状態で使うことができま" +#~ "すが、このツールは他のプロジェクトへの依存関係を定義できず、また、" +#~ "``setuptools`` によって提供されるメタデータを配布物中に自動で正しく配置す" +#~ "るための便利なユーティリティがいくつか不足しています。標準ライブラリではあ" +#~ "りませんが、 ``setuptools`` は、また、Python の異なるバージョンを跨ぐ形で" +#~ "ずっと一貫性のある機能を提供しますし、(``distutils`` とは異なって) 最近の" +#~ "バージョンの ``setuptools`` は :ref:`core-metadata` に記述されているような" +#~ "近代的なメタデータ記入項目をすべてサポートしています。" + +#~ msgid "" +#~ "Even for projects that do choose to use ``distutils``, when :ref:`pip` " +#~ "installs such projects directly from source (rather than installing from " +#~ "a prebuilt :term:`wheel ` file), it will actually build your " +#~ "project using :ref:`setuptools` instead." +#~ msgstr "" +#~ "``distutils`` を使うことを選択したプロジェクトでさえも、(ビルド済み" +#~ "の :term:`wheel ` ファイルからインストールするのではな" +#~ "く) :ref:`pip` でソースコードから直接にインストールした場合には、実際には" +#~ "代わりに :ref:`setuptools` を使ってプロジェクトをビルドしています。" + +#~ msgid "" +#~ "`distribute`_ (a fork of setuptools) was merged back " +#~ "into :ref:`setuptools` in June 2013, thereby making setuptools the " +#~ "default choice for packaging." +#~ msgstr "" +#~ "(setuptools から分岐した) `distribute`_ は、2013年6月に :ref:`setuptools` " +#~ "へ再合流し、それ以来デフォルトのパッケージングにはデフォルトで setuptools " +#~ "を使うようになっています。" + +#~ msgid "Standards compliance for interoperability" +#~ msgstr "相互互換性のための標準的な取り決め" + +#~ msgid "Here are some examples of compliant version numbers::" +#~ msgstr "規定に合致したバージョン番号の例を次に示す::" + +#~ msgid "" +#~ "To further accommodate historical variations in approaches to version " +#~ "numbering, :pep:`440` also defines a comprehensive technique " +#~ "for :pep:`version normalisation <440#normalization>` that maps variant " +#~ "spellings of different version numbers to a standardised canonical form." +#~ msgstr "" +#~ "過去の様々なバージョン番号付与方法を規定内に包含するために、 :pep:`440` は" +#~ "様々なバージョン番号の変種的書き方を網羅する :pep:`バージョンの正規化 " +#~ "<440#normalization>` のテクニックも定義しています。" + +#~ msgid "Scheme choices" +#~ msgstr "方法論の選択" + +#~ msgid "" +#~ "For new projects, the recommended versioning scheme is based on `Semantic " +#~ "Versioning `_, but adopts a different approach to " +#~ "handling pre-releases and build metadata." +#~ msgstr "" +#~ "新しいプロジェクトには、 `意味あるバージョン付与方法 ` に従うことが推奨されていますが、リリース前やビルド時のメタデータとして" +#~ "は異なるやり方を採用しても良いでしょう。" + +#~ msgid "" +#~ "Adopting this approach as a project author allows users to make use " +#~ "of :pep:`\"compatible release\" <440#compatible-release>` specifiers, " +#~ "where ``name ~= X.Y`` requires at least release X.Y, but also allows any " +#~ "later release with a matching MAJOR version." +#~ msgstr "" +#~ "プロジェクトの作者としてこのやり方を採用すれば、ユーザが :pep:`互換性のあ" +#~ "るリリース <440#compatible-release>` の指定、つまり、``name ~= X.Y`` と指" +#~ "定してあるなら少なくともリリース X.Y が必要だが同じMAJORバージョンを持つな" +#~ "らその後のリリースでも構わないという書き方を利用することができるようになり" +#~ "ます。" + +#~ msgid "Date based versioning" +#~ msgstr "日付ベースのバージョン付与" + +#~ msgid "" +#~ "Version numbers for date based projects typically take the form of " +#~ "YEAR.MONTH (for example, ``12.04``, ``15.10``)." +#~ msgstr "" +#~ "日付ベースのバージョン番号は、YEAR.MONTHの形(例えば ``12.04``や``15.10``)" +#~ "をとるのが普通です。" + +#~ msgid "" +#~ "This is the simplest possible versioning scheme, and consists of a single " +#~ "number which is incremented every release." +#~ msgstr "" +#~ "これは最も単純なバージョン付与方法で、リリースのたびに増加する単一の番号で" +#~ "構成します。" + +#~ msgid "Pre-release versioning" +#~ msgstr "リリース前のバージョン付与方式" + +#~ msgid "" +#~ "Regardless of the base versioning scheme, pre-releases for a given final " +#~ "release may be published as:" +#~ msgstr "" +#~ "どのバージョン付与方式を採用するとしても、ある特定の最終的なリリースの前の" +#~ "リリースが次のような形で公開されることもあるでしょう:" + +#~ msgid "zero or more dev releases (denoted with a \".devN\" suffix)" +#~ msgstr "零またはそれ以上の dev リリース (\".devN\"という拡張子をつけて表示)" + +#~ msgid "zero or more alpha releases (denoted with a \".aN\" suffix)" +#~ msgstr "零またはそれ以上のalphaリリース (\".aN\"という拡張子をつけて表示)" + +#~ msgid "zero or more beta releases (denoted with a \".bN\" suffix)" +#~ msgstr "零またはそれ以上のbetaリリース (\".bN\"という拡張子をつけて表示)" + +#~ msgid "zero or more release candidates (denoted with a \".rcN\" suffix)" +#~ msgstr "零またはそれ以上のリリース候補 (\".rcN\"という拡張子をつけて表示)" + +#~ msgid "" +#~ "``pip`` and other modern Python package installers ignore pre-releases by " +#~ "default when deciding which versions of dependencies to install." +#~ msgstr "" +#~ "``pip``や最近のPythonパッケージインストーラでは、依存関係にあるパッケージ" +#~ "をインストールする際にリリース前のものを無視して含めないのが規定の動作で" +#~ "す。" + +#~ msgid "" +#~ "A local version identifier takes the form ``+``. For example::" +#~ msgstr "" +#~ "ローカルバージョン識別子は、 ``<公的バージョン識別子>+<ローカルバージョン" +#~ "ラベル>`` の形を取ります。例えば::" + +#~ msgid "" +#~ "Mirroring or caching of PyPI can be used to speed up local package " +#~ "installation, allow offline work, handle corporate firewalls or just " +#~ "plain Internet flakiness." +#~ msgstr "" +#~ "PyPIのミラーやキャッシュがあると、手元でパッケージをインストールするのが速" +#~ "くなったり、オフラインでインストールできたり、会社のファイアウォール経由で" +#~ "もできたり、あるいは、単純にインターネットがあてにならなくてもインストール" +#~ "できたりします。" + +#~ msgid "Three options are available in this area:" +#~ msgstr "この分野には３個のやり方があります:" + +#~ msgid "pip provides local caching options," +#~ msgstr "pip はローカルキャッシュのオプションを提供し、" + +#~ msgid "" +#~ "devpi provides higher-level caching option, potentially shared amongst " +#~ "many users or machines, and" +#~ msgstr "" +#~ "devpi は、潜在的には多数のユーザやマシンをまたがって共有できるような高レベ" +#~ "ルのキャッシュのオプションを提供し、" + +#~ msgid "" +#~ "bandersnatch provides a local complete mirror of all PyPI :term:`packages " +#~ "`." +#~ msgstr "" +#~ "bandersnatch は、PyPIのすべての :term:`パッケージ ` " +#~ "の完全なミラー(複製)を手元に置くオプションを提供します。" + +#~ msgid "Caching with devpi" +#~ msgstr "devpiでのキャッシュ" + +#~ msgid "" +#~ "devpi is a caching proxy server which you run on your laptop, or some " +#~ "other machine you know will always be available to you. See the `devpi " +#~ "documentation for getting started`__." +#~ msgstr "" +#~ "devpi は、キャッシュ機能付きのプロクシサーバで、あなたのラップトップやあな" +#~ "たがいつでも使えるとわかっているどこかの機体の上で動作させます。 `devpi の" +#~ "始め方 `__ を見てください。" + +#~ msgid "Complete mirror with bandersnatch" +#~ msgstr "bandersnatch で完全なミラーを作る" + +#~ msgid "" +#~ "bandersnatch will set up a complete local mirror of all " +#~ "PyPI :term:`packages ` (externally-hosted packages " +#~ "are not mirrored). See the `bandersnatch documentation for getting that " +#~ "going`__." +#~ msgstr "" +#~ "bandersnatch は、すべての PyPI :term:`パッケージ ` " +#~ "(外部にホストされているパッケージはミラーされません)の完全なローカルミラー" +#~ "を構築します。 `bandersnatch を走らせるには `__ を見てください。" + +#~ msgid "" +#~ "A benefit of devpi is that it will create a mirror which " +#~ "includes :term:`packages ` that are external to " +#~ "PyPI, unlike bandersnatch which will only cache :term:`packages " +#~ "` hosted on PyPI." +#~ msgstr "" +#~ "devpi の利点は、 PyPI の外部にある :term:`パッケージ ` を含むミラーを作成できることで、これはPyPI にホストされてい" +#~ "る :term:`パッケージ ` だけをキャッシュする " +#~ "bandersnatch とは異なる点です。" + +#~ msgid "" +#~ "`Issues `__ | `GitHub " +#~ "`__ | `PyPI `__" +#~ msgstr "" +#~ "`課題リスト `__ | `GitHub " +#~ "`__ | `PyPI `__" + +#~ 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)." +#~ msgstr "" +#~ "``bandersnatch`` は、PyPI をミラーリングするクライアントで、PyPI のコンテ" +#~ "ンツの完全なコピーを効率よく作成するように設計されています。組織から見る" +#~ "と、これによってパッケージのダウンロードに必要な帯域幅とレイテンシーを (と" +#~ "りわけ自動化されたテストの文脈で) 節約することができ、PyPI のコンテンツデ" +#~ "リバリネットワーク (CDN) への負荷を軽減します。" + +#~ 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." +#~ msgstr "" +#~ "devpi は、 Python を使ったパッケージングやテスティングやリリース活動を推進" +#~ "するための補完的なコマンドラインツールを備えた PyPI 互換の強力なサーバと " +#~ "PyPI プロクシキャッシュの機能を持ちます。devpi は閲覧と検索が可能なwebイン" +#~ "タフェイスも備えています。" + +#~ msgid "" +#~ "pypiserver is a minimalist application that serves as a private Python " +#~ "package index 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 "" +#~ "pypiserver は、素朴な API とブラウザ向けのインタフェイスだけを実装したプラ" +#~ "イベートの Python パッケージインデックスサーバとして振る舞う「小さいことは" +#~ "良いことだ」主義者のアプリケーションです。公衆向けに公開することなく標準の" +#~ "ツールを使って外部非公開のパッケージをアップロードすることもできますし、そ" +#~ "れを `pip` でダウンロード・インストールすることもできます。 pypiserver を" +#~ "用いる組織では、通常は pypiserver と PyPI の両方からパッケージをダウンロー" +#~ "ドします。" + +#, fuzzy +#~ msgid "" +#~ "By default, any hash algorithm available via `hashlib `_ (specifically any that can be " +#~ "passed to ``hashlib.new()`` and do not require additional parameters) can " +#~ "be used as a key for the hashes dictionary. At least one secure algorithm " +#~ "from ``hashlib.algorithms_guaranteed`` **SHOULD** always be included. At " +#~ "the time of this spec, ``sha256`` specifically is recommended." +#~ msgstr "" +#~ "``hash lib`` 経由で利用可能なハッシュアルゴリズム (とりわけ、 " +#~ "``hashlib.new()`` に渡すことができて、かつ、追加的なパラメータを必要としな" +#~ "いもの) はどれでも、ハッシュ値を格納する辞書のキーとして用いることができま" +#~ "す。 ``hashlib.algorithms_garanteed`` から安全なアルゴリズムを少なくともひ" +#~ "とつ選択して (訳注、ハッシュ値格納用辞書に) 含めるべきです。執筆時点で" +#~ "は、 ``sha256`` が特に推奨されています。" + +#, fuzzy +#~ msgid "pyproject type" +#~ msgstr "pyproject.toml" + +#~ msgid "" +#~ "pex is both a library and tool for generating :file:`.pex` (Python " +#~ "EXecutable) files, standalone Python environments in the spirit " +#~ "of :ref:`virtualenv`. :file:`.pex` files are just carefully constructed " +#~ "zip files with a ``#!/usr/bin/env python`` and " +#~ "special :file:`__main__.py`, and are designed to make deployment of " +#~ "Python applications as simple as ``cp``." +#~ msgstr "" +#~ "pex は、 :ref:`virtualenv` の精神に則ったスタンドアローンの Python 環境で" +#~ "ある :file:`.pex` (実行可能な Python ファイル) ファイルを生成するツールで" +#~ "ありライブラリです。 :file:`.pex` ファイルは、 ``#!/usr/bin/env python`` " +#~ "と特別な :file:`__main__.py` を伴う注意深く構築された zip ファイルであり、" +#~ "単に cp すれば Python アプリケーションを配置 (deploy) できるように設計され" +#~ "ています。" + +#~ msgid "" +#~ "If you're developing for a \"Platform-as-a-Service\" or \"PaaS\" like " +#~ "Heroku or Google App Engine, you are going to want to follow their " +#~ "respective packaging guides." +#~ msgstr "" +#~ "Heroku や Google App Engine のような「プラットフォームアズアサービス」ない" +#~ "し「PaaS」を使って開発をしているのであれば、各サービスのそれぞれのパッケー" +#~ "ジングガイドに従いたくなるでしょう。" + +#~ msgid "" +#~ "`Heroku `_" +#~ msgstr "" +#~ "`Heroku `_" + +#~ msgid "" +#~ "`Google App Engine `_" +#~ msgstr "" +#~ "`Google App Engine `_" + +#~ msgid "`PythonAnywhere `_" +#~ msgstr "`PythonAnywhere `_" + +#~ msgid "`OpenShift `_" +#~ msgstr "`OpenShift `_" + +#~ msgid "\"Serverless\" frameworks like :gh:`Zappa `" +#~ msgstr ":gh:`Zappa ` のような「サーバレス」フレームワーク" + +#~ msgid "" +#~ "In all these setups, the platform takes 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 "" +#~ "これらすべての構成では、あなたが彼らのパターンに従っている限りはプラット" +#~ "フォーム側がパッケージングと配置の世話をします。ほとんどのソフトウェアはこ" +#~ "れらのテンプレートのうちの一つには合致しないので、下記のような他の選択肢が" +#~ "存在することになります。" + +#, fuzzy +#~ msgid "" +#~ "The HTML format is defined in :pep:`503`, with the addition of \"yank\" " +#~ "support (allowing a kind of file deletion) in :pep:`592`, specifying the " +#~ "interface version provided by an index server in :pep:`629`, and " +#~ "providing package metadata independently from a package in :pep:`658` and " +#~ "revised in :pep:`714`." +#~ msgstr "" +#~ "利用可能なパッケージのバージョンを問い合わせ、インデックスサーバからパッ" +#~ "ケージを取り出すインタフェースは、現在、 :pep:`592` の \"yank\" サポート " +#~ "(ある種の削除を可能とするもの) や、 :pep:`629` のインデックスサーバ側が提" +#~ "供しているインタフェースのバージョンを指定する機能や、 :pep:`658` のパッ" +#~ "ケージとは独立にパッケージメタデータを提供する機能とともに、 :pep:`503` で" +#~ "定義されています。" + +#~ msgid "" +#~ "There were multiple iterations of the ``manylinux`` specification, each " +#~ "representing the common subset of Linux platforms at a given point in " +#~ "time:" +#~ msgstr "" +#~ "``manylinux`` 仕様は複数回の改訂があり、それぞれの版がその時々の Linux の" +#~ "共通のサブセットを表現しています:" + +#~ msgid "" +#~ "``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " +#~ "architectures. and updates the previous specification to be based on a " +#~ "compatible Linux platform from 2010 instead." +#~ msgstr "" +#~ "``manylinux2010`` (:pep:`571`) は、 ``x86_64`` および ``i686`` アーキテク" +#~ "チャをサポートしており、以前の仕様を更新して、その代わりに 2010 年から互換" +#~ "性のある Linux プラットフォームに基づいています。" + +#~ msgid "" +#~ "``manylinux2014`` (:pep:`599`) adds support for a number of additional " +#~ "architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " +#~ "``s390x``) and updates the base platform to a compatible Linux platform " +#~ "from 2014." +#~ msgstr "" +#~ "``manylinux2014`` (:pep:`599`) では、多数のアーキテクチャ (``aarch64``, " +#~ "``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``) へのサポートを追加し、" +#~ "また、2014 年以降の互換 Linux プラットフォームのベースを更新しました。" + +#~ msgid "" +#~ "``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " +#~ "future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " +#~ "versions supported (e.g. ``manylinux_2_24`` should work on any distro " +#~ "using glibc 2.24+). Previous tags are still supported for backward " +#~ "compatibility." +#~ msgstr "" +#~ "``manylinux_x_y`` (:pep:`600`) では、それまでの PEP 群を全て代替する形で将" +#~ "来を見据えた標準を定義しました。 ``x`` と ``y`` は、その標準がサポートす" +#~ "る glibc のメジャーバージョンとマイナーバージョンとして定義されています " +#~ "(例えば、 ``manylinux_2_24`` は glibc 2.24+ を使っているディストロならどれ" +#~ "でも、その上で動作するはずです) 。以前に使われたタグは広報互換性を保つため" +#~ "に依然としてサポートされています。" + +#~ msgid "Manylinux compatibility support" +#~ msgstr "Manylinux 互換性サポート" + +#~ msgid "" +#~ "The ``manylinux2014`` specification is relatively new and is not yet " +#~ "widely recognised by install tools." +#~ msgstr "" +#~ "``manylinux2014`` 仕様は相対的に新しく、未だインストールツールに広く認識さ" +#~ "れたと言える状況ではありません。" + +#~ msgid "" +#~ "The ``manylinux_x_y`` specification is relatively new and is not yet " +#~ "widely recognised by install tools." +#~ msgstr "" +#~ "``manylinux_x_y`` 仕様は相対的に新しく、未だインストールツールに広く認識さ" +#~ "れたと言える状況ではありません。" + +#~ msgid "" +#~ "The name of the distribution. The name field is the primary identifier " +#~ "for a distribution. A valid name consists only of ASCII letters and " +#~ "numbers, period, underscore and hyphen. It must start and end with a " +#~ "letter or number. Distribution names are limited to those which match the " +#~ "following regex (run with ``re.IGNORECASE``)::" +#~ msgstr "" +#~ "配布物の名前。name フィールドは、配布物の一義的な識別子です。正当な名前は " +#~ "ASCII 文字・数字・ピリオド・アンダースコア・ハイフンだけで構成されているも" +#~ "のです。名前の先頭と末尾は文字か数字でなければなりません。配布物の名前は次" +#~ "の正規表現に (``re.IGNORECASE`` 付きで) マッチするものに限られます::" + +#~ msgid "" +#~ "Project names are \"normalized\" for use in various contexts. This " +#~ "document describes how project names should be normalized." +#~ msgstr "" +#~ "プロジェクト名は、さまざまな文脈で使用するために \"正規化\" されます。この" +#~ "説明文書では、プロジェクト名がどのように正規化されるべきかについて記述しま" +#~ "す。" + +#~ msgid "Valid non-normalized names" +#~ msgstr "正当な非正規化名" + +#, fuzzy +#~ msgid "The following changes were applied since the initial version:" +#~ msgstr "" +#~ "以降の変更は、最初の実装 (ができた) 後に寄せられたフィードバックに基づくも" +#~ "のです:" + +#~ msgid "Summary of changes to PEP 508" +#~ msgstr "PEP 508 に対する変更の要旨" + +#~ msgid "" +#~ "The following changes were made based on feedback after its initial " +#~ "implementation:" +#~ msgstr "" +#~ "以降の変更は、最初の実装 (ができた) 後に寄せられたフィードバックに基づくも" +#~ "のです:" + +#~ msgid "" +#~ "March 2020: the ``direct_url.json`` metadata file was originally " +#~ "specified in :pep:`610` and is formally documented here." +#~ msgstr "" +#~ "2020年3月: ``direct_url.json`` メタデータファイルは、当初は :pep:`610` で" +#~ "仕様を指定されていましたが、ここで正式に文書化されました。" + +#~ msgid "" +#~ "March 2020: this data structure was originally specified as part of the " +#~ "``direct_url.json`` metadata file in :pep:`610` and is formally " +#~ "documented here." +#~ msgstr "" +#~ "2020年3月: このデータ構造は、当初は :pep:`610` で ``direct_url.json`` メタ" +#~ "データファイルの一部として仕様を指定されていましたが、ここで正式に文書化さ" +#~ "れました。" + +#~ msgid "" +#~ "January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" +#~ "discuss.python.org/t/22299))." +#~ msgstr "" +#~ "2023年1月: ``archive_info.hashes`` キーを追加しました ([議論] (https://" +#~ "discuss.python.org/t/22299)) 。" + +#~ msgid "" +#~ "`September 2015 `_: normalized name was originally specified " +#~ "in :pep:`503#normalized-names`." +#~ msgstr "" +#~ "`2015年9月 `_: 正規化された名称は、元々は :pep:`503#normalized-" +#~ "names` で仕様化されていました。" + +#~ msgid "" +#~ "`November 2015 `_: valid non-normalized name was originally " +#~ "specified in :pep:`508#names`." +#~ msgstr "" +#~ "`2015年11月 `_: 正当であるが正規化されてはいない名称は、元々" +#~ "は :pep:`508#names` で仕様化されていました。" + +#~ msgid "The following PEPs contributed to this spec:" +#~ msgstr "この仕様に貢献する PEP 群を以下に示す:" + +#~ msgid ":pep:`425`" +#~ msgstr ":pep:`425`" + +#~ msgid ":pep:`513`" +#~ msgstr ":pep:`513`" + +#~ msgid ":pep:`599`" +#~ msgstr ":pep:`599`" + +#~ msgid "History and change workflow" +#~ msgstr "ワークフローの履歴と変更" + +#~ msgid "" +#~ "The metadata described here was first specified in :pep:`376`, and later " +#~ "amended in :pep:`627` (and other PEPs). It was formerly known as " +#~ "*Database of Installed Python Distributions*. As with other PyPA " +#~ "specifications, editorial amendments with no functional impact may be " +#~ "made through the GitHub pull request workflow. Proposals for functional " +#~ "changes that would require amendments to package building and/or " +#~ "installation tools must be made through the PEP process (see :pep:`1`)." +#~ msgstr "" +#~ "ここで述べるメタデータは、 :pep:`376` で初めて定義されたもので、後" +#~ "に :pep:`627` (およびその他の PEP 群) で改訂されました。以前は *インストー" +#~ "ル済みの Python 配布物のデータベース* という名前で知られていました。他の " +#~ "PyPA 仕様と同様に、 GitHab の Pull リクエストのワークフローを通じて、機能" +#~ "の面に影響しない編集上の改訂を行うことが可能です。パッケージの作成やインス" +#~ "トールツールを修正するであろう機能面での変更提案は、 PEP のプロセス " +#~ "(:pep:`1` を見てください) を通じて行わなければなりません。" + +#~ msgid "" +#~ "While this document is the normative specification, the PEPs that " +#~ "introduce changes to it may include additional information such as " +#~ "rationales and backwards compatibility considerations." +#~ msgstr "" +#~ "この説明文書が規範的な仕様書である一方で、その変更を導入するような PEP 群" +#~ "は、理論的根拠や後方互換性を保つための考慮点のような追加的な情報を含んでい" +#~ "ても構いません。" + +#~ msgid "November 2020: :pep:`643` converted to this specification" +#~ msgstr "2020-11: :pep:`643` をこの仕様に変換" + +#~ msgid "December 2000: Source distributions standardized in :pep:`643`" +#~ msgstr "2000-12: ソースコード配布物について :pep:`643` で標準化" + +#~ msgid "" +#~ "This is the name of your project, determining how your project is listed " +#~ "on :term:`PyPI `. Per :pep:`508`, valid " +#~ "project names must:" +#~ msgstr "" +#~ "これは、あなたのプロジェクトが :term:`PyPI ` " +#~ "でどこに並べられるかを決めるプロジェクトの名前です。 :pep:`508` に従えば、" +#~ "正当なプロジェクト名は以下の条件を満たさなければなりません：" + +#~ msgid "Start & end with an ASCII letter or digit." +#~ msgstr "先頭と最後の文字がASCII文字ないし数字であること。" + +#~ msgid "" +#~ "This is the current version of your project, allowing your users to " +#~ "determine whether or not they have the latest version, and to indicate " +#~ "which specific versions they've tested their own software against." +#~ msgstr "" +#~ "これはあなたのプロジェクトの現在のバージョンで、これがあることであなたのプ" +#~ "ロジェクトのユーザたちが自分が最新版を使っているのかどうかを判断したり、彼" +#~ "ら自身のソフトウェアと組み合わせて試験を行ったバージョンがどれなのかを示し" +#~ "たりすることができるようになります。" + +#~ msgid "" +#~ "Versions are displayed on :term:`PyPI ` for " +#~ "each release if you publish your project." +#~ msgstr "" +#~ "バージョンは、あなたが自分のプロジェクトをリリースする度に :term:`PyPI " +#~ "` 上に表示されます。" + +#~ msgid "" +#~ "If the project code itself needs run-time access to the version, the " +#~ "simplest way is to keep the version in both :file:`setup.py` and your " +#~ "code. If you'd rather not duplicate the value, there are a few ways to " +#~ "manage this. See the \":ref:`Single sourcing the version`\" Advanced " +#~ "Topics section." +#~ msgstr "" +#~ "プログラムが動作している間に自分自身のバージョンを知る必要があるのであれ" +#~ "ば、バージョン番号を :file:`setup.py` とあなたのソースコードの両方に格納し" +#~ "ておくのがもっとも単純な方法です。値を複数箇所に書きたくないのであれば、や" +#~ "り方が2,3種類あります。「 :ref:`バージョンを一箇所で管理するには ` 」の「高度な話題」の節を見て下さい。" + +#~ msgid "Give a short and long description for your project." +#~ msgstr "あなたのプロジェクトについて、短い説明と長い説明を与えて下さい。" + +#~ msgid "" +#~ "These values will be displayed on :term:`PyPI ` if you publish your project. On ``pypi.org``, the user interface " +#~ "displays ``description`` in the grey banner and ``long_description`` in " +#~ "the section named \"Project Description\"." +#~ msgstr "" +#~ "これらの値は、あなたのプロジェクトを公開したときに :term:`PyPI ` に表示されます。 ``pypi.org`` のユーザインタフェイ" +#~ "スでは、灰色のバナーに ``description`` を表示し、「プロジェクトの説明」と" +#~ "名付けられたセクションに ``long_description`` を表示します。" + +#~ msgid "" +#~ "``description`` is also displayed in lists of projects. For example, it's " +#~ "visible in the search results pages such as https://pypi.org/search/?" +#~ "q=jupyter, the front-page lists of trending projects and new releases, " +#~ "and the list of projects you maintain within your account profile (such " +#~ "as https://pypi.org/user/jaraco/)." +#~ msgstr "" +#~ "``description`` は、プロジェクト一覧にも表示されます。例えば、https://" +#~ "pypi.org/search/?q=jupyter のような検索結果のページや、フロントページの流" +#~ "行プロジェクトや新規リリースプロジェクトの一覧や、あなたのアカウントのプロ" +#~ "ファイルページ(例えば https://pypi.org/user/jaraco/)の中のあなたがメンテナ" +#~ "ンスしているプロジェクトの一覧に表示されるということです。" + +#~ msgid "" +#~ "A :ref:`content type ` can be " +#~ "specified with the ``long_description_content_type`` argument, which can " +#~ "be one of ``text/plain``, ``text/x-rst``, or ``text/markdown``, " +#~ "corresponding to no formatting, `reStructuredText (reST) `_, and the GitHub-flavored Markdown dialect of `Markdown `_ respectively." +#~ msgstr "" +#~ ":ref:`content type ` は、書式のな" +#~ "い ``text/plain`` か `reStructuredText (reST) `_ の ``text/x-rst`` か `Markdown `_ の GitHub 方言のマークダウンである ``text/" +#~ "markdown`` のうちのいずれかひとつの書式で、 " +#~ "``long_description_content_type`` 引数とともに指定することができます。" + +#~ msgid "``url``" +#~ msgstr "``url``" + +#~ msgid "Give a homepage URL for your project." +#~ msgstr "あなたのプロジェクトのホームページのURLを与えてください。" + +#~ msgid "Provide details about the author." +#~ msgstr "著者について詳しい情報を提供してください。" + +#~ msgid "" +#~ "The ``license`` argument doesn't have to indicate the license under which " +#~ "your package is being released, although you may optionally do so if you " +#~ "want. If you're using a standard, well-known license, then your main " +#~ "indication can and should be via the ``classifiers`` argument. " +#~ "Classifiers exist for all major open-source licenses." +#~ msgstr "" +#~ "``license`` 引数には、あなたのパッケージがどのライセンスの下で公開されたか" +#~ "を示すこともできますが、これは必須ではなくオプションです。あなたが一般的で" +#~ "よく知られたライセンスを採用するのであれば、 ``分類詞 `` を指" +#~ "定するだけで済ませることができると同時に済ませるべきです。メジャーなオープ" +#~ "ンソースライセンスであればどれでも、それを指し示す分類詞が用意されていま" +#~ "す。" + +#~ msgid "" +#~ "Provide a list of classifiers that categorize your project. For a full " +#~ "listing, see https://pypi.org/classifiers/." +#~ msgstr "" +#~ "あなたのプロジェクトを特徴付ける分類詞(classifier)を設定してください。" +#~ "https://pypi.org/classifiers に全部の一覧が出ています。" + +#~ msgid "List keywords that describe your project." +#~ msgstr "あなたのプロジェクトを説明するキーワードを列挙してください。" + +#~ msgid "" +#~ "List additional relevant URLs about your project. This is the place to " +#~ "link to bug trackers, source repositories, or where to support package " +#~ "development. The string of the key is the exact text that will be " +#~ "displayed on PyPI." +#~ msgstr "" +#~ "あなたのプロジェクトに関係する追加的なURLを列挙してください。これは、バグ" +#~ "追跡システムやソースコードリポジトリ、あるいは、パッケージ開発をサポートす" +#~ "る場所などをリンクするための場所です。キー文字列をそのままテキストとして" +#~ "PyPI上に表示されます。" + +#~ msgid "" +#~ "If your project only runs on certain Python versions, setting the " +#~ "``python_requires`` argument to the appropriate :pep:`440` version " +#~ "specifier string will prevent :ref:`pip` from installing the project on " +#~ "other Python versions. For example, if your package is for Python 3+ " +#~ "only, write::" +#~ msgstr "" +#~ "あなたのプロジェクトが特定のバージョンのPythonでないと動作しないのであれ" +#~ "ば、適切な :pep:`440` バージョン特定文字列で ``python_requires`` 引数を設" +#~ "定しておくことで :ref:`pip` が他のバージョンの `Python` なのに当該プロジェ" +#~ "クトをインストールしてしまうことがなくなります。例えば、あなたのパッケージ" +#~ "が Python 3+ 向けのものであれば、このように書いてください：" + +#~ msgid "" +#~ "If your package is for Python 2.6, 2.7, and all versions of Python 3 " +#~ "starting with 3.3, write::" +#~ msgstr "" +#~ "Python 2.6と2.7、そして3.3以上のPython 3用であればこのように書きます::" + +#~ msgid "And so on." +#~ msgstr "等々。" + +#~ msgid "" +#~ "Support for this feature is relatively recent. Your project's source " +#~ "distributions and wheels (see :ref:`Packaging Your Project`) must be " +#~ "built using at least version 24.2.0 of :ref:`setuptools` in order for the " +#~ "``python_requires`` argument to be recognized and the appropriate " +#~ "metadata generated." +#~ msgstr "" +#~ "この機能がサポートされたのは比較的最近のことです。 ``python_requires`` 引" +#~ "数が認識されて適切なメタデータが生成されるためには、あなたのプロジェクトの" +#~ "ソースコード配布物やwheels (:ref:`あなたのプロジェクトをパッケージする " +#~ "` 参照)を24.2.0かそれ以降のバージョン" +#~ "の :ref:`setuptools` でビルドしなければなりません。" + +#~ msgid "" +#~ "In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the " +#~ "``python_requires`` metadata. Users with earlier versions of pip will be " +#~ "able to download & install projects on any Python version regardless of " +#~ "the projects' ``python_requires`` values." +#~ msgstr "" +#~ "さらに、 :ref:`pip` のバージョン9.0.0かそれ以降のものでなければ " +#~ "``python_requires`` のメタデータを認識しません。これより前のバージョンの" +#~ "pipを使っている場合は、 ``python_requires`` の設定に関わりなくどんなバー" +#~ "ジョンのPythonを使っていてもダウンロードやインストールが可能です。" + +#~ msgid "``entry_points``" +#~ msgstr "``entry_points``" + +#~ msgid "" +#~ "Use this keyword to specify any plugins that your project provides for " +#~ "any named entry points that may be defined by your project or others that " +#~ "you depend on." +#~ msgstr "" +#~ "あなたのプロジェクト内か依存先のプロジェクトで定義された名前付きのエント" +#~ "リーポイントをあなたのプロジェクトが提供しているようなプラグインがあればこ" +#~ "のキーワード引数を使って指定してください。" + +#~ msgid "" +#~ "For more information, see the section on :ref:`Advertising Behavior " +#~ "` from " +#~ "the :ref:`setuptools` docs." +#~ msgstr "" +#~ "詳しくは、:ref:`setup tools` 文書の :ref:`広報する動作 " +#~ "` の節を見てくださ" +#~ "い。" + +#~ msgid "" +#~ "The most commonly used entry point is \"console_scripts\" (see below)." +#~ msgstr "" +#~ "よくあるエントリーポイントとしては、\"console_scipts\" (後述)が挙げられま" +#~ "す。" + +#~ msgid "" +#~ "Use ``console_script`` :ref:`entry points ` to register your script interfaces. You can " +#~ "then let the toolchain handle the work of turning these interfaces into " +#~ "actual scripts [2]_. The scripts will be generated during the install of " +#~ "your :term:`distribution `." +#~ msgstr "" +#~ "``console_script`` :ref:`エントリーポイント ` は、スクリプトインターフェイスを登録するために" +#~ "使ってください。そうすれば、ツールチェーンがそのようなインターフェイスを実" +#~ "際のスクリプトに変換する作業を肩代わりしてくれます[2]_ 。あなたの :term:`" +#~ "配布物 ` をインストールする途中でスクリプトが生成さ" +#~ "れます。" + +#~ msgid "" +#~ "For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." +#~ msgstr "" +#~ "詳しくは、 :doc:`setuptools 説明文書 ` の中の :doc:`エン" +#~ "トリポイント ` を見てください。" + +#~ msgid "" +#~ "Specifically, the \"console_script\" approach generates ``.exe`` files on " +#~ "Windows, which are necessary because the OS special-cases ``.exe`` files. " +#~ "Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher " +#~ "for Windows <397>` allow scripts to be used in many cases, but not all." +#~ msgstr "" +#~ "特に、\"console_script\" を使うと Windows では ``.exe`` ファイルを生成しま" +#~ "すが、これはOSが特別なケースとして ``.exe`` ファイルを必要とするからで" +#~ "す。 ``PATHEXT`` や :pep:`Windows向けPythonランチャー <397>` のようなスク" +#~ "リプトを実行する機能によって多くの場合にスクリプトが使われますが、しかし、" +#~ "いつでも使えるわけではありません。" + +#~ msgid "" +#~ "The binary distribution format (:term:`wheel `) was originally " +#~ "defined in :pep:`427`. The current version of the specification is here." +#~ msgstr "" +#~ "バイナリ配布物のフォーマット (:term:`wheel `) は、元々" +#~ "は :pep:`427` で定義されました。仕様の現在のバージョンはここにあります。" + +#~ msgid "Abstract" +#~ msgstr "要約" + +#~ msgid "" +#~ "This PEP describes a built-package format for Python called \"wheel\"." +#~ msgstr "" +#~ "この PEP は、 Python 向けコンパイル済みパッケージの \"wheel\" と呼ばれる" +#~ "フォーマットについて記述しています。" + +#~ msgid "PEP Acceptance" +#~ msgstr "PEP の受諾" + +#~ msgid "" +#~ "This PEP was accepted, and the defined wheel version updated to 1.0, by " +#~ "Nick Coghlan on 16th February, 2013 [1]_" +#~ msgstr "" +#~ "この PEP は受諾され、定義された wheel のバージョンが 1.0 に2013年2月16日" +#~ "に Nick Coghlan によって更新されました" + +#~ msgid "Rationale" +#~ msgstr "理論的根拠" + +#~ msgid "" +#~ "Python needs a package format that is easier to install than sdist. " +#~ "Python's sdist packages are defined by and require the distutils and " +#~ "setuptools build systems, running arbitrary code to build-and-install, " +#~ "and re-compile, code just so it can be installed into a new virtualenv. " +#~ "This system of conflating build-install is slow, hard to maintain, and " +#~ "hinders innovation in both build systems and installers." +#~ msgstr "" +#~ "Python には sdist よりも簡単にインストールすることができるパッケージフォー" +#~ "マットが必要です。 Python の sdist パッケージは、ソースコードをビルドした" +#~ "りインストールしたり再コンパイルしたりするために任意のコードを実行し、そう" +#~ "することで新しい virtualenv 環境にインストールできるように、 distutiles " +#~ "と setuptools によるビルドシステムによって定義され、かつ、これらのツールを" +#~ "必要とします。このようなビルドとインストールを合成したシステムは動作が遅" +#~ "く、維持管理が困難であり、ビルドシステムとインストーラの双方における技術革" +#~ "新を阻害します。" + +#~ msgid "" +#~ "Wheel attempts to remedy these problems by providing a simpler interface " +#~ "between the build system and the installer. The wheel binary package " +#~ "format frees installers from having to know about the build system, saves " +#~ "time by amortizing compile time over many installations, and removes the " +#~ "need to install a build system in the target environment." +#~ msgstr "" +#~ "Wheel は、ビルドシステムとインストーラの間により単純なインタフェイスを提供" +#~ "することで、これらの問題を癒すことを試みます。 wheel バイナリパッケージの" +#~ "フォーマットは、インストーラがビルドシステムについて知らなくても済むように" +#~ "し、何度もインストールするとしてもコンパイルにかかる時間を節約できるように" +#~ "し、また、インストール先の環境にビルドシステムをインストールする必要を取り" +#~ "除きます。" + +#~ msgid "Comparison to .egg" +#~ msgstr ".egg との比較" + +#~ msgid "" +#~ "Wheel is an installation format; egg is importable. Wheel archives do " +#~ "not need to include .pyc and are less tied to a specific Python version " +#~ "or implementation. Wheel can install (pure Python) packages built with " +#~ "previous versions of Python so you don't always have to wait for the " +#~ "packager to catch up." +#~ msgstr "" +#~ "Wheel はインストールするためのフォーマットのひとつですが、 egg はインポー" +#~ "トすることができます。 Wheel アーカイブには .pyc が含まれている必要がない" +#~ "ので、 Python の特定のバージョンや実装に紐づく度合いがより小さくなりま" +#~ "す。 Wheel は、以前のバージョンの Python でビルドされた (純 Python の) " +#~ "パッケージをインストールすることができるので、必ずしもパッケージ制作者が追" +#~ "いつくのを待つ必要がありません。" + +#~ msgid "" +#~ "Wheel uses .dist-info directories; egg uses .egg-info. Wheel is " +#~ "compatible with the new world of Python packaging and the new concepts it " +#~ "brings." +#~ msgstr "" +#~ "Wheel は .dist-info ディレクトリを使用するが、 egg は .egg-info を使いま" +#~ "す。 Wheel は、 Python のパッケージングにおける新しい世界とそれがもたらす" +#~ "新しい概念に適合しています。" + +#~ msgid "" +#~ "Wheel has a richer file naming convention for today's multi-" +#~ "implementation world. A single wheel archive can indicate its " +#~ "compatibility with a number of Python language versions and " +#~ "implementations, ABIs, and system architectures. Historically the ABI " +#~ "has been specific to a CPython release, wheel is ready for the stable ABI." +#~ msgstr "" +#~ "Wheel は、今日の複数実装世界に合わせて、より表現力が高いファイル命名慣習を" +#~ "持っています。単独の wheel アーカイブ (訳注、その名前) が、数々の Python " +#~ "言語のバージョンや実装、ABI やシステムアーキテクチャとの互換性を表示するこ" +#~ "とができるのです。歴史的には、 ABI は CPython のリリースに紐づいていました" +#~ "が、 wheel は安定な ABI に対応しています。" + +#~ msgid "" +#~ "Wheel is lossless. The first wheel implementation bdist_wheel always " +#~ "generates egg-info, and then converts it to a .whl. It is also possible " +#~ "to convert existing eggs and bdist_wininst distributions." +#~ msgstr "" +#~ "Wheel はロスレスです。最初の wheel 実装である bdist_wheel は常に egg-info " +#~ "を生成し、それを .whl ファイルへ変換します。既存の egg ファイルを " +#~ "bdist_wininst 配布物に変換することも可能です。" + +#~ msgid "" +#~ "Wheel is versioned. Every wheel file contains the version of the wheel " +#~ "specification and the implementation that packaged it. Hopefully the next " +#~ "migration can simply be to Wheel 2.0." +#~ msgstr "" +#~ "Wheel はバージョン付けされています。各 wheel ファイルは wheel 仕様および" +#~ "パッケージングに使われた実装のバージョンを含んでいます。次のマイグレーショ" +#~ "ンが単純に Wheel 2.0 へのものになれば良いのですが。" + +#~ msgid "Wheel is a reference to the other Python." +#~ msgstr "Wheel は、他の Python に対して参照するべきものとなっています。" + +#~ msgid "Since :pep:`427`, this specification has changed as follows:" +#~ msgstr ":pep:`427` 以来、この仕様には次のような修正が加えられました:" + +#~ msgid "" +#~ "PEP acceptance (https://mail.python.org/pipermail/python-dev/2013-" +#~ "February/124103.html)" +#~ msgstr "" +#~ "PEP 受諾 (https://mail.python.org/pipermail/python-dev/2013-February/" +#~ "124103.html)" + +#~ msgid "This document has been placed into the public domain." +#~ msgstr "この文書はパブリックドメインに位置付けられる。" + +#~ msgid "``python -m twine check``" +#~ msgstr "``python -m twine check``" + +#~ msgid "``python -m twine register``" +#~ msgstr "``python -m twine register``" + +#~ msgid "``python -m twine upload``" +#~ msgstr "``python -m twine upload``" + +#~ msgid "``python -m setuptools-scm``" +#~ msgstr "``python -m setuptools-scm``" + +#~ msgid "" +#~ "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth); " +#~ "see :doc:`Declaring project metadata ` for more detail" +#~ msgstr "" +#~ "プロジェクトの :doc:`コアとなるメタデータ ` (名前・バージョン・作者・その他) を含む ``[project]`` テーブル; 詳しく" +#~ "は、 :doc:`プロジェクトのメタデータを宣言する ` を見てください" + +#~ msgid "a ``[tool]`` table containing tool-specific configuration options" +#~ msgstr "ツール特有の設定オプションを含んだ ``[tool]`` テーブル" + +#~ msgid "" +#~ "A `content type `_ can be specified with the " +#~ "``long_description_content_type`` argument, which can be one of ``text/" +#~ "plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " +#~ "formatting, `reStructuredText (reST) `_, and the GitHub-" +#~ "flavored Markdown dialect of `Markdown `_ respectively." +#~ msgstr "" +#~ "``long_description_content_type`` 引数に特に整形しない ``text/plain`` 、" +#~ "`reStructuredText (reST) `_ として解釈される ``text/x-" +#~ "rst`` 、`Markdown `_ の中で" +#~ "もGitHub方言のものとして解釈される ``text/markdown`` のうちのいずれかを与" +#~ "えることで、`コンテンツタイプ `_ を指定" +#~ "することができます。" + +#~ msgid "You can learn more about pipx at https://pypa.github.io/pipx/." +#~ msgstr "pipx については、 https://pypa.github.io/pipx/ でもっと学べます。" + +#~ msgid ":ref:`declaring-build-dependencies`" +#~ msgstr ":ref:`ビルド依存関係を宣言する `" + +#~ msgid "" +#~ "Read :ref:`declaring-project-metadata` for the full specification of the " +#~ "content allowed in the ``[project]`` table." +#~ msgstr "" +#~ "``[project]`` テーブルで許される内容の完全な仕様については、 :ref:`プロ" +#~ "ジェクトのメタデータを宣言する ` を読んでくだ" +#~ "さい。" + +#~ msgid ":ref:`declaring-project-metadata`" +#~ msgstr "" +#~ ":ref:`プロジェクトのメタデータを宣言する `" + +#~ msgid "" +#~ "`Docs `__ | `GitHub `__ | `PyPI `__" +#~ msgstr "" +#~ "`説明文書 `__ | `GitHub `__ | `PyPI `__" + +#~ msgid "" +#~ ":doc:`Docs ` | `Issues `__ | `GitHub `__" +#~ msgstr "" +#~ ":doc:`説明文書 ` | `課題リスト `__ | `GitHub `__" + +#~ msgid "" +#~ "trove-classifiers is the canonical source for `classifiers on PyPI " +#~ "`_, which project maintainers use to " +#~ "`systematically describe their projects `_ so that users " +#~ "can better find projects that match their needs on the PyPI." +#~ msgstr "" +#~ "trove-classifiers は、`PyPI における分類子 `_ の正統な源泉で、ユーザがそのニーズに即したプロジェクトを PyPI でよりう" +#~ "まく探し出せるように、プロジェクトの管理者が `プロジェクトを体系的に表現す" +#~ "る `_ のに使います。" + +#, fuzzy +#~ msgid "" +#~ "The ``pyproject.toml`` file is written in `TOML `_. " +#~ "Among other metadata (such as :ref:`project metadata `), it declares any Python level dependencies that must be " +#~ "installed in order to run the project's build system successfully." +#~ msgstr "" +#~ "`pyproject.toml` は :pep:`518` で定義されたビルドシステムとは独立したファ" +#~ "イル形式で、あるプロジェクトのビルドシステムが正常に動作するためにインス" +#~ "トールされていなければならない Python レベルの依存関係をすべて宣言するとい" +#~ "う目的のためにそのプロジェクトが提供するものです。" + +#~ msgid "Declaring project metadata" +#~ msgstr "プロジェクトのメタデータを宣言する" + +#~ msgid "" +#~ ":pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for packaging-related tools to " +#~ "consume. It defines the following specification as the canonical source " +#~ "for the format used." +#~ msgstr "" +#~ ":pep:`621` では、パッケージング関連のツールが使用するために、あるプロジェ" +#~ "クトの :ref:`コアとなるメタデータ ` を ``pyproject.toml`` " +#~ "ファイルにどのように書けば良いかを指定しています。使われるファイルフォー" +#~ "マットの基準となる仕様として、以下のようなものを定義しています。" + +#, fuzzy +#~ msgid "" +#~ "The keys defined in this specification MUST be in a table named " +#~ "``[project]`` in ``pyproject.toml``. No tools may add keys to this table " +#~ "which are not defined by this specification. For tools wishing to store " +#~ "their own settings in ``pyproject.toml``, they may use the ``[tool]`` " +#~ "table as defined in the :ref:`build dependency declaration specification " +#~ "`. The lack of a ``[project]`` table " +#~ "implicitly means the :term:`build backend ` will " +#~ "dynamically provide all keys." +#~ msgstr "" +#~ "この仕様で定義されるキーは、 ``pyproject.toml`` ファイルの中の " +#~ "``[project]`` という名前のテーブルに収容されていなければなりません。いかな" +#~ "るツールもこのテーブルにこの仕様で定義されていないキーを追加してはなりませ" +#~ "ん。自身の設定を ``pyproject.toml`` ファイルに記録しておきたいと願うツール" +#~ "は、 :ref:`ビルド時の依存関係を宣言するための仕様 ` で定義されている通りに ``[tool]`` テーブルを使うことができ" +#~ "ます。 ``[project]`` テーブルが欠落している場合は、ビルド用のバックエンド" +#~ "がすべてのキーを動的に提供するであろうということを暗黙理に意味しています。" + +#~ msgid "" +#~ "A ``.tar.gz`` source distribution (sdist) contains a single top-level " +#~ "directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " +#~ "source files of the package. The name and version MUST match the metadata " +#~ "stored in the file. This directory must also contain " +#~ "a :file:`pyproject.toml` in the format defined in :ref:`declaring-build-" +#~ "dependencies`, and a ``PKG-INFO`` file containing metadata in the format " +#~ "described in the :ref:`core-metadata` specification. The metadata MUST " +#~ "conform to at least version 2.2 of the metadata specification." +#~ msgstr "" +#~ "``.tar.gz`` ソースコード配布物 (sdist) には、 ``{name}-{version}`` (例え" +#~ "ば ``foo-1.0``) と言う名前の単一のトップレベルディレクトリがあって、そこに" +#~ "パッケージのソールファイル群を含んでいます。 name と version は、ファイル" +#~ "内のメタデータと合致していなければなりません。このディレクトリ" +#~ "は、 :ref:`declaring-build-dependencies` の中で定義されたフォーマットで書" +#~ "かれた :file:`pyproject.toml` ファイルや、 :ref:`core-metadata` 仕様内に記" +#~ "述されたフォーマットで書かれたメタデータを含んだ ``PKG-INFO`` ファイルも含" +#~ "んでいなければなりません。メタデータは、少なくともバージョン 2.2 のメタ" +#~ "データ仕様を満足するものでなければなりません。" + +#~ msgid "" +#~ "Read :pep:`517` and :pep:`518` for background and details on build tool " +#~ "configuration." +#~ msgstr "" +#~ "ビルドツールの設定に関する背景情報や詳細情報については、 :pep:`517` " +#~ "や :pep:`518` を読みましょう。" + +#~ msgid "Read about :doc:`/guides/packaging-binary-extensions`." +#~ msgstr ":doc:`/guides/packaging-binary-extensions` について読みましょう。" + +#~ msgid "And of course *setuptools* itself is not deprecated either." +#~ msgstr "" +#~ "そして、 *setuptools* それ自身もまた、非推奨ではないのはもちろんのことで" +#~ "す。" + +#~ msgid "" +#~ "It is however deprecated to run ``python setup.py`` as a command line " +#~ "tool." +#~ msgstr "" +#~ "しかしながら、コマンドラインツールとしての ``python setup.py`` を実行する" +#~ "ことは非推奨になっています。" + +#~ msgid "Current recommendation" +#~ msgstr "現在の推奨項目" + +#~ msgid "" +#~ "`distribute`_ was a fork of setuptools that was merged back into " +#~ "setuptools (in v0.7), thereby making setuptools the primary choice for " +#~ "Python packaging." +#~ msgstr "" +#~ "`distribute`_ は setuptools から分岐したもので、 setuptools に (v0.7 で) " +#~ "再合流し、その時からは setuptools が Python のパッケージングにおける第一の" +#~ "選択肢となりました。" + +#~ msgid "" +#~ "When building a :term:`source distribution ` for your package, by default only a minimal set of files are " +#~ "included. You may find yourself wanting to include extra files in the " +#~ "source distribution, such as an authors/contributors file, a :file:`docs/" +#~ "` directory, or a directory of data files used for testing purposes. " +#~ "There may even be extra files that you *need* to include; for example, if " +#~ "your :file:`setup.py` computes your project's ``long_description`` by " +#~ "reading from both a README and a changelog file, you'll need to include " +#~ "both those files in the sdist so that people that build or install from " +#~ "the sdist get the correct results." +#~ msgstr "" +#~ "パッケージの :term:`ソースコード配布物 ` をビルドする際、配布物には必要最低限のファイルだけが配布物に" +#~ "含まれるのがデフォルトです。ソースコード配布物に、例えば authors/" +#~ "contributors ファイルや、 :file:`docs/` ディレクトリや、テストに使う目的の" +#~ "データファイルを収めたディレクトリなどの追加のファイルを含めたくなる時もあ" +#~ "るかと思います。また、追加のファイルを含める *必要がある* 場合さえあるで" +#~ "しょう; 例えば :file:`setup.py` が README ファイルと改変履歴ファイルを読み" +#~ "込んでプロジェクトの ``long_description`` を計算するようになっている場合に" +#~ "は、これら両方のファイルを sdist に含めることで人々が sdist からビルドなり" +#~ "インストールなりを行う際にも正しく動作するようにする必要があります。" + +#~ msgid "" +#~ "Adding & removing files to & from the source distribution is done by " +#~ "writing a :file:`MANIFEST.in` file at the project root." +#~ msgstr "" +#~ "プロジェクトのルートディレクトリにある :file:`MANIFEST.in` ファイルを書け" +#~ "ば、ソースコード配布物に対してファイルの追加・削除を行うことができます。" + +#~ msgid "How files are included in an sdist" +#~ msgstr "ファイルは sdist にどのように含まれるのか" + +#~ msgid "" +#~ "The following files are included in a source distribution by default:" +#~ msgstr "" +#~ "次に掲げるファイル群は、デフォルトでソースコード配布物に取り込まれます:" + +#~ msgid "" +#~ "all Python source files implied by the ``py_modules`` and ``packages`` " +#~ "``setup()`` arguments" +#~ msgstr "" +#~ "``setup()`` の引数である ``py_modules`` と ``packages`` で暗示されるすべて" +#~ "の Python ソースファイル" + +#~ msgid "" +#~ "all C source files mentioned in the ``ext_modules`` or ``libraries`` " +#~ "``setup()`` arguments" +#~ msgstr "" +#~ "``setup()`` の引数である ``ext_modules`` や ``libraries`` で言及されたすべ" +#~ "ての C 言語のソースファイル" + +#~ msgid "scripts specified by the ``scripts`` ``setup()`` argument" +#~ msgstr "``setup()`` の ``scripts`` 引数で指定されたスクリプト群" + +#~ msgid "" +#~ "all files specified by the ``package_data`` and ``data_files`` " +#~ "``setup()`` arguments" +#~ msgstr "" +#~ "``setup()`` の引数である ``package_data`` と ``data_files`` で指定されるす" +#~ "べてのファイル群" + +#~ msgid "" +#~ "the file specified by the ``license_file`` option in :file:`setup.cfg` " +#~ "(setuptools 40.8.0+)" +#~ msgstr "" +#~ ":file:`setup.cfg` ファイル (setuptools 40.8.0 以降) 内の ``license_file`` " +#~ "オプションで指定されるファイル" + +#~ msgid "" +#~ "all files specified by the ``license_files`` option in :file:`setup.cfg` " +#~ "(setuptools 42.0.0+)" +#~ msgstr "" +#~ ":file:`setup.cfg` ファイル (setuptools 42.0.0 以降) の ``license_files`` " +#~ "オプションで指定される全てのファイル" + +#~ msgid "all files matching the pattern :file:`test/test*.py`" +#~ msgstr ":file:`test/test*.py` にマッチする全てのファイル" + +#~ msgid ":file:`setup.py` (or whatever you called your setup script)" +#~ msgstr "" +#~ ":file:`setup.py` ファイル (または、名前がなんであろうとセットアップスクリ" +#~ "プト)" + +#~ msgid ":file:`setup.cfg`" +#~ msgstr ":file:`setup.cfg` ファイル" + +#~ msgid ":file:`README`" +#~ msgstr ":file:`README` ファイル" + +#~ msgid ":file:`README.txt`" +#~ msgstr ":file:`README.txt` ファイル" + +#~ msgid ":file:`README.rst` (Python 3.7+ or setuptools 0.6.27+)" +#~ msgstr "" +#~ ":file:`README.rst` ファイル (Python 3.7 以降、または setuptools 0.6.27 以" +#~ "降)" + +#~ msgid ":file:`README.md` (setuptools 36.4.0+)" +#~ msgstr ":file:`README.md` ファイル (setuptools 36.4.0 以降)" + +#~ msgid ":file:`pyproject.toml` (setuptools 43.0.0+)" +#~ msgstr ":file:`pyproject.toml` ファイル (setuptools 43.0.0 以降)" + +#~ msgid ":file:`MANIFEST.in`" +#~ msgstr ":file:`MANIFEST.in` ファイル" + +#~ msgid "" +#~ "After adding the above files to the sdist, the commands " +#~ "in :file:`MANIFEST.in` (if such a file exists) are executed in order to " +#~ "add and remove further files to and from the sdist. Default files can " +#~ "even be removed from the sdist with the appropriate :file:`MANIFEST.in` " +#~ "command." +#~ msgstr "" +#~ "sdist に上記のファイル群を追加した後、sdist へのさらなるファイルの追加・削" +#~ "除を行うために (もしそのファイルが存在すれば) :file:`MANIFEST.in` ファイル" +#~ "の中のコマンドが実行されます。 :file:`MANIFEST.in` に適切にコマンドを記述" +#~ "すれば、デフォルトで含まれるファイルであっても削除することができます。" + +#~ msgid "" +#~ "After processing the :file:`MANIFEST.in` file, setuptools removes " +#~ "the :file:`build/` directory as well as any directories " +#~ "named :file:`RCS`, :file:`CVS`, or :file:`.svn` from the sdist, and it " +#~ "adds a :file:`PKG-INFO` file and an :file:`*.egg-info` directory. This " +#~ "behavior cannot be changed with :file:`MANIFEST.in`." +#~ msgstr "" +#~ ":file:`MANIFEST.in` ファイルに従って処理をした後、 setuptools " +#~ "は :file:`build/` ディレクトリと同様に :file:`RCS` ・ :file:`CVS` " +#~ "・ :file:`.svn` という名前のディレクトリ群を sdist から削除し、:file:`PKG-" +#~ "INFO` ファイルと :file:`*.egg-info` ディレクトリを追加します。この動作" +#~ "は :file:`MANIFEST.in` ファイルでは変更することができません。" + +#~ msgid ":file:`MANIFEST.in` commands" +#~ msgstr ":file:`MANIFEST.in` コマンド" + +#~ msgid "" +#~ "A :file:`MANIFEST.in` file consists of commands, one per line, " +#~ "instructing setuptools to add or remove some set of files from the " +#~ "sdist. The commands are:" +#~ msgstr "" +#~ ":file:`MANIFEST.in` ファイルは一行にひとつのコマンドで構成されており、" +#~ "setuptools に対して sdist に関するファイル追加・削除を指示します。コマンド" +#~ "として使えるのは次のものです:" + +#~ msgid "Command" +#~ msgstr "コマンド" + +#~ msgid ":samp:`include {pat1} {pat2} ...`" +#~ msgstr ":samp:`include {pat1} {pat2} ...`" + +#~ msgid "" +#~ "Add all files matching any of the listed patterns (Files must be given as " +#~ "paths relative to the root of the project)" +#~ msgstr "" +#~ "列挙されたパターンのいずれかに合致するすべてのファイルを追加する (ファイル" +#~ "はプロジェクトのルートディレクトリに対する相対パスの形で指定されなければな" +#~ "りません)" + +#~ msgid ":samp:`exclude {pat1} {pat2} ...`" +#~ msgstr ":samp:`exclude {pat1} {pat2} ...`" + +#~ msgid "" +#~ "Remove all files matching any of the listed patterns (Files must be given " +#~ "as paths relative to the root of the project)" +#~ msgstr "" +#~ "列挙されたパターンのいずれかに合致するすべてのファイルを削除する (ファイル" +#~ "はプロジェクトのルートディレクトリに対する相対パスの形で指定されなければな" +#~ "りません)" + +#~ msgid ":samp:`recursive-include {dir-pattern} {pat1} {pat2} ...`" +#~ msgstr ":samp:`recursive-include {dir-pattern} {pat1} {pat2} ...`" + +#~ msgid "" +#~ "Add all files under directories matching ``dir-pattern`` that match any " +#~ "of the listed patterns" +#~ msgstr "" +#~ "``dir-pattern`` に合致するディレクトリの下にあって、かつ、列挙されたパター" +#~ "ンのいずれかに合致するファイルをすべて追加する" + +#~ msgid ":samp:`recursive-exclude {dir-pattern} {pat1} {pat2} ...`" +#~ msgstr ":samp:`recursive-exclude {dir-pattern} {pat1} {pat2} ...`" + +#~ msgid "" +#~ "Remove all files under directories matching ``dir-pattern`` that match " +#~ "any of the listed patterns" +#~ msgstr "" +#~ "``dir-pattern`` に合致するディレクトリの下にあって、かつ、列挙されたパター" +#~ "ンのいずれかに合致するファイルをすべて削除する" + +#~ msgid ":samp:`global-include {pat1} {pat2} ...`" +#~ msgstr ":samp:`global-include {pat1} {pat2} ...`" + +#~ msgid "" +#~ "Add all files anywhere in the source tree matching any of the listed " +#~ "patterns" +#~ msgstr "" +#~ "ソースコードツリーのどこにあろうとも、列挙されたパターンのいずれかに合致す" +#~ "るファイルを追加する" + +#~ msgid ":samp:`global-exclude {pat1} {pat2} ...`" +#~ msgstr ":samp:`global-exclude {pat1} {pat2} ...`" + +#~ msgid "" +#~ "Remove all files anywhere in the source tree matching any of the listed " +#~ "patterns" +#~ msgstr "" +#~ "ソースコードツリーのどこにあろうとも、列挙されたパターンのいずれかに合致す" +#~ "るファイルを削除する" + +#~ msgid ":samp:`graft {dir-pattern}`" +#~ msgstr ":samp:`graft {dir-pattern}`" + +#~ msgid "Add all files under directories matching ``dir-pattern``" +#~ msgstr "" +#~ "``dir-pattern`` に合致するディレクトリの下にある全てのファイルを追加する" + +#~ msgid ":samp:`prune {dir-pattern}`" +#~ msgstr ":samp:`prune {dir-pattern}`" + +#~ msgid "Remove all files under directories matching ``dir-pattern``" +#~ msgstr "" +#~ "``dir-pattern`` に合致するディレクトリの下にあるすべてのファイルを削除する" + +#~ msgid "" +#~ "The patterns here are glob-style patterns: ``*`` matches zero or more " +#~ "regular filename characters (on Unix, everything except forward slash; on " +#~ "Windows, everything except backslash and colon); ``?`` matches a single " +#~ "regular filename character, and ``[chars]`` matches any one of the " +#~ "characters between the square brackets (which may contain character " +#~ "ranges, e.g., ``[a-z]`` or ``[a-fA-F0-9]``). Setuptools also has " +#~ "undocumented support for ``**`` matching zero or more characters " +#~ "including forward slash, backslash, and colon." +#~ msgstr "" +#~ "ここでのパターンは glob スタイルのもの: ``*`` はファイル名に使われる通常の" +#~ "文字 (UNIX ではスラッシュを除くすべて; Windows ではコロンを除くすべて) の " +#~ "0 個またはそれ以上の並びに合致; ``?`` はファイル名に使われる通常の文字 1 " +#~ "個に合致し、 ``[chars]`` は角括弧の間にある文字 (文字範囲を含んでも構いま" +#~ "せん。例えば ``[a-z]`` や ``[a-fA-F0-9]``) の内のいずれかひとつに合致しま" +#~ "す。ドキュメント化されていませんが、スラッシュかバックスラッシュかコロンだ" +#~ "けの 0 個またはそれ以上の並びに合致する ``**`` を Setuptools はサポートし" +#~ "ています。" + +#~ msgid "" +#~ "Directory patterns are relative to the root of the project directory; " +#~ "e.g., ``graft example*`` will include a directory named :file:`examples` " +#~ "in the project root but will not include :file:`docs/examples/`." +#~ msgstr "" +#~ "ディレクトリ向けのパターンはプロジェクトのルートディレクトリに対する相対パ" +#~ "スです; 例えば、 ``graft example*`` は、プロジェクトルートの直下にあ" +#~ "る :file:`examples` という名前のディレクトリを追加しますが、 :file:`docs/" +#~ "examples/` については追加しません。" + +#~ msgid "" +#~ "File & directory names in :file:`MANIFEST.in` should be ``/``-separated; " +#~ "setuptools will automatically convert the slashes to the local platform's " +#~ "appropriate directory separator." +#~ msgstr "" +#~ ":file:`MANIFEST.in` 内のファイルやディレクトリの名前は、 ``/`` で区切られ" +#~ "ていなければなりません; setuptools がスラッシュをローカルのプラットフォー" +#~ "ムに適切なディレクトリ分離子に置換してくれます。" + +#~ msgid "" +#~ "Commands are processed in the order they appear in " +#~ "the :file:`MANIFEST.in` file. For example, given the commands:" +#~ msgstr "" +#~ "コマンドは :file:`MANIFEST.in` ファイルに登場する順に実行されます。例え" +#~ "ば、以下のようなコマンドが与えられると:" + +#~ msgid "" +#~ "the contents of the directory tree :file:`tests` will first be added to " +#~ "the sdist, and then after that all files in the sdist with a ``.pyc``, " +#~ "``.pyo``, or ``.pyd`` extension will be removed from the sdist. If the " +#~ "commands were in the opposite order, then ``*.pyc`` files etc. would be " +#~ "only be removed from what was already in the sdist before " +#~ "adding :file:`tests`, and if :file:`tests` happened to contain any " +#~ "``*.pyc`` files, they would end up included in the sdist because the " +#~ "exclusion happened before they were included." +#~ msgstr "" +#~ ":file:`tests` ディレクトリ以下のコンテンツは、まず全てが sdist に追加され" +#~ "た後に、 ``.pyc`` ・ ``.pyo`` ・ ``.pyd`` の拡張子を持ったファイルがすべ" +#~ "て sdist から削除されます。逆順でコマンドを与えると、 ``*.pyc`` その他の" +#~ "ファイルについては、 :file:`tests` を追加する前に sdist に存在していたもの" +#~ "だけが取り除かれることになり、削除が追加の前に行われているの" +#~ "で :file:`tests` に ``*.pyc`` ファイルなどがあれば最終的な sdist に含まれ" +#~ "ることになります。" + +#~ msgid "" +#~ "Use `pkgutil-style namespace packages`_. This is recommended for new " +#~ "packages that need to support Python 2 and 3 and installation via both " +#~ "``pip`` and ``python setup.py install``." +#~ msgstr "" +#~ "`pkgutil 型の名前空間パッケージ `_ を用" +#~ "いる方法。 Python 2 および 3 をサポートする必要があって ``pip`` でも " +#~ "``python setup.py install`` でもインストールできるようにしたいなら、これが" +#~ "推奨される方法です。" + +#~ msgid "" +#~ "Use `pkg_resources-style namespace packages`_. This method is recommended " +#~ "if you need compatibility with packages already using this method or if " +#~ "your package needs to be zip-safe." +#~ msgstr "" +#~ "`pkg_resources 型の名前空間パッケージ `_ を使う方法。この手法を採用した既存のパッケージとの互換性を保つ" +#~ "必要がある場合か、あなたのパッケージに zip 耐性を持つ必要がある場合に推奨" +#~ "されます。" + +#~ msgid "" +#~ "Because ``mynamespace`` doesn't contain " +#~ "an :file:`__init__.py`, :func:`setuptools.find_packages` won't find the " +#~ "sub-package. You must use :func:`setuptools.find_namespace_packages` " +#~ "instead or explicitly list all packages in your :file:`setup.py`. For " +#~ "example:" +#~ msgstr "" +#~ "``my namespace`` が :file:`__init__.py` を含まないの" +#~ "で、 :func:`setuptools.find_packages` はサブパッケージを検出しようとしませ" +#~ "ん。代わりに :func:`setuptools.find_namespace_packages` を使うか、また" +#~ "は、 :file:`setup.py` にすべてのパッケージを明示的に列挙してください。例え" +#~ "ば:" + +#~ msgid "" +#~ "`June 2022 `_: ``EXTERNALLY-MANAGED`` " +#~ "marker file was originally specified in :pep:`668#marking-an-interpreter-" +#~ "as-using-an-external-package-manager`." +#~ msgstr "" +#~ "`2022年6月 `_: ``EXTERNALLY-MANAGED`` " +#~ "マーカファイルは、元々は :pep:`668#marking-an-interpreter-as-using-an-" +#~ "external-package-manager` で仕様化されていました。" + +#, fuzzy +#~ msgid "You can make sure that pip is up-to-date by running:" +#~ msgstr "" +#~ "Windows 用の Python インストーラは pip を含んでいます。次のようにすると " +#~ "pip が最新版であることを確実にすることができます:" + +#~ msgid "" +#~ "This guide discusses how to install packages using :ref:`pip` and a " +#~ "virtual environment manager: either :ref:`venv` for Python 3 " +#~ "or :ref:`virtualenv` for Python 2. These are the lowest-level tools for " +#~ "managing Python packages and are recommended if higher-level tools do not " +#~ "suit your needs." +#~ msgstr "" +#~ "このガイドでは、 :ref:`pip` と仮想環境マネージャ、つまり Python 3 で" +#~ "の :ref:`venv` か Python 2 での :ref:`virtualenv` を使ってパッケージをイン" +#~ "ストールする方法について議論します。これらは、Python のパッケージを管理す" +#~ "る最も低レベルのツールで、高レベルのツールがあなたのニーズに合わない時に推" +#~ "奨される方法です。" + +#~ msgid "Installing pip" +#~ msgstr "pip をインストールする" + +#~ msgid "" +#~ "Debian and most other distributions include a `python-pip`_ package; if " +#~ "you want to use the Linux distribution-provided versions of pip, " +#~ "see :doc:`/guides/installing-using-linux-tools`." +#~ msgstr "" +#~ "Debian や他のほとんどのディストロは `python-pip`_ パッケージを含んでいま" +#~ "す; Linuxのディストロが準備したバージョンの pip を使いたい場合は、 :doc:`/" +#~ "guides/installing-using-linux-tools` を見てください。" + +#~ msgid "" +#~ "You can also install pip yourself to ensure you have the latest version. " +#~ "It's recommended to use the system pip to bootstrap a user installation " +#~ "of pip:" +#~ msgstr "" +#~ "pip の最新版を使っていることを担保するために、自分自身でインストールするこ" +#~ "ともできます。ユーザ側で pip をインストールするためにシステム側で準備した " +#~ "pip をブートストラップとして使うことが推奨されています。" + +#~ msgid "Installing virtualenv" +#~ msgstr "virtualenv をインストールする" + +#~ msgid "" +#~ "If you are using Python 3.3 or newer, the :mod:`venv` module is the " +#~ "preferred way to create and manage virtual environments. venv is included " +#~ "in the Python standard library and requires no additional installation. " +#~ "If you are using venv, you may skip this section." +#~ msgstr "" +#~ "Python 3.3 またはそれ以降のものを使っているなら、 :mod:`venv` モジュールの" +#~ "方が仮想環境を作成・管理するのに好ましいです。 venv は Python の標準ライブ" +#~ "ラリに含まれていて、追加で何かをインストールしなければならないということが" +#~ "ありません。venv を使っているのであれば、この節を飛ばして構いません。" + +#~ msgid "" +#~ ":ref:`virtualenv` is used to manage Python packages for different " +#~ "projects. Using virtualenv allows you to avoid installing Python packages " +#~ "globally which could break system tools or other projects. You can " +#~ "install virtualenv using pip." +#~ msgstr "" +#~ ":ref:`virtualenv` は、異なるプロジェクトで使う Python パッケージを管理する" +#~ "ために使われていました。Python パッケージを大域的にインストールするとシス" +#~ "テムツールや他のプロジェクトを壊してしまいかねないのですが、 virtualenv を" +#~ "用いることでこれを避けることができます。virtualenv は pip でインストールで" +#~ "きます。" + +#~ msgid "It should be in the ``env`` directory:" +#~ msgstr "``env`` ディレクトリの中のものを使っているはずです。" + +#~ msgid "Leaving the virtual environment" +#~ msgstr "仮想環境から離脱する" + +#~ msgid "Installing specific versions" +#~ msgstr "特定のバージョンをインストールする" + +#~ msgid "pip can install a package directly from source, for example:" +#~ msgstr "" +#~ "pip はソースコードから直接にパッケージをインストールすることができます。例" +#~ "えば:" + +#~ msgid "Using other package indexes" +#~ msgstr "他のパッケージインデックスを使う" + +#~ msgid "Installing Packages:" +#~ msgstr "パッケージをインストールする:" + +#~ msgid "Miscellaneous:" +#~ msgstr "種々の事柄:" + +#~ msgid "The version of the project as supported by :pep:`440`." +#~ msgstr ":pep:`440` でサポートされた通りのプロジェクトのバージョン。" + +#~ msgid "" +#~ "Version numbering requirements and the semantics for specifying " +#~ "comparisons between versions are defined in :pep:`440`." +#~ msgstr "" +#~ "バージョンの付け方に関する要求事項や、バージョン間での比較方法を指定する意" +#~ "味づけは、 :pep:`440` に定義されています。" + +#~ msgid "" +#~ "The version specifiers section in this PEP supersedes the version " +#~ "specifiers section in :pep:`345`." +#~ msgstr "" +#~ "この PEP のバージョン指定子の節は、 :pep:`345` のバージョン指定子の節を置" +#~ "き換えるものです。" + +#~ msgid "Contents" +#~ msgstr "内容" + +#~ msgid "FIXME" +#~ msgstr "FIXME (ここを修正してください)" + +#~ msgid "mention the stable ABI (3.2+, link to the CPython C API docs)" +#~ msgstr "安定な ABI (3.2+ のこと。 CPython C API 説明文書にリンクすること)" + +#~ msgid "mention the implications of the GIL for extension modules" +#~ msgstr "拡張モジュール向けの GIL 実装について言及すること" + +#~ msgid "" +#~ "For interim guidance on this topic, see the discussion in :issue:`this " +#~ "issue <284>`." +#~ msgstr "" +#~ "この話題に関する暫定的なガイダンスが :issue:`この課題 <284>` にあります。" + +#~ msgid "cover publishing as wheel files on PyPI or a custom index server" +#~ msgstr "" +#~ "PyPI やその他のインデックスサーバに wheel ファイルを公開することについて書" +#~ "くこと" + +#~ msgid "cover creation of Windows and macOS installers" +#~ msgstr "Windows 向けや macOS 向けのインストーラの作り方について書くこと" + +#~ msgid "" +#~ "mention the fact that Linux distros have a requirement to build from " +#~ "source in their own build systems, so binary-only releases are strongly " +#~ "discouraged" +#~ msgstr "" +#~ "Linux のディストロ群ではそれぞれのビルドシステムでソースコードからビルドで" +#~ "きることを要求するので、バイナリのみのリリースは強い非推薦の状態にあるとい" +#~ "う事実について書くこと" + +#~ msgid "" +#~ "This section covers the basics of how to create documentation using " +#~ "`Sphinx`_ and host the documentation for free in `Read The Docs`_." +#~ msgstr "" +#~ "この節では、 `Sphinx`_ を用いて説明文書を作成する方法の基礎と、 `Read The " +#~ "Docs`_ に無料で説明文書をホストしてもらう方法を説明します。" + +#~ msgid "Installing Sphinx" +#~ msgstr "Sphinx をインストールする" + +#~ msgid "Use ``pip`` to install Sphinx:" +#~ msgstr "``pip`` を使って Sphinx をインストールするには:" + +#~ msgid "" +#~ "For other installation methods, see this :doc:`installation guide " +#~ "` by Sphinx." +#~ msgstr "" +#~ "その他のインストール方法については、 Sphinx による :doc:`インストールガイ" +#~ "ド ` を見てください。" + +#~ msgid "Getting Started With Sphinx" +#~ msgstr "Sphinx の初めの第一歩" + +#~ msgid "" +#~ "Create a ``docs`` directory inside your project to hold your " +#~ "documentation:" +#~ msgstr "" +#~ "プロジェクトの中に説明文書を保持するための ``docs`` ディレクトリを作成しま" +#~ "す:" + +#~ msgid "Run ``sphinx-quickstart`` inside the ``docs`` directory:" +#~ msgstr "" +#~ "``docs`` ディレクトリ内で ``sphinx-quickstart`` コマンドを実行します:" + +#~ msgid "" +#~ "This sets up a source directory, walks you through some basic " +#~ "configurations, and creates an ``index.rst`` file as well as a " +#~ "``conf.py`` file." +#~ msgstr "" +#~ "これは、ソースディレクトリを作成し、いくつかの基本的な設定事項を渉猟し、 " +#~ "``conf.py`` ファイルと同様に ``index.rst`` ファイルを生成します。" + +#~ msgid "" +#~ "You can add some information about your project in ``index.rst``, then " +#~ "build them:" +#~ msgstr "" +#~ "``index.rst`` にプロジェクトに関する情報をいくらか追加して、ビルドします:" + +#~ msgid "" +#~ "For more details on the build process, see this `guide`_ by Read The Docs." +#~ msgstr "" +#~ "ビルドのプロセスに関するもっと詳しいことは、 Read The Docs の `ガイド " +#~ "`_ を見てください。" + +#~ msgid "" +#~ "For a more detailed guide on how to use Sphinx and reStructuredText, " +#~ "please see this `documentation tutorial`_ on Hitchhiker's Guide to Python." +#~ msgstr "" +#~ "Sphinx と reStructuredText の使い方に関するもっと詳細なガイドについては、 " +#~ "Python のためのヒッチハイカーズガイドの中の `説明文書を作るチュートリアル " +#~ "`_ を見てください。" + +#~ msgid "" +#~ "Essential tools and concepts for working within the Python development " +#~ "ecosystem are covered in our :doc:`tutorials/index` section:" +#~ msgstr "" +#~ "Python での開発に関わるエコシステム内で使われる基本的なツールや概念につい" +#~ "ては、 :doc:`チュートリアル ` 節に記述しています:" + +#~ msgid "" +#~ "To get an overview of packaging options for Python libraries and " +#~ "applications, see the :doc:`Overview of Python Packaging `" +#~ msgstr "" +#~ "Python ライブラリとアプリケーション向けのパッケージングオプションの概要を" +#~ "得るには、 :doc:`Python におけるパッケージングの概要 ` を見てく" +#~ "ださい" + +#~ msgid "Learn more" +#~ msgstr "さらに学ぶ" + +#~ msgid "" +#~ "Beyond our :doc:`tutorials/index`, this guide has several other resources:" +#~ msgstr "" +#~ ":doc:`tutorials/index` を越える話題については、このガイドには他にいくつか" +#~ "のリソースがあります:" + +#~ msgid "" +#~ "The :doc:`guides/index` section for walk throughs, such as :doc:`guides/" +#~ "installing-using-linux-tools` or :doc:`guides/packaging-binary-" +#~ "extensions`." +#~ msgstr "" +#~ "一通り通して知るには :doc:`ガイド ` の :doc:`linux のツール" +#~ "を使ってインストールする ` や :doc:`" +#~ "バイナリ拡張をパッケージ化する ` な" +#~ "ど。" + +#~ msgid "" +#~ "The :doc:`discussions/index` section for in-depth references on topics " +#~ "such as :doc:`discussions/deploying-python-applications` " +#~ "or :doc:`discussions/pip-vs-easy-install`." +#~ msgstr "" +#~ ":doc:`python アプリケーションを配置する ` や :doc:`pip 対 easy-install ` のような詳細に渡る議論を参照するには :doc:`議論 ` の節を見てください。" + +#~ msgid "" +#~ "``requires`` is a list of packages that are needed to build your package. " +#~ "You don't need to install them; build frontends like :ref:`pip` will " +#~ "install them automatically in a temporary, isolated virtual environment " +#~ "for use during the build process." +#~ msgstr "" +#~ "``requires`` は、当該パッケージをビルドするために必要となるパッケージ群を" +#~ "列挙したものです。これらを自分でインストールする必要はなく; :ref:`pip` の" +#~ "ようなビルドフロントエンドが、ビルド作業の一環として、一時的で隔離された仮" +#~ "想環境に自動的にインストールしてくれることでしょう。" + +#~ msgid "" +#~ "It uses the `sigstore/gh-action-sigstore-python GitHub Action`_, and then " +#~ "uploads them to a GitHub Release." +#~ msgstr "" +#~ "それには `sigstore/gh-action-sigstore-python GitHub Action`_ を使い、それ" +#~ "から GitHub Release にアップロードします。" + +#~ msgid "" +#~ "It's important to note that the term \"package\" in this context is being " +#~ "used to describe a bundle of software to be installed (i.e. as a synonym " +#~ "for a :term:`distribution `). It does not to refer " +#~ "to the kind of :term:`package ` that you import in your " +#~ "Python source code (i.e. a container of modules). It is common in the " +#~ "Python community to refer to a :term:`distribution ` using the term \"package\". Using the term \"distribution\" is " +#~ "often not preferred, because it can easily be confused with a Linux " +#~ "distribution, or another larger software distribution like Python itself." +#~ msgstr "" +#~ "この文脈では、 \"パッケージ\" という用語が、インストールされるソフトウェア" +#~ "の束を表すものである (すなわち、 :term:`配布物 ` の" +#~ "同義語である) ことを注記しておくことは重要です。 Python のなんらかのソース" +#~ "コードをインポートする (つまり、モジュール群の) 容れ物としての :term:`パッ" +#~ "ケージ ` のことを指してはいないのです。 Python のコミュニ" +#~ "ティでは、 :term:`配布物 ` のことを \"パッケージ\" " +#~ "という用語で呼ぶことは一般的に行われています。 Linux ディストロや、 " +#~ "Python そのもののようなその他の大きなソフトウェア配布物と紛らわしいので、 " +#~ "\"配布物\" という用語を使うことはしばしば歓迎されません。" + +#~ msgid "" +#~ "`Docs `__ | `Issues " +#~ "`__" +#~ msgstr "" +#~ "`説明文書 `__ | `課題リ" +#~ "スト `__" + +#~ msgid "Saving credentials on GitHub" +#~ msgstr "GitHub に認証情報を保存する" + +#~ msgid "" +#~ "In this guide, we'll demonstrate uploading to both PyPI and TestPyPI, " +#~ "meaning that we'll have two separate sets of credentials. And we'll need " +#~ "to save them in the GitHub repository settings." +#~ msgstr "" +#~ "このガイドでは、 PyPI と TestPyPI の両方へのアップロードを実演するので、二" +#~ "組の別々の認証情報を持つことになります。そして、それらを GitHub のリポジト" +#~ "リ設定の中に保存する必要があります。" + +#~ msgid "" +#~ "Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +#~ "token`_. If you have the project on PyPI already, limit the token scope " +#~ "to just that project. You can call it something like ``GitHub Actions CI/" +#~ "CD — project-org/project-repo`` in order for it to be easily " +#~ "distinguishable in the token list. **Don't close the page just yet — you " +#~ "won't see that token again.**" +#~ msgstr "" +#~ "https://pypi.org/manage/account/#api-tokens へ行って新しい `APIトークン " +#~ "`_ を作成してください。もう PyPI に自分のプロジェクトを持ってい" +#~ "るのであれば、トークンのスコープをそのプロジェクトだけに限定してください。" +#~ "トークンのリストの中で容易に見分けがつくように、何か ``GitHub Actions CI/" +#~ "CD — project-org/project-repo`` のような名前にしましょう。 **まだページを" +#~ "閉じないで -- トークンを再び見る機会はないですよ。**" + +#~ msgid "" +#~ "In a separate browser tab or window, go to the ``Settings`` tab of your " +#~ "target repository and then click on `Secrets`_ in the left sidebar." +#~ msgstr "" +#~ "ブラウザで別のタブかウィンドウを開いて、対象になっているリポジトリの " +#~ "``Settings`` タブへ行き、左側のサイドバーにある `Secrets`_ の部分をクリッ" +#~ "クしてください。" + +#~ msgid "" +#~ "Create a new secret called ``PYPI_API_TOKEN`` and copy-paste the token " +#~ "from the first step." +#~ msgstr "" +#~ "``PYPI_API_TOKEN`` と言う名前で新しい secret を作成し、先ほど作成したトー" +#~ "クンをコピーしましょう。" + +#~ msgid "" +#~ "Now, let's add initial setup for our job. 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:" +#~ msgstr "" +#~ "さて、我々のジョブについて最初の設定を追加しましょう。それは、我々が後で定" +#~ "義するであろうコマンドを実行するようなプロセスです。このガイドでは、" +#~ "GitHub Actions で提供される Ubuntu LTS の最新版を使います:" + +#~ msgid "Then, add the following under the ``build-n-publish`` section:" +#~ msgstr "それから、以下のものを ``build-n-publish`` 節に追加しましょう:" + +#, fuzzy +#~ msgid "" +#~ "You can use any other method for building distributions as long as it " +#~ "produces ready-to-upload artifacts saved into the ``dist/`` folder. You " +#~ "can even use ``actions/upload-artifact`` and ``actions/download-" +#~ "artifact`` to transfer files between jobs or make them accessible for " +#~ "download from the web CI interface." +#~ msgstr "" +#~ "アップロードできる状態の創作物を ``dist/`` ディレクトリに保存するという条" +#~ "件を満たすのであれば、他のどのような方法で配布物をビルドしても構いません。" +#~ "ジョブからジョブへファイルを転送するのに ``actions/upload-artifact`` や " +#~ "``actions/download-artifact`` を使ったり、ウェブの CI インタフェースからダ" +#~ "ウンロードできるようにすることでそれらにアクセスすることを可能にしたりする" +#~ "ことさえできます。" + +#~ msgid "So add this to the steps list:" +#~ msgstr "そこでこれを手順のリストに追加しましょう:" + +#~ msgid "" +#~ "These two steps use the `pypa/gh-action-pypi-publish`_ GitHub Action: the " +#~ "first one uploads contents of the ``dist/`` folder into TestPyPI " +#~ "unconditionally and the second does that to PyPI, but only if the current " +#~ "commit is tagged. It is recommended you use the latest release tag; a " +#~ "tool like GitHub's dependabot can keep these updated regularly." +#~ msgstr "" +#~ "これらふたつの手順は、 `pypa/gh-action-pypi-publich`_ GitHub アクションを" +#~ "使います: 一つ目は ``dist/`` ディレクトリの中身を無条件に TestPyPI にアッ" +#~ "プロードする時で、二つ目はそのコミットがタグ付けされている場合に限って " +#~ "PyPI へ送る時です。最新のリリースタグを用いることが推奨されています; " +#~ "GitHub のdependabot のようなツールが恒常的に更新されている状態を保つことが" +#~ "できるのです。" + +#~ msgid "" +#~ "`Docs `__ | `GitHub `__ | " +#~ "`PyPI `__" +#~ msgstr "" +#~ "`説明文書 `__ | `GitHub `__ | " +#~ "`PyPI `__" + +#~ msgid "_`https://bazaar.canonical.com` *(Not responding as of 5/2023)*" +#~ msgstr "_`https://bazaar.canonical.com` *(2023年5月時点で応答しません)*" + +#~ msgid "" +#~ "Using naming convention for plugins also allows you to query the Python " +#~ "Package Index's `simple API`_ for all packages that conform to your " +#~ "naming convention." +#~ msgstr "" +#~ "プラグインの命名規則を用いることで、あなたの命名規則に従うすべてのパッケー" +#~ "ジについてPython パッケージインデックスの `simple API`_ から検索することも" +#~ "できるようになります。" + +#~ msgid "" +#~ "For complete documentation of the simple repository protocol, " +#~ "see :pep:`503`." +#~ msgstr "" +#~ "単純なリポジトリプロトコルの完全な説明文書としては、 :pep:`503` を見てくだ" +#~ "さい。" + +#~ msgid "" +#~ "PDM is a modern Python package manager with :pep:`582` support. It " +#~ "installs and manages packages in a similar way to ``npm`` that doesn't " +#~ "need to create a :term:`virtual environment` at all. It also " +#~ "uses :term:`pyproject.toml` to store project metadata as defined " +#~ "in :pep:`621`." +#~ msgstr "" +#~ "PDM は、近代的な Python パッケージ管理ソフトで、 :pep:`582` をサポートして" +#~ "います。 :term:`仮想環境 ` を作る必要が全くない " +#~ "``npm`` と似たやり方でパッケージをインストール・管理します。 :pep:`621` で" +#~ "定義されているように、プロジェクトのメタデータを :term:`pyproject.toml` に" +#~ "保存します。" + +#~ 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 `__ に文" +#~ "書化されています。" + +#~ msgid "" +#~ "To install from other data sources (for example Amazon S3 storage) you " +#~ "can create a helper application that presents the data in a :pep:`503` " +#~ "compliant index format, and use the ``--extra-index-url`` flag to direct " +#~ "pip to use that index." +#~ msgstr "" +#~ ":pep:`503` 準拠のインデックスフォーマットに合わせてデータを表現するような" +#~ "ヘルパーアプリケーションを作成すれば、 pip を ``--extra-index-url`` フラグ" +#~ "でそのインデックスへ向け直すことで、他のデータソース (例えば Amazon S3 ス" +#~ "トレージ) からインストールすることができます。" + +#~ msgid "" +#~ "`PDM `_ for a modern Python package " +#~ "management tool supporting :pep:`582` (replacing virtual environments " +#~ "with ``__pypackages__`` directory for package installation) and relying " +#~ "on standards such as :pep:`517` and :pep:`621`." +#~ msgstr "" +#~ "`PDM `_ は、近代的な Python パッケージ" +#~ "管理ツールで、 (パッケージインストールのための ``__pypackages__`` ディレク" +#~ "トリを採用した仮想環境を置き換える) :pep:`582` をサポートしてお" +#~ "り、 :pep:`517` や :pep:`621` のような標準に立脚しています。" + +#~ msgid "" +#~ "It may also be known that project A follows semantic versioning, and that " +#~ "v2 of 'A' will indicate a break in compatibility, so it makes sense to " +#~ "not allow v2:" +#~ msgstr "" +#~ "また、Aがセマンティックバージョニングの方法に従っていて'A'の(将来の)v2は互" +#~ "換性を持たなくなるだろうかということがわかっているので、(自分たちのプロ" +#~ "ジェクトの側では)v2を許容したくないとしましょう：" + +#~ msgid ":term:`Wheel` has an :pep:`official PEP <427>`. :term:`Egg` did not." +#~ msgstr "" +#~ ":term:`Wheel`には :pep:`公式PEP <427>`が存在します。 :term:`Egg`には対応す" +#~ "るPEPがありません。" + +#~ msgid "" +#~ "Circumstantially, in some cases, wheels can be used as an importable " +#~ "runtime format, although :pep:`this is not officially supported at this " +#~ "time <427#is-it-possible-to-import-python-code-directly-from-a-wheel-" +#~ "file>`." +#~ msgstr "" +#~ ":pep:`Wheelファイルから直接にimportすることは現時点では公式にサポートされ" +#~ "ていません<427#is-it-possible-to-import-python-code-directly-from-a-wheel-" +#~ "file>`が、状況によって幾つかのケースでwheelは重要な実行時フォーマットとし" +#~ "て使われます。" + +#~ msgid "" +#~ "A :term:`Built Distribution` format introduced by :pep:`427`, which is " +#~ "intended to replace the :term:`Egg` format. Wheel is currently supported " +#~ "by :ref:`pip`." +#~ msgstr "" +#~ ":term:`Egg` フォーマットを代替することを意図して :pep:`427` で導入され" +#~ "た :term:`ビルド済配布物`。現在、:ref:`pip`はWheelをサポートしている。" + +#~ msgid "" +#~ "Note that the rows are stored in a partitioned, which helps limit the " +#~ "cost of queries. These example queries analyze downloads from recent " +#~ "history by filtering on the ``timestamp`` column." +#~ msgstr "" +#~ "クエリのコストを削減するためにデータベースの行がパーティションされた状態で" +#~ "格納されていることを覚えておいてください。これらの例では、``timestamp`` カ" +#~ "ラムを使って絞り込むことで最近のダウンロード履歴を分析しています。" + +#~ msgid "" +#~ "To only count downloads from pip, filter on the " +#~ "``details.installer.name`` column." +#~ msgstr "" +#~ "pipを通じてダウンロードされた数だけを数えるには、" +#~ "``details.installer.name``カラムを使って抽出します。" + +#~ msgid "For CentOS, see here: https://www.softwarecollections.org/en/" +#~ msgstr "" +#~ "CentOS の場合は、こちらを見てください: https://" +#~ "www.softwarecollections.org/en/" + +#~ msgid "Debian/Ubuntu" +#~ msgstr "Debian/Ubuntu" + +#~ msgid "" +#~ "This will download your repository into the CI runner and then install " +#~ "and activate Python 3.10." +#~ msgstr "" +#~ "これによって、あなたのリポジトリを CI ランナーにダウンロードして、 Python " +#~ "3.10 をインストールしアクティベートすることになります。" + +#~ 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 `bottle.py `_ " +#~ "and :doc:`boltons `." +#~ msgstr "" +#~ "この方法は、単純なスクリプトやスニペットを互換性のあるバージョンの Python " +#~ "を持っている人たちどうしで (電子メールや StackOverflow や GitHub gists な" +#~ "どで) 共有するには優れた方法です。例えば `bottle.py `_ and :doc:`boltons ` のように、 Python " +#~ "ライブラリ全体をこのやり方で共有することをオプションの一つとして提供してい" +#~ "るものさえあります。" + +#~ msgid "" +#~ "Computing as we know it is defined by the ability to execute programs. " +#~ "Every operating system natively supports one or more formats of program " +#~ "they can natively execute." +#~ msgstr "" +#~ "我々が知るところのコンピューティングは、プログラムを実行する能力として定義" +#~ "されます。それぞれのオペレーティングシステムは、そのまま実行することが可能" +#~ "なひとつかもっと多くのプログラムフォーマットを元々サポートしています。" + +#~ msgid "" +#~ "These techniques are mostly reserved for larger scale deployments in data " +#~ "centers, though certain complex applications can benefit from this " +#~ "packaging. Technologies are Python agnostic, and include:" +#~ msgstr "" +#~ "このような手法は、複雑なアプリケーションの中にはこのパッケージング方法から" +#~ "利益を得るものもありますが、たいていの場合はデータセンタにおけるかなり大規" +#~ "模な配置のために使用します。技術としては Python を直接サポートしているわけ" +#~ "ではなく、次のものを含みます:" + +#~ msgid "" +#~ "Either because that character is inconvenient or potentially confusing in " +#~ "some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used " +#~ "to denote the user's home directory in POSIX), or because the advantages " +#~ "weren't sufficiently compelling to justify changing the existing " +#~ "reference implementation for the wheel format defined in :pep:427 (for " +#~ "example, using ``,`` rather than ``.`` to separate components in a " +#~ "compressed tag)." +#~ msgstr "" +#~ "それは、その文字が不便であるかコンテクストによっては潜在的に混乱を招きやす" +#~ "い (例えば ``+`` は URL 内ではクォートしなければなりませんし、 ``~`` は " +#~ "POSIX でユーザのホームディレクトリを示すために使われます) から、あるい" +#~ "は、 :pep:427 で定義された wheel フォーマットを参照して作成された既存の実" +#~ "装を変更すること (例えば、圧縮タグで部分部分を分割するのに ``.`` ではなく " +#~ "``,`` を使うようにすること) を正当化するに足りるだけのアドバンテージがない" +#~ "から、のいずれかです。" + +#~ 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 `bottle.py `_ and :doc:`boltons `." +#~ msgstr "" +#~ "この方法は、単純なスクリプトやスニペットを互換性のあるバージョンの Python " +#~ "を持っている人たちどうしで (電子メールや StackOverflow や GitHub gists な" +#~ "どで) 共有するには優れた方法です。例えば `bottle.py `_ や :doc:`boltons ` のように、 " +#~ "Python ライブラリ全体をこのやり方で共有することをオプションの一つとして提" +#~ "供しているものさえあります。" + +#~ msgid "" +#~ "It's the command line interface for running various commands that relate " +#~ "to packaging tasks. To get a listing of available commands, run ``python " +#~ "setup.py --help-commands``." +#~ msgstr "" +#~ "それは、パッケージングする上での作業項目に関連したさまざまなコマンドを走ら" +#~ "せるためのコマンドラインインタフェイスです。使用可能なコマンドを一覧するに" +#~ "は、 ``python setup.py --help-commands`` を実行してください。" + +#~ msgid "" +#~ "A variation on the above which pre-builds the installation files for the " +#~ "requirements using :ref:`python -m pip wheel `:" +#~ msgstr "" +#~ ":ref:`python -m pip wheel ` を用いて依存先パッケージのイン" +#~ "ストール用ファイルをあらかじめビルドしておくという上記のバリエーション:" + +#~ 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 ``python -c ''`` to invoke the " +#~ "application's main entry point directly." +#~ msgstr "" +#~ "最初に ``pkg_resources`` をインポートするよりも前に " +#~ "``__main__.__requires__`` の中のすべての依存関係を設定しておくことでこの問" +#~ "題を回避することができますが、このアプローチでは影響を受けるツールを標準の" +#~ "コマンドラインからの呼び出しで使うことができないことになります - つまり、" +#~ "独自のラッパスクリプトを書くか、アプリケーションの main エントリポイントを" +#~ "直接に呼び出すための ``python -c ''`` を使うかしなければなりませ" +#~ "ん。" + +#~ msgid "https://bazaar.canonical.com" +#~ msgstr "https://bazaar.canonical.com" + +#~ msgid "" +#~ "This guide *assumes* that you already have a project that you know how to " +#~ "build distributions for and *it lives on GitHub*." +#~ msgstr "" +#~ "このガイドでは、配布物をビルドするやり方がわかっているプロジェクトが " +#~ "*GitHub に置いてある* ことを *前提* にしています。" + +#~ msgid "" +#~ "And now we can build dists from source. In this example, we'll use " +#~ "``build`` package, assuming that your project has a ``pyproject.toml`` " +#~ "properly set up (see :pep:`517`/:pep:`518`)." +#~ msgstr "" +#~ "そして、今や我々はソースコードから配布物をビルドすることができます。この例" +#~ "では、あなたのプロジェクトの ``pyproject.toml`` が適切に設定されている " +#~ "(:pep:`517` と :pep:`518` を参照してください) ことを仮定して、 ``build`` " +#~ "パッケージを用いることになります。" + +#~ msgid "" +#~ "You can use any other method for building distributions as long as it " +#~ "produces ready-to-upload artifacts saved into the ``dist/`` folder." +#~ msgstr "" +#~ "アップロードできる状態の創作物を ``dist/`` ディレクトリに保存するという条" +#~ "件を満たすのであれば、どのような方法で配布物をビルドしても構いません。" + +#~ msgid "" +#~ "This JSON file MUST be a dictionary, compliant with :rfc:`8259` and UTF-8 " +#~ "encoded." +#~ msgstr "" +#~ "この JSON ファイルは、:rfc:`8259` を満足する辞書になっていて、かつ、 " +#~ "UTF-8 エンコーディングでなければなりません。" + +#~ msgid "" +#~ "If present, it MUST contain at least two fields. The first one is " +#~ "``url``, with type ``string``. Depending on what ``url`` refers to, the " +#~ "second field MUST be one of ``vcs_info`` (if ``url`` is a VCS reference), " +#~ "``archive_info`` (if ``url`` is a source archives or a wheel), or " +#~ "``dir_info`` (if ``url`` is a local directory). These info fields have a " +#~ "(possibly empty) subdictionary as value, with the possible keys defined " +#~ "below." +#~ msgstr "" +#~ "もし存在すれば、それは少なくともふたつのフィールドを含んでいなければなりま" +#~ "せん。第１のものは ``string`` 型の ``url`` です。 ``url`` が何を参照してい" +#~ "るかによって、第２のフィールドは、 (``url`` が VCS への参照であるなら) " +#~ "``vcs_info`` であるか、 (``url`` がソースコードのアーカイブまたは wheel を" +#~ "参照しているなら) ``archive_info`` であるか、または、 (``url`` がローカル" +#~ "のディレクトリを参照しているなら) ``dir_info`` であるか、このうちのひとつ" +#~ "でなければなりません。これらの情報フィールドは、以下に定義する取り得るキー" +#~ "と共に、 (空であることも可能ですが) サブディレクトリを値に取ります。" + +#~ msgid "" +#~ "``url`` MUST be stripped of any sensitive authentication information, for " +#~ "security reasons." +#~ msgstr "" +#~ "``url`` は、セキュリティ上の理由から、機微に関わる認証情報をすべて削除して" +#~ "おかなければなりません。" + +#~ msgid "" +#~ "A ``commit_id`` key (type ``string``) MUST be present, containing the " +#~ "exact commit/revision number that was installed. If the VCS supports " +#~ "commit-hash based revision identifiers, such commit-hash MUST be used as " +#~ "``commit_id`` in order to reference the immutable version of the source " +#~ "code that was installed." +#~ msgstr "" +#~ "``commit_id`` キー (``string`` 型) は、正確にどのコミットまたはリビジョン" +#~ "がインストールされたかを示すもので、必須のキーです。 VCS がリビジョン識別" +#~ "子に基づくコミットハッシュをサポートしているなら、インストールされたものの" +#~ "ソースコードの不変のバージョンを指し示す目的で、そのようなコミットハッシュ" +#~ "を ``commit_id`` として使わなければなりません。" + +#~ msgid "" +#~ "``editable`` (type: ``boolean``): ``true`` if the distribution was " +#~ "installed in editable mode, ``false`` otherwise. If absent, default to " +#~ "``false``." +#~ msgstr "" +#~ "``editable`` (``boolean`` 型): 配布物が編集可能モードでインストールされて" +#~ "いる場合には ``true`` 、そうでなければ ``false`` 。存在していない場合のデ" +#~ "フォルトは ``false`` です。" + +#~ msgid "" +#~ "When ``url`` refers to a local directory, it MUST have the ``file`` sheme " +#~ "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`` が存在していなければなりません。特にパス部分は絶対パスでなけれ" +#~ "ばなりません。相対パスを絶対パスに変換する際には、シンボリックリンクはその" +#~ "まま保存されるべきです。" + +#~ msgid "" +#~ "Installers 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/`` で始まる参照はブランチに対応します。" + +#~ msgid "Example direct_url.json" +#~ msgstr "direct_url.json の例" + +#~ msgid "Local directory installed in editable mode:" +#~ msgstr "編集可能モードでインストールされたローカルディレクトリ:" + +#~ msgid "" +#~ "The platform compatibility tagging model used for the ``wheel`` " +#~ "distribution format is defined in :pep:`425`." +#~ msgstr "" +#~ "``wheel`` 配布物フォーマットに使われるプラットフォーム互換性タグのタグ付け" +#~ "モデルは、 :pep:`425` で定義されています。" + +#~ msgid "Platform tags for Windows" +#~ msgstr "Windows 向けプラットフォームタグ" + +#~ msgid "" +#~ "The scheme defined in :pep:`425` covers public distribution of wheel " +#~ "files to systems running Windows." +#~ msgstr "" +#~ ":pep:`425` で定義されたスキームは、 Windows で動作するシステム向けの " +#~ "wheel ファイルの公開配布物をカバーします。" + +#~ msgid "Platform tags for macOS (Mac OS X)" +#~ msgstr "macOS (Mac OSX) 向けのプラットフォームタグ" + +#~ msgid "" +#~ "The scheme defined in :pep:`425` covers public distribution of wheel " +#~ "files to systems running macOS (previously known as Mac OS X)." +#~ msgstr "" +#~ ":pep:`425` で定義されたスキームは、 macOS (かつての Mac OS X) で動作するシ" +#~ "ステム向けの wheel ファイルの公開配布物をカバーします。" + +#~ msgid "Platform tags for common Linux distributions" +#~ msgstr "普通の Linux ディストロ向けのプラットフォームタグ" + +#~ msgid "Platform tags for other \\*nix platforms" +#~ msgstr "その他の \\*nix プラットフォーム向けのプラットフォームタグ" + +#~ msgid "" +#~ "The scheme defined in :pep:`425` is not generally sufficient for public " +#~ "distribution of wheel files to other \\*nix platforms. Efforts are " +#~ "currently (albeit intermittently) under way to define improved " +#~ "compatibility tagging schemes for AIX and for Alpine Linux." +#~ msgstr "" +#~ ":pep:`425` で定義されたスキームは、その他の \\*nix プラットフォーム向けに" +#~ "公開された wheel 配布物にとって常に十分なものではありません。 AIX 向けや " +#~ "Alpine Linux 向けに改良された互換性タグのスキームを定義する努力が (断続的" +#~ "とは言え) 現在も続けられています。" + +#~ msgid "" +#~ "For projects which don't provide their own Windows installers (and even " +#~ "some which do), Christoph Gohlke at the University of California provides " +#~ "a `collection of Windows installers `__. Many Python users on Windows have reported a positive " +#~ "experience with these prebuilt versions." +#~ msgstr "" +#~ "独自の Windows 版インストーラを準備していないプロジェクトについては (そし" +#~ "て、準備しているプロジェクトでもその内のいくつかについては) 、カリフォルニ" +#~ "ア大学の Christoph Gohlke さんが `Windows 版インストーラのコレクション " +#~ "`__ を提供しています。Windows" +#~ "で Python を使う多くのユーザが、これらのビルド済みのバージョン(のパッケー" +#~ "ジ) について肯定的な評価を報告しています。" + +#~ msgid "" +#~ "Earlier versions of setuptools implemented the ``attr:`` directive by " +#~ "importing the module, but setuptools 46.4.0 added rudimentary AST " +#~ "analysis so that ``attr:`` can function without having to import any of " +#~ "the package's dependencies." +#~ msgstr "" +#~ "setuptools の初期のバージョンでは、モジュールをインポートすることで " +#~ "``attr:`` ディレクティブを実装していましたが、setuptools 46.4.0 で初歩的" +#~ "な AST 解析が追加されたので ``attr:`` が他の依存先パッケージをインポートし" +#~ "なくても機能するようになりました。" + +#~ msgid "" +#~ ":doc:`Setuptools ` provides :doc:`special support " +#~ "` for plugins. By providing the " +#~ "``entry_points`` argument to :func:`setup` in :file:`setup.py` plugins " +#~ "can register themselves for discovery." +#~ msgstr "" +#~ ":doc:`Setuptools ` はプラグイン向けに :doc:`特別なサ" +#~ "ポート ` を提供していま" +#~ "す。 :file:`setup.py` の中の :func:`setup`の ``entry_points`` 引数を準備す" +#~ "ることで、プラグインが検出されるように登録することができます。" + +#~ msgid "" +#~ "A corresponding :ref:`core metadata ` field does not exist" +#~ msgstr "" +#~ "対応する :ref:`コアとなるメタデータ ` のフィールドは存在し" +#~ "ない" + +#~ msgid "" +#~ ":doc:`Docs ` | `Issues `__ | `Bitbucket `__ | `PyPI `__" +#~ msgstr "" +#~ ":doc:`説明文書 ` | `課題リスト `__ | `Bitbucket `__ | `PyPI `__" + +#~ msgid "" +#~ "`GitHub and Docs `__ | `PyPI " +#~ "`__" +#~ msgstr "" +#~ "`GitHub と説明文書 `__ | `PyPI " +#~ "`__" + +#~ msgid "" +#~ "``license`` is the path to the :file:`LICENSE` file, described below." +#~ msgstr "" +#~ "``license`` は、下に記述するように、 :file:`LICENSE` ファイルへのパスで" +#~ "す。" + +#~ msgid "" +#~ "For more information, see `Automatic Script Creation `_ from the :doc:`setuptools docs " +#~ "`." +#~ msgstr "" +#~ "詳しくは、:doc:`setuptools 説明文書 ` の `スクリプトの自" +#~ "動生成 `_ を見てくださ" +#~ "い。" + +#~ msgid "" +#~ "All other fields are considered optional and my be specified statically, " +#~ "listed as dynamic, or left unspecified." +#~ msgstr "" +#~ "他の全てのフィールドは必須ではないものと解釈され、これらは静的に指定しても" +#~ "動的にリストしても未指定のままにしていても構いません。" + +#~ msgid "Install `setuptools extras`_." +#~ msgstr "`setuptools extras`_ をインストールする。" + +#~ 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 features very pretty " +#~ "terminal colors." +#~ msgstr "" +#~ "Pipenv は、全てのパッケージング世界の最良のものを Python 世界に持ち込むこ" +#~ "とを目的とするプロジェクトです。 :ref:`Pipfile` ・ :ref:`pip` " +#~ "・ :ref:`virtualenv` を単一のツールチェーンにまとめ上げるものです。端末上" +#~ "で綺麗な色彩を持っています。" + +#~ msgid "" +#~ "Pipenv aims to help users manage environments, dependencies, and imported " +#~ "packages on the command line. It also works well on Windows (which other " +#~ "tools often underserve), makes and checkes file hashes, to ensure " +#~ "compliance with hash-locked dependency specifiers, and eases " +#~ "uninstallation of packages and dependencies. It is used by Python users " +#~ "and system administrators, but has been less maintained since late 2018." +#~ msgstr "" +#~ "Pipenv は、ユーザがコマンドラインで環境・依存関係・インポートされたパッ" +#~ "ケージを管理することを補助することを目的としています。 (他のツールが往々に" +#~ "してうまく動かない) Windows 上でもきちんと動作し、ファイルのハッシュ値を計" +#~ "算し確認することでハッシュ値による依存関係識別子との互換性を確保し、パッ" +#~ "ケージの依存関係先のアンインストールを容易にします。Python ユーザやシステ" +#~ "ム管理者に使われてきましたが、 2018 年後半以降はあまりメンテナンスされなく" +#~ "なりました。" + +#~ msgid "" +#~ "`GitHub and Docs `__ | `PyPI `__" +#~ msgstr "" +#~ "`GitHub と説明文書 `__ | `PyPI `__" + +#~ msgid "" +#~ "These fields 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." +#~ msgstr "" +#~ "これらのフィールドは、 ``name`` と ``email`` のふたつのキーを伴ったテーブ" +#~ "ルの配列を受け入れます。両方の値は文字列でなければなりません。 ``name`` の" +#~ "値は、電子メールアドレスにおける正当な名前 (すなわち、 :rfc:`822` における" +#~ "電子メールアドレスのアドレス部分に前置する名前なら何でも) で、コンマを含ま" +#~ "ないものでなければなりません。 ``email`` の値は、正当な電子メールアドレス " +#~ "(のアドレス部分) でなければなりません。これらのキーは共に必須ではありませ" +#~ "ん。" + +#~ msgid "" +#~ "`GitHub and Docs `__ | `PyPI `__" +#~ msgstr "" +#~ "`GitHub と説明文書 `__ | `PyPI `__" + +#~ msgid "" +#~ "Hatch is a unified command-line tool meant to conveniently manage " +#~ "dependencies and environment isolation for Python developers. Python " +#~ "package developers use Hatch to configure, version, specify dependencies " +#~ "for, and publish packages to PyPI. Under the hood, it uses :ref:`twine` " +#~ "to upload packages to PyPI, and :ref:`pip` to download and install " +#~ "packages." +#~ msgstr "" +#~ "Hatch は、 Python での開発者向けに依存関係の管理や環境の分離を便利に行うた" +#~ "めの統合されたコマンドラインツールです。 Python パッケージ開発者は Hatch " +#~ "を使って、パッケージの設定を実施し、バージョン管理を行い、依存関係を指定" +#~ "し、そして PyPI で公開することができます。内部では、 :ref:`twine` を使って" +#~ "パッケージを PyPI へアップロードし、 :ref:`pip` を使ってパッケージのダウン" +#~ "ロードとインストールをしています。" + +#~ msgid "" +#~ "These examples apply to :ref:`twine`, and projects like :ref:`hatch` that " +#~ "use it under the hood. 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 "" +#~ "これらの例は :ref:`twine` や内部でそれを使う :ref:`hatch` のようなプロジェ" +#~ "クトに該当します。他のプロジェクト (例えば :ref:`flit`) で" +#~ "も :file:`.pypirc` を使いますが、既定値が異なります。より詳しくは、また" +#~ "は、使い方についてはそれぞれのプロジェクトの説明文書を見てください。" + +#~ msgid "" +#~ "`hatch `_ for opinionated coverage of even " +#~ "more steps in the project management workflow, such as incrementing " +#~ "versions, tagging releases, and creating new skeleton projects from " +#~ "project templates." +#~ msgstr "" +#~ "`hatch `_ は、バージョン番号の増やし方やタ" +#~ "グ付きリリース、プロジェクト雛形から新しいスケルトンプロジェクトを作成する" +#~ "方法などの点で、プロジェクト管理のワークフローにおけるこだわりの強い機能を" +#~ "持つツールです。" + +#~ msgid "" +#~ "Use :ref:`pipenv` to manage library dependencies when developing Python " +#~ "applications. See :doc:`../tutorials/managing-dependencies` for more " +#~ "details on using ``pipenv``." +#~ msgstr "" +#~ "Python アプリケーションを開発する時にライブラリの依存関係を管理するに" +#~ "は、 :ref:`pipenv` を使いましょう。 ``pipenv`` について詳しくは :doc:`../" +#~ "tutorials/managing-dependencies` をご覧ください。" + +#~ msgid "" +#~ "When ``pipenv`` does not meet your use case, consider other tools like:" +#~ msgstr "" +#~ "``pipenv`` があなたの要望に合致しない場合は、以下のようなツールを検討して" +#~ "ください:" + +#~ msgid "`pip-tools `_" +#~ msgstr "`pip-tools `_" + +#~ msgid "`Poetry `_" +#~ msgstr "`Poetry `_" + +#~ msgid "2014-11-11" +#~ msgstr "2014年11月11日" + +#~ 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. 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`` キー " +#~ "(この仕様内で後で定義します) を経由して一覧化されていて、ツール側が後から" +#~ "提供することになるでしょう。" diff --git a/locales/kab/LC_MESSAGES/messages.po b/locales/kab/LC_MESSAGES/messages.po new file mode 100644 index 000000000..1e82f5a12 --- /dev/null +++ b/locales/kab/LC_MESSAGES/messages.po @@ -0,0 +1,26815 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# ButterflyOfFire , 2025. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: 2025-10-14 20:08+0000\n" +"Last-Translator: ButterflyOfFire \n" +"Language-Team: Kabyle \n" +"Language: kab\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=2; plural=n > 1;\n" +"X-Generator: Weblate 5.14-dev\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "" + +#: ../source/contribute.rst:14 +msgid "Translating the guide" +msgstr "" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "Imniren" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "Asqerdec" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "Tisuqilin" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "" + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "Iswi" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "" + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "" + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "D arummid" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "24/08/2021" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "Tamuɣli s umata" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "pex" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "Arewway" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "2025-?" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "Ayɣeṛ?" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "Amek?" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "" + +#: ../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 +msgid "What is a source distribution?" +msgstr "" + +#: ../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 +msgid "What about eggs?" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "" + +#: ../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 "Ih" + +#: ../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 "Uhu" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python setup.py install``" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "D aqbur" + +#: ../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 "" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python -m pip install --editable .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:104 +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "``alias``" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr "" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +msgid "Complete" +msgstr "" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +msgid "Versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +msgid "Calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +msgid "Other schemes" +msgstr "" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 ../source/flow.rst:143 +msgid "" +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../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 :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +msgid "Installed Project" +msgstr "" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "Amatar n ikemmusen" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "Asenfar" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +msgid "Project Root Directory" +msgstr "" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "" + +#: ../source/glossary.rst:257 +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:260 +msgid "Pyproject Metadata" +msgstr "" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +msgid "Pyproject Metadata Key" +msgstr "" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "pypi.org" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "pyproject.toml" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "" + +#: ../source/glossary.rst:344 +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:348 +msgid "Root License Directory" +msgstr "" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "setup.py" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "setup.cfg" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "Akemmus n unagraw" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "Wheel" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +msgid "Wheel Project" +msgstr "" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "Ajgu" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "Aglam" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "Imedyaten" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "Lqem n ukemmus" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "Amesbedday" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "1956741" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "2344692" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "1730398" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "2047310" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "python" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "3.7" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "18051328726" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "3.6" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "9635067203" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "3.8" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "7781904681" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "2.7" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "6381252241" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "2026630299" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "3.5" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "1894153540" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "url" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +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/analyzing-pypi-package-downloads.rst:246 +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/analyzing-pypi-package-downloads.rst:248 +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/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "Aseqdec:" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +msgid "Creating the package" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +msgid "``pyproject.toml``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +msgid "Installing the package with ``pipx``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +msgid "Conclusion" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "MANIFEST.in" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "``packages``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "``package_data``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +msgid "1. Install twine" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +msgid "Dropping a Python version" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:54 +msgid "Mirror" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:55 +msgid "Proxy" +msgstr "Apṛuksi" + +#: ../source/guides/index-mirrors-and-caches.rst:62 +msgid "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "Fedora" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "CentOS/RHEL" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../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 "" + +#: ../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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +msgid "Install packages in a virtual environment using pip and venv" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +msgid "Install packages using pip" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +msgid "Install extras" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +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/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python -m build``" +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:126 +msgid "``python -m build --no-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:127 +msgid "``python -m pip install --no-build-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../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 "" +"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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +msgid "Installation" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:233 +msgid "``appveyor-sample/build.cmd``" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:5 +msgid "Tool recommendations" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +msgid "Installing packages" +msgstr "Asebded n ikemmusen" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +msgid "Building distributions" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:313 +msgid "setuptools" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:317 +msgid "uv-build" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "Amnir n useqdec n ikemmusen n Python" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +msgid "`Kivy `_" +msgstr "" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "Subdirectory name" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +msgid "``licenses``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*object*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Schema version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "examples" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "version\\_info" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*number*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**implementation**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**flags**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**headers**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +msgid "Package Building" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "Tawsit" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +msgid ":ref:`Version `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +msgid "``toml``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +msgid "``dependency_groups``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +msgid "Installers" +msgstr "" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +msgid "Reference implementation in Python" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +msgid "Names and normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +msgid "Name normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +msgid "Project Status Markers" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +msgid "Installer semantics: none." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +msgid "Installer semantics:" +msgstr "Amesbedday n semantics:" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +#, fuzzy +#| msgid "Deprecated" +msgid "``deprecated``" +msgstr "D aqbur" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +msgid "``pylock.toml`` Specification" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +msgid "``lock-version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +msgid "**Required?**: yes" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +msgid "``environments``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +msgid "``dependency-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +msgid "``[[packages]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +msgid "``packages.version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +msgid "The version of the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +msgid "``[[packages.dependencies]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "Wali :ref:`pylock-packages-vcs-subdirectory`." + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "Wali :ref:`pylock-packages-vcs-url`." + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "Wali :ref:`pylock-packages-vcs-path`." + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +msgid "The time the file was uploaded." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +msgid "``packages.index``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "Wali :ref:`pylock-packages-archive-upload-time`." + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "Wali :ref:`pylock-packages-archive-url`." + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "Wali :ref:`pylock-packages-archive-path`." + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "Wali :ref:`pylock-packages-archive-size`." + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "Wali :ref:`pylock-packages-archive-hashes`." + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "Wali :ref:`pylock-packages-tool`." + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +msgid "``import-names``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +msgid "Legacy specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +#, fuzzy +#| msgid "Examples" +msgid "Examples:" +msgstr "Imedyaten" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +#, fuzzy +#| msgid "Examples" +msgid "Example:" +msgstr "Imedyaten" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +msgid "PyPA schemas" +msgstr "" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +msgid "Python Description Formats" +msgstr "" + +#: ../source/specifications/section-reproducible-environments.rst:3 +msgid "Reproducible Environments" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +msgid "Normalized Names" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +#, fuzzy +#| msgid "Translations" +msgid "HTML Serialization" +msgstr "Tisuqilin" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +msgid "Project List" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +msgid "Project Detail" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +msgid "JSON Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +msgid "Content-Types" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +msgid "Version + Format Selection" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +msgid "Definitions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +msgid "Version scheme" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +msgid "Pre-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +msgid "Version epochs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +msgid "Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +msgid "Integer Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +msgid "Version exclusion" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +msgid "Well-known Project URLs in Metadata" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +msgid "Label normalization" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +msgid "Normalized" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"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/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "Asebded n ikemmusen" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "" + +#: ../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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "" + +#: ../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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" diff --git a/locales/ko/LC_MESSAGES/messages.po b/locales/ko/LC_MESSAGES/messages.po new file mode 100644 index 000000000..4f9175b72 --- /dev/null +++ b/locales/ko/LC_MESSAGES/messages.po @@ -0,0 +1,27066 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# Tanat , 2022, 2023. +# Dongseop , 2023. +# 고종환 , 2023. +# kkumtree , 2023. +# Bae KwonHan , 2024. +# emscb , 2024. +# 황인아 , 2024. +# Changseop Yeom , 2025. +# 스이미 , 2026. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: 2026-02-05 03:01+0000\n" +"Last-Translator: 스이미 \n" +"Language-Team: Korean \n" +"Language: ko\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=1; plural=0;\n" +"X-Generator: Weblate 5.16-dev\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "이 가이드에 기여하기" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "" +"|PyPUG|는 기여자들을 환영합니다! 다음과 같은 다양한 방법으로 지원할 수 있습니" +"다:" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "가이드를 읽고 피드백을 제공하기" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "새로운 기여를 검토하기" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "기존 콘텐츠를 수정하기" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "새로운 콘텐츠를 작성하기" + +#: ../source/contribute.rst:14 +msgid "Translating the guide" +msgstr "가이드를 번역하기" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" +"|PyPUG|의 작업은 대부분 `프로젝트의 GitHub 저장소`__에서 진행됩니다. 시작하려" +"면 `open issues`__ 및 `pull requests`__ 목록을 확인하세요. 가이드를 작성하거" +"나 편집할 계획이라면 :ref:`스타일 가이드 `를 읽어주" +"시기 바랍니다." + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "|PyPUG|에 기여함으로써 귀하는 PSF의 `행동 강령`을 준수해야 합니다." + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "문서 유형" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" +"이 프로젝트는 특정 목적을 가진 4가지 문서 유형으로 구성되어 있습니다. 본 프로" +"젝트는 훌륭한 문서작성을 위해서`Diátaxis process`를 따르는 것을 열망합니다. " +"프로젝트에 대해 새로운 추가를 제안할 때 적절한 문서 유형을 선택하십시오." + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "튜토리얼" + +#: ../source/contribute.rst:44 +#, fuzzy +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" +"자습서는 목표를 달성하여 독자에게 새로운 개념을 가르치는 데 중점을 둡니다. 그" +"들은 독단적인 단계별 가이드입니다. 여기에는 관련 없는 경고나 정보가 포함되지 " +"않습니다. `예제 튜토리얼 스타일 문서`_." + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "가이드" + +#: ../source/contribute.rst:53 +#, fuzzy +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" +"가이드는 특정 작업을 수행하는 데 중점을 두고 있으며 어느 정도의 사전 요구 사" +"항 지식을 가정할 수 있습니다. 이들은 튜토리얼과 비슷하지만 초점이 좁고 명확하" +"며 필요에 따라 많은 주의사항과 추가 정보를 제공할 수 있습니다. 또한 작업을 수" +"행하기 위한 여러 가지 접근 방식에 대해서도 논의할 수 있습니다. :doc:` 가이드 " +"스타일의 문서 `." + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "토론" + +#: ../source/contribute.rst:62 +#, fuzzy +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" +"토론은 이해와 정보에 초점이 맞춰져 있습니다. 이들은 특정 목표를 염두에 두지 " +"않고 특정 주제를 탐구합니다. :doc:` 토론 스타일 문서`." + +#: ../source/contribute.rst:67 +#, fuzzy +msgid "Specifications" +msgstr "명세서" + +#: ../source/contribute.rst:69 +#, fuzzy +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" +"명세서은 패키징 도구 간의 상호 운용성을 위해 합의된 인터페이스를 포괄적으로 " +"문서화하는 데 중점을 둔 참조 문서입니다. :doc:`예제 규격 유형 문서 " +"`." + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "번역" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" +"우리는 이 프로젝트의 번역을 관리하기 위해 `Weblate`_를 사용합니다. 번역에 참" +"여하려면 Weblate의 `packaging.python.org`_ 프로젝트를 방문하세요." + +#: ../source/contribute.rst:80 +#, fuzzy +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "번역 작업 중 문제가 발생하면 `Github`_에서 문제를 여십시오." + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "이 프로젝트의 모든 번역은 `reStructuredText syntax`_을 따라야 합니다." + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "언어 추가" + +#: ../source/contribute.rst:95 +#, fuzzy +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" +"사용자의 언어가 `packaging.python.org`_에 나열되지 않은 경우, 다음 버튼을 클" +"릭합니다:guilabel:`새로운 번역 시작하기`언어 목록의 맨 아래에 번역할 언어를 " +"추가합니다." + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "reStructuredText 문법을 따르기" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" +"reStructuredText(RST) 문법에 익숙하지 않다면, Weblate에서 번역하기 전에 this " +"guide_를 읽어주세요." + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "**참고 문헌의 텍스트를 직접 번역하지 마세요**" + +#: ../source/contribute.rst:106 +#, fuzzy +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "참고로 텍스트를 번역할 때 직접 번역하지 마십시오." + +#: ../source/contribute.rst:0 +#, fuzzy +msgid "Wrong: Translate the following text directly:" +msgstr "잘못되었다: 다음 텍스트를 직접 번역:" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "오른쪽: 다음 텍스트를 자신의 언어로 번역하고 원본 참조를 추가합니다.:" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "로컬에서 가이드 빌드" + +#: ../source/contribute.rst:125 +#, fuzzy +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" +"기여할 필요는 없지만 변경 사항을 테스트하기 위해 이 가이드를 로컬에서 작성하" +"는 것이 유용할 수 있습니다. 이 가이드를 로컬에서 작성하려면 다음이 필요합니" +"다." + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" +":doc:`Nox `. ``pip``를 사용하여 nox를 설치하거나 업그레이드할 수 " +"있습니다." + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" +"Python 3.11. 우리의 빌드 스크립트는 보통 Python 3.11에서만 테스트됩니다. 운" +"영 체제에 Python 3.11을 설치하려면 :doc:'Hitchhiker's Guide to Python 설치 안" +"내 '를 참고하세요." + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "가이드를 빌드하려면, 프로젝트 루트 폴더에서 다음 셸 명령을 실행하세요:" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" +"프로세스가 완료된 후 HTML 결과물은 ``./build/html`` 디렉터리에서 찾을 수 있습" +"니다. ``index.html`` 파일을 열어 웹 브라우저에서 가이드를 확인할 수 있지만, " +"가이드를 HTTP 서버를 통해 제공하는 것이 권장됩니다." + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" +"다음 명령어를 사용하여 가이드를 빌드하고 HTTP 서버를 통해 제공할 수 있습니다:" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "가이드는 http://localhost:8000을 통해 탐색할 수 있습니다." + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "가이드가 배포되는 위치" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" +"이 가이드는 ReadTheDocs를 통해 배포되며 구성은 https://readthedocs.org/" +"projects/python-packaging-user-guide/에 있습니다. 커스텀 도메인에서 서비스되" +"며 Fast.ly가 앞단에서 처리합니다." + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "스타일 안내서" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" +"이 스타일 가이드는 |PyPUG|를 작성하는 방법에 대한 권장 사항을 담고 있습니다. " +"글을 쓰기 전에 반드시 이 가이드를 검토해 주세요. 스타일 가이드를 따르면, 일관" +"된 내용 구성에 기여할 수 있어, 여러분의 기여가 프로젝트에 더 쉽게 수용될 수 " +"있습니다." + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "목적" + +#: ../source/contribute.rst:181 +#, fuzzy +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" +"|PyPUG|의 목적은 최신 도구를 사용하여 Python 프로젝트를 패키징, 배포 및 설치" +"하는 방법에 대한 권위 있는 자료를 제공하는 것입니다." + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "범위" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" +"이 가이드는 정확하고 집중된 추천을 통해 질문에 답하고 문제를 해결하기 위한 것" +"입니다." + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" +"이 가이드는 모든 내용을 담고 있는 종합서가 아니며, 개별 프로젝트의 공식 문서" +"를 대체하기 위해서 작성 된 것도 아닙니다. 예를 들어, pip에는 수십 개의 명령어" +"와 옵션, 설정이 존재합니다. pip 공식 문서에서는 그 모든 요소들을 상세히 설명" +"하고 있지만, 이 가이드는 본문에 서술된 특정 작업들을 완료하는데 필요한 pip의 " +"핵심적인 부분들만을 다룹니다." + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "청중" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "이 가이드는 패키지를 사용하는 Python 사용자라면 누구든 해당됩니다." + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" +"Python 커뮤니티는 규모가 크고 누구라도 환영하는 점을 잊지 마세요. 독자의 나" +"이, 성별, 학력, 문화 등이 다를 수 있지만, 그들도 여러분만큼이나 패키징에 대" +"해 배울 자격이 있습니다." + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" +"특히, Python 을 사용하는 모든 사람들이 자신을 프로그래머라고 생각하지는 않는" +"다는 점을 기억해 주세요. 이 가이드의 이용 대상은 전문적인 소프트웨어 개발자뿐" +"만 아니라 천문학자 또는 화가, 또는 학생들까지 포함합니다." + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "목소리와 톤" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" +"이 가이드를 작성할 때는 모든 내용을 알고 있더라도, 최대한 친근하고 겸손한 말" +"투를 유지하도록 노력해 주세요." + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" +"여러분이 아주 똑똑하고 실력 있는 사람과 함께 Python 프로젝트를 하고 있다고 상" +"상해 보세요. 서로 손발도 잘 맞고 사이도 좋습니다. 그 사람이 여러분에게 질문" +"을 던졌고 , 여러분은 그 답을 이미 알고 있습니다. 그때 여러분이 그 사람에게 대" +"답해 주는 *그 방식*, 그게 바로 이 가이드를 작성하는 말투여야 합니다." + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" +"간단하게 확인해 볼까요? 여러분이 쓴 글을 소리 내어 읽어보며 말투와 느낌을 살" +"펴보세요. 평소에 여러분이 하는 말처럼 들리나요, 아니면 마치 연극 대사나 연설" +"문처럼 들리나요? 격식을 차린 딱딱한 문법에 너무 얽매이지 말고, 평소 여러분이 " +"쓰는 자연스러운 표현들을 마음껏 사용해 보세요. 문장 끝을 딱딱한 말투 대신 조" +"금 더 친근한 말투로 끝내고 싶다면, 그렇게 하셔도 좋습니다." + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" +"가이드를 쓸 때는 주제의 무게나 난이도에 맞춰 말투를 조절해 주세요. 입문자를 " +"위한 튜토리얼이라면 가벼운 농담을 던져도 괜찮지만, 보안과 관련된 민감한 내용" +"을 다룰 때라면, 농담을 아예 피하는 것이 좋습니다." + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "약속과 원칙" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "**독자에게 직접 말을 걸어보세요**" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" +"권고 사항이나 작업 순서를 설명할 때는 독자에게 직접 말을 건내듯 *여러분* 이라" +"고 지칭하거나, 요청형 문장을 사용해 보세요." + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "잘못된: 설치하려면, 직접 실행하세요…" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "올바른 방법: 당신을 그것을 설치할 수 있습니다, ...을 실행하면…" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "올바른 방법: 설치하려면, 다음을 실행하세요…" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "**상태 추정**" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" +"독자가 내용을 미리 알고 있다고 가정하지 마세요. 독자가 가이드의 어떤 페이지" +"를 가장 먼저 보게 될지 알 수 없기 때문입니다. 가정이 꼭 필요할 때는 그 내용" +"을 미리 언급해 주세요." + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "**관련 내용을 충분히 참조하세요**" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" +"특정 도구를 처음 언급할 때는 관련 가이드나 외부 문서로 링크를 걸어주세요. 독" +"자가 직접 검색하는 수고를 덜어줄 수 있습니다." + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "**고유 명칭의 표기법을 존중해 주세요**" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" +"도구, 사이트, 인물 및 기타 고유 명칭을 언급할 때는 해당 대상이 선호하는 대소" +"문자 표기 방식을 따라주세요." + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "잘못된: Pip를 사용하세요…" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "올바른: pip를 사용하세요…" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "잘못된: ...github에서 호스팅됩니다." + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "올바른: ...GitHub애서 호스팅됩니다." + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "**특정 성별에 치우치지 않는 표현을 사용해 주세요**" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" +"때때로, 여러분은 독자를 *you(여러분)*, *your(여러분의)*, 그리고 *yours(여러분" +"의 것)* 로 지칭하게 됩니다. 그렇지 않은 경우에는, 성중립적 대명사인 *they(그" +"들)*, *their(그들의)*, 그리고 *theirs(그들의 것)* 를 사용하거나 대명사를 완전" +"히 사용하지 마십시오." + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "잘못된: 메인테이너가 파일을 업로드합니다. 그 후 그는…" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "올바른: 메인테이너가 파일을 업로드합니다. 그 후 그들은…" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "올바른: 메인테이너가 파일을 업로드합니다. 그 후 메인테이너는…" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "**헤드라인**" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" +"독자가 검색하는 단어를 사용하여 제목을 작성하십시오. 좋은 방법은 당신의 제목" +"이 예상되는 질문을 완성하게 하는 것입니다. 예를 들어, 독자는 *어떻게 " +"MyLibrary를 설치하나요?* 를 알고 싶어 할 수 있으므로, 좋은 제목은 *MyLibrary " +"설치* 가 될 수 있습니다." + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" +"섹션 제목에는 문장처럼 자연스러운 형식을 사용하십시오. 다시 말해, 일반적인 문" +"장을 쓰는 것처럼 제목을 작성하십시오." + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "잘못된: Python에 대해 알아야 할 것" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "올바른: Python에 대해 여러분이 알아야 할 것들" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "**숫자**" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" +"본문에서는 1부터 9까지의 숫자는 단어(하나, 둘 등)로 쓰고, 다른 숫자나 표에 있" +"는 숫자에는 숫자(15, 700 등)를 사용하십시오." + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "Python 애플리케이션 배포하기" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "페이지 상태" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "미완성" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "최종 검토일" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "2021-8-24 (한글 번역: 2026-02-04)" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "개요" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "다양한 하드웨어 플랫폼 지원" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "OS 패키징 및 인스톨러" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" +"`Pynsist `__ 는 NSIS를 기반으로 Python 프로" +"그램과 Python 인터프리터를 하나의 설치 프로그램으로 묶어주는 도구입니다. 대부" +"분, 사용자는 파이썬 인터프리터 버전만 선택하고 프로그램 의존성을 선언하기만 " +"하면 패키징을 할 수 있습니다. 이 도구는 지정된 Windows용 파이썬 인터프리터를 " +"다운로드하고 모든 의존성과 함께 하나의 Windows 실행 파일 형태의 설치 프로그램" +"으로 패키징합니다." + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" +"설치된 프로그램은 설치 프로그램이 시작 메뉴에 추가한 바로가기를 통해 실행할 " +"수 있으며, 이 프로그램은 컴퓨터에 설치된 다른 Python 인터프리터와 무관하게, " +"디텍터리 내에 설치된 자체 Python 인터프리터를 사용합니다." + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" +"Pynsist의 큰 장점은 Linux에서도 Windows 패키지를 빌드할 수 있다는 것입니" +"다. :any:`documentation ` 에는 다양한 종류의 프로그램(콘솔, " +"GUI)에 대한 여러 예제가 제공됩니다. 이 도구는 MIT 라이선스로 배포됩니다." + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "애플리케이션 번들" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" +"`py2exe `__ 는 Python 스크립트에서 단독 실" +"행 가능한 Windows 프로그램(32비트 및 64비트)을 빌드할 수 있게 해주는 " +"distutils 확장 모입니다. 공식 지원 범위에 포함된 Python 버전이 지원됩니다 " +"(refers to `Status of Python branches`__). py2exe는 콘솔 실행 파일과 윈도우" +"(GUI) 실행 파일을 빌드할 수 있습니다. Windows service 및 DLL/EXE COM 서버 빌" +"드 기능도 가능할 수 있지만, 활발하게 지원되지는 않습니다. 이 distutils 확장 " +"모듈은 MIT 라이선스와 Mozilla Public License 2.0에 따라 배포됩니다." + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" +"`py2app `__ 는 Python setuptools 명령어로, " +"Python 스크립트로부터 단독 실행 가능한 macOS 애플리케이션 번들과 플러그인을 " +"만들 수 있게 해줍니다. py2app는 반드시 macOS에서 사용해야 하며, 다른 플랫폼에" +"서는 Mac용 애플리케이션을 생성할 수 없습니다. py2app는 MIT 라이선스로 배포됩" +"니다." + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "Unix (Linux 및 macOS 포함)" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "pex" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" +"`pex `__ 는 가상 환경(virtualenv)한 유사한 방" +"식으로 실행 가능한 Python 환경인 .pex(Python EXecutable) 파일을 생성하는 라이" +"브러리입니다. pex는 :pep:441에 기술된 아이디어를 확장한 것으로, Python 애플리" +"케이션 배포를 cp 명령만큼이나 간하게 만들어 줍니다. pex 파일에는 여러 플랫폼" +"별 Python 배포판을 포함할 수도 있으므로, 하나의 pex 파일로 Linux와 macOS에서 " +"모두 사용 가능합니다. pex는 Apache License 2.0에 따라 배포됩니다." + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "구성 관리" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "배포 패키지 vs import 패키지" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" +"일반적으로 \"패키지\" 라는 단어는 여러 가지 서로 다른 개념을 지칭하는 데 사용" +"됩니다. 이 페이지에서는 Python 패키징에서 쓰이는, 서로 다르지만 밀접한 관련" +"이 있는 두 가지 의미인 '배포 패키지(distribution package)'와 'import 패키지" +"(import package)'의 차이점을 명확히 설명합니다." + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "배포 패키지란 무엇인가요?" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" +"배포 패키지는 여러분이 설치할 수 있는 소프트웨어의 한 종류입니다. 대부분의 경" +"우 '프로젝트'와 같은 의미로 쓰입니다. 여러분이 ``pip install pkg``를 입력하거" +"나, ``pyproject.toml``파일에 ``dependencies = [\"pkg\"]``라고 작성할 때, 여기" +"서 ``pkg``가 바로 배포 패키지의 이름입니다. Python 라이브러리와 도구를 설치" +"할 때 가장 널리 알려진 중앙 저장소인 PyPI_ 에서 검색하거나 둘러볼 때 보게 되" +"는 것들도 모두 배포 패키지 목록입니다. 또한, \"배포 패키지\"라는 용어는 프로" +"젝트의 특정 버전을 포함하고 있는 구체적인 파일을 가리키는 데 사용되기도 합니" +"다." + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" +"Linux 환경에서 \"배포 패키지(distribution package)\"는 일반적으로 \"디스트로 " +"패키지(distro package)\" 또는 \"패키지(package)\"로 줄여서 사용되며, `Linux " +"배포판 `_ 의 시스템 패키지 관리자가 제공하는 것을 의미합니다. 이는 " +"앞서 언급한 \"배포 패키지(distribution package)\"와는 다른 의미입니다." + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "import 패키지란 무엇인가요?" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" +"import 패키지는 하나의 Python 모듈입니다. 따라서 여러분의 Python 코드에 " +"``import pkg``나 ``from pkg import func``라고 작성할 때, 여기서 ``pkg``는 " +"import 패키지의 이름입니다. 더 정확히 말하자면, import 패키지는 하위 모듈" +"(submodule)을 포함할 수 있는 특수한 Python 모듈입니다. 예를 들어, ``numpy`` " +"패키지는 ``numpy.linalg``나 ``numpy.fft``와 같은 모듈들을 포함하고 있습니다. " +"보통 import 패키지는 파일 시스템상의 디렉터리 형태이며, 그 안에 ``.py`` 파일 " +"형태의 모듈과 하위 디렉터리 형태의 하위 패키지(subpackage)를 포함합니다." + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" +"여러분이 import 패키지를 제공하는 배포 패키지를 설치하면, 즉시 그 패키지를 사" +"용할 수 있습니다." + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "배포 패키지와 import 패키지 사이에는 어떤 연결 관계가 있나요?" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" + +#: ../source/discussions/package-formats.rst:5 +#, fuzzy +msgid "Package Formats" +msgstr "패키지 인덱스" + +#: ../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 +msgid "What is a source distribution?" +msgstr "" + +#: ../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 +msgid "What about eggs?" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python setup.py install``" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 +#, fuzzy +#| msgid "Documentation types" +msgid "Recommendation" +msgstr "문서 유형" + +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python -m pip install .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python -m pip install --editable .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:104 +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr "" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +#, fuzzy +#| msgid "Incomplete" +msgid "Complete" +msgstr "미완료" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +#, fuzzy +msgid "Versioning" +msgstr "번역" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +#, fuzzy +msgid "Calendar versioning" +msgstr "번역" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +#, fuzzy +msgid "Other schemes" +msgstr "번역" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 ../source/flow.rst:143 +msgid "" +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../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 :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "배포 패키지" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "확장 모듈" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +#, fuzzy +msgid "Import Package" +msgstr "패키지 가져오기" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +#, fuzzy +#| msgid "Translations" +msgid "Installed Project" +msgstr "번역" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "모듈" + +#: ../source/glossary.rst:186 +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:189 +#, fuzzy +msgid "Package Index" +msgstr "패키지 인덱스" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +#, fuzzy +msgid "Per Project Index" +msgstr "프로젝트별 인덱스" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "프로젝트" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +#, fuzzy +#| msgid "Project name" +msgid "Project Root Directory" +msgstr "프로젝트 이름" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "순수 모듈" + +#: ../source/glossary.rst:257 +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:260 +#, fuzzy +#| msgid "Project name" +msgid "Pyproject Metadata" +msgstr "프로젝트 이름" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +#, fuzzy +#| msgid "Project name" +msgid "Pyproject Metadata Key" +msgstr "프로젝트 이름" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +#, fuzzy +msgid "Requirement Specifier" +msgstr "요구 사항 지정자" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "" + +#: ../source/glossary.rst:344 +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:348 +#, fuzzy +#| msgid "Project name" +msgid "Root License Directory" +msgstr "프로젝트 이름" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "소스 아카이브" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "버전 명시자" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +#, fuzzy +#| msgid "Project" +msgid "Wheel Project" +msgstr "프로젝트" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "프로젝트 이름" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "파이썬 버전" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "" +"https://files.pythonhosted.org/packages/eb/" +"45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" +"sampleproject-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "" +"https://files.pythonhosted.org/packages/56/0a/" +"178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" +"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +msgid "" +"https://files.pythonhosted.org/packages/" +"63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" +"sampleproject_nomura-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +#, fuzzy +#| msgid "Translations" +msgid "Creating the package" +msgstr "번역" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +msgid "``pyproject.toml``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +#, fuzzy +#| msgid "Translations" +msgid "Installing the package with ``pipx``" +msgstr "번역" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +#, fuzzy +msgid "Conclusion" +msgstr "번역" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "계정 생성하기" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +#, fuzzy +#| msgid "Translations" +msgid "1. Install twine" +msgstr "번역" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +#, fuzzy +#| msgid "Python version" +msgid "Dropping a Python version" +msgstr "파이썬 버전" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 +#, fuzzy +msgid "Package upload" +msgstr "패키지 인덱스" + +#: ../source/guides/hosting-your-own-index.rst:64 +msgid "PyPI fall-through [2]_" +msgstr "" + +#: ../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 "" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:105 +#, fuzzy +#| msgid "Maintainer" +msgid "unmaintained" +msgstr "관리자" + +#: ../source/guides/installing-scientific-packages.rst:5 +msgid "Installing scientific packages" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:8 +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." +msgstr "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:108 +msgid "openSUSE" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:118 +msgid "Debian/Ubuntu and derivatives" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +msgid "Install packages in a virtual environment using pip and venv" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +msgid "Install packages using pip" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +#, fuzzy +#| msgid "Translations" +msgid "Install extras" +msgstr "번역" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +#, fuzzy +msgid "Using a requirements file" +msgstr "요구 사항 지정자" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +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/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python -m build``" +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:126 +msgid "``python -m build --no-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:127 +msgid "``python -m pip install --no-build-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../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 "" +"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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "``.github/workflows/publish-to-pypi.yml`` 파일을 만들어 봅시다." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +#, fuzzy +#| msgid "Translations" +msgid "Installation" +msgstr "번역" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:233 +msgid "``appveyor-sample/build.cmd``" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:5 +msgid "Tool recommendations" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +#, fuzzy +#| msgid "Translations" +msgid "Installing packages" +msgstr "번역" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +#, fuzzy +#| msgid "Reviewing new contributions" +msgid "Building distributions" +msgstr "새로운 기여를 검토" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:313 +msgid "setuptools" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:317 +msgid "uv-build" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "패키지화" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +msgid "`Kivy `_" +msgstr "" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "보안" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "세부 정보" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +#, fuzzy +#| msgid "Project name" +msgid "Subdirectory name" +msgstr "프로젝트 이름" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +msgid "``licenses``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Project" +msgid "*object*" +msgstr "프로젝트" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Python version" +msgid "Schema version." +msgstr "파이썬 버전" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "examples" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +msgid "**version**" +msgstr "번역" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +msgid "version\\_info" +msgstr "번역" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*number*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Documentation types" +msgid "**implementation**" +msgstr "문서 유형" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**flags**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +msgid "extensions" +msgstr "번역" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**headers**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "관리자" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +#, fuzzy +msgid "Package Building" +msgstr "패키지 인덱스" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +#, fuzzy +#| msgid "Documentation types" +msgid "Reference Implementation" +msgstr "문서 유형" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +#, fuzzy +msgid "Versions" +msgstr "번역" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +msgid ":ref:`Version `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +msgid "``toml``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +msgid "``dependency_groups``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +#, fuzzy +msgid "package" +msgstr "패키지 가져오기" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +#, fuzzy +#| msgid "Documentation types" +msgid "Implementation Notes" +msgstr "문서 유형" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +#, fuzzy +#| msgid "Translations" +msgid "Installers" +msgstr "번역" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +#, fuzzy +#| msgid "Documentation types" +msgid "Reference implementation in Python" +msgstr "문서 유형" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +#, fuzzy +msgid "Names and normalization" +msgstr "번역" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +#, fuzzy +msgid "Name normalization" +msgstr "번역" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +#, fuzzy +#| msgid "Project name" +msgid "Project Status Markers" +msgstr "프로젝트 이름" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +#, fuzzy +#| msgid "Translations" +msgid "Installer semantics: none." +msgstr "번역" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +#, fuzzy +#| msgid "Translations" +msgid "Installer semantics:" +msgstr "번역" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +msgid "``deprecated``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +#, fuzzy +msgid "``pylock.toml`` Specification" +msgstr "명세서" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +msgid "``lock-version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +msgid "**Required?**: yes" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +msgid "``environments``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +msgid "``dependency-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +#, fuzzy +msgid "``[[packages]]``" +msgstr "패키지 가져오기" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +msgid "``packages.version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +#, fuzzy +#| msgid "Translations" +msgid "The version of the package." +msgstr "번역" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +msgid "``[[packages.dependencies]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +msgid "The time the file was uploaded." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +#, fuzzy +msgid "``packages.index``" +msgstr "패키지 인덱스" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +msgid "``import-names``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +#, fuzzy +msgid "Legacy specification" +msgstr "명세서" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +msgid "Examples:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +msgid "Example:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +msgid "PyPA schemas" +msgstr "" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +#, fuzzy +#| msgid "Python version" +msgid "Python Description Formats" +msgstr "파이썬 버전" + +#: ../source/specifications/section-reproducible-environments.rst:3 +msgid "Reproducible Environments" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +#, fuzzy +msgid "Normalized Names" +msgstr "번역" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +#, fuzzy +msgid "HTML Serialization" +msgstr "번역" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +#, fuzzy +#| msgid "Project" +msgid "Project List" +msgstr "프로젝트" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +#, fuzzy +#| msgid "Project name" +msgid "Project Detail" +msgstr "프로젝트 이름" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +#, fuzzy +msgid "JSON Serialization" +msgstr "번역" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +msgid "Content-Types" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +#, fuzzy +msgid "Version + Format Selection" +msgstr "번역" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +#, fuzzy +msgid "Definitions" +msgstr "명세서" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +#, fuzzy +msgid "Version scheme" +msgstr "번역" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +msgid "Pre-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +#, fuzzy +msgid "Version epochs" +msgstr "번역" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +#, fuzzy +msgid "Normalization" +msgstr "번역" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +#, fuzzy +msgid "Integer Normalization" +msgstr "번역" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +#, fuzzy +msgid "Version exclusion" +msgstr "번역" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +#, fuzzy +#| msgid "Project name" +msgid "Well-known Project URLs in Metadata" +msgstr "프로젝트 이름" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +#, fuzzy +msgid "Label normalization" +msgstr "번역" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +#, fuzzy +msgid "Normalized" +msgstr "번역" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"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/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "" + +#: ../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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "" + +#: ../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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" diff --git a/locales/lzh/LC_MESSAGES/messages.po b/locales/lzh/LC_MESSAGES/messages.po new file mode 100644 index 000000000..b2619577f --- /dev/null +++ b/locales/lzh/LC_MESSAGES/messages.po @@ -0,0 +1,26797 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# 王玎珰 <1330274738@qq.com>, 2023. +# maker , 2024. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: 2024-01-31 06:01+0000\n" +"Last-Translator: maker \n" +"Language-Team: Chinese (Literary) \n" +"Language: lzh\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=2; plural=n != 1;\n" +"X-Generator: Weblate 5.4-dev\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "助此引" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "" + +#: ../source/contribute.rst:14 +msgid "Translating the guide" +msgstr "" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "导" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "" + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "" + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "" + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "未完成" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "" + +#: ../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 +msgid "What is a source distribution?" +msgstr "" + +#: ../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 +msgid "What about eggs?" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python setup.py install``" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python -m pip install --editable .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:104 +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr "" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +#, fuzzy +#| msgid "Incomplete" +msgid "Complete" +msgstr "未完成" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +msgid "Versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +msgid "Calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +msgid "Other schemes" +msgstr "" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 ../source/flow.rst:143 +msgid "" +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../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 :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +msgid "Installed Project" +msgstr "" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +msgid "Project Root Directory" +msgstr "" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "" + +#: ../source/glossary.rst:257 +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:260 +msgid "Pyproject Metadata" +msgstr "" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +msgid "Pyproject Metadata Key" +msgstr "" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "" + +#: ../source/glossary.rst:344 +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:348 +msgid "Root License Directory" +msgstr "" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "源码" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "版本指定器" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +msgid "Wheel Project" +msgstr "" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "" +"https://files.pythonhosted.org/packages/eb/" +"45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" +"sampleproject-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "" +"https://files.pythonhosted.org/packages/56/0a/" +"178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" +"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +msgid "" +"https://files.pythonhosted.org/packages/" +"63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" +"sampleproject_nomura-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +msgid "Creating the package" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +msgid "``pyproject.toml``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +msgid "Installing the package with ``pipx``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +msgid "Conclusion" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +msgid "1. Install twine" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +msgid "Dropping a Python version" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:108 +msgid "openSUSE" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:118 +msgid "Debian/Ubuntu and derivatives" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +msgid "Install packages in a virtual environment using pip and venv" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +msgid "Install packages using pip" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +msgid "Install extras" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +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/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python -m build``" +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:126 +msgid "``python -m build --no-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:127 +msgid "``python -m pip install --no-build-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../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 "" +"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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +msgid "Installation" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:233 +msgid "``appveyor-sample/build.cmd``" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:5 +msgid "Tool recommendations" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +msgid "Installing packages" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +msgid "Building distributions" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:313 +msgid "setuptools" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:317 +msgid "uv-build" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +msgid "`Kivy `_" +msgstr "" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "Subdirectory name" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +msgid "``licenses``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*object*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Schema version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "examples" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "version\\_info" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*number*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**implementation**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**flags**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**headers**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +msgid "Package Building" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +#, fuzzy +#| msgid "Version Specifier" +msgid ":ref:`Version `" +msgstr "版本指定器" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +msgid "``toml``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +msgid "``dependency_groups``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +msgid "Installers" +msgstr "" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +msgid "Reference implementation in Python" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +msgid "Names and normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +msgid "Name normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +msgid "Project Status Markers" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +msgid "Installer semantics: none." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +msgid "Installer semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +msgid "``deprecated``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +msgid "``pylock.toml`` Specification" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +msgid "``lock-version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +msgid "**Required?**: yes" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +msgid "``environments``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +msgid "``dependency-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +msgid "``[[packages]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +msgid "``packages.version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +msgid "The version of the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +msgid "``[[packages.dependencies]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +msgid "The time the file was uploaded." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +msgid "``packages.index``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +msgid "``import-names``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +msgid "Legacy specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +msgid "Examples:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +msgid "Example:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +msgid "PyPA schemas" +msgstr "" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +msgid "Python Description Formats" +msgstr "" + +#: ../source/specifications/section-reproducible-environments.rst:3 +msgid "Reproducible Environments" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +msgid "Normalized Names" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +msgid "HTML Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +msgid "Project List" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +msgid "Project Detail" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +msgid "JSON Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +msgid "Content-Types" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +msgid "Version + Format Selection" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +msgid "Definitions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +msgid "Version scheme" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +msgid "Pre-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +msgid "Version epochs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +msgid "Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +msgid "Integer Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +msgid "Version exclusion" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +msgid "Well-known Project URLs in Metadata" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +msgid "Label normalization" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +msgid "Normalized" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"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/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "" + +#: ../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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "" + +#: ../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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" diff --git a/locales/messages.pot b/locales/messages.pot new file mode 100644 index 000000000..7d1311e39 --- /dev/null +++ b/locales/messages.pot @@ -0,0 +1,18594 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-08-05 18:34+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "" + +#: ../source/contribute.rst:7 +msgid "The |PyPUG| welcomes contributors! There are lots of ways to help out, including:" +msgstr "" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "" + +#: ../source/contribute.rst:14 +msgid "Translating the guide" +msgstr "" + +#: ../source/contribute.rst:16 +msgid "Most of the work on the |PyPUG| takes place on the `project's GitHub repository`__. To get started, check out the list of `open issues`__ and `pull requests`__. If you're planning to write or edit the guide, please read the :ref:`style guide `." +msgstr "" + +#: ../source/contribute.rst:25 +msgid "By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of Conduct`__." +msgstr "" + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "" + +#: ../source/contribute.rst:34 +msgid "This project consists of four distinct documentation types with specific purposes. The project aspires to follow the `Diátaxis process`_ for creating quality documentation. When proposing new additions to the project please pick the appropriate documentation type." +msgstr "" + +#: ../source/contribute.rst:42 +#: ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "" + +#: ../source/contribute.rst:44 +msgid "Tutorials are focused on teaching the reader new concepts by accomplishing a goal. They are opinionated step-by-step guides. They do not include extraneous warnings or information. `example tutorial-style document`_." +msgstr "" + +#: ../source/contribute.rst:51 +#: ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "" + +#: ../source/contribute.rst:53 +msgid "Guides are focused on accomplishing a specific task and can assume some level of pre-requisite knowledge. These are similar to tutorials, but have a narrow and clear focus and can provide lots of caveats and additional information as needed. They may also discuss multiple approaches to accomplishing the task. :doc:`example guide-style document `." +msgstr "" + +#: ../source/contribute.rst:60 +#: ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "" + +#: ../source/contribute.rst:62 +msgid "Discussions are focused on understanding and information. These explore a specific topic without a specific goal in mind. :doc:`example discussion-style document `." +msgstr "" + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "" + +#: ../source/contribute.rst:69 +msgid "Specifications are reference documentation focused on comprehensively documenting an agreed-upon interface for interoperability between packaging tools. :doc:`example specification-style document `." +msgstr "" + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "" + +#: ../source/contribute.rst:77 +msgid "We use `Weblate`_ to manage translations of this project. Please visit the `packaging.python.org`_ project on Weblate to contribute." +msgstr "" + +#: ../source/contribute.rst:80 +msgid "If you are experiencing issues while you are working on translations, please open an issue on `GitHub`_." +msgstr "" + +#: ../source/contribute.rst:85 +msgid "Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "" + +#: ../source/contribute.rst:95 +msgid "If your language is not listed on `packaging.python.org`_, click the button :guilabel:`Start new translation` at the bottom of the language list and add the language you want to translate." +msgstr "" + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "" + +#: ../source/contribute.rst:102 +msgid "If you are not familiar with reStructuredText (RST) syntax, please read `this guide`_ before translating on Weblate." +msgstr "" + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "" + +#: ../source/contribute.rst:106 +msgid "When translating the text in reference, please do not translate them directly." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: Translate the following text with your own language and add the original reference:" +msgstr "" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "" + +#: ../source/contribute.rst:125 +msgid "Though not required to contribute, it may be useful to build this guide locally in order to test your changes. In order to build this guide locally, you'll need:" +msgstr "" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" + +#: ../source/contribute.rst:136 +msgid "Python 3.11. Our build scripts are usually tested with Python 3.11 only. See the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating system." +msgstr "" + +#: ../source/contribute.rst:140 +msgid "To build the guide, run the following shell command in the project's root folder:" +msgstr "" + +#: ../source/contribute.rst:146 +msgid "After the process has completed you can find the HTML output in the ``./build/html`` directory. You can open the ``index.html`` file to view the guide in web browser, but it's recommended to serve the guide using an HTTP server." +msgstr "" + +#: ../source/contribute.rst:151 +msgid "You can build the guide and serve it via an HTTP server using the following command:" +msgstr "" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "" + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "" + +#: ../source/contribute.rst:164 +msgid "The guide is deployed via ReadTheDocs and the configuration lives at https://readthedocs.org/projects/python-packaging-user-guide/. It's served from a custom domain and fronted by Fast.ly." +msgstr "" + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "" + +#: ../source/contribute.rst:172 +msgid "This style guide has recommendations for how you should write the |PyPUG|. Before you start writing, please review it. By following the style guide, your contributions will help add to a cohesive whole and make it easier for your contributions to be accepted into the project." +msgstr "" + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "" + +#: ../source/contribute.rst:181 +msgid "The purpose of the |PyPUG| is to be the authoritative resource on how to package, publish, and install Python projects using current tools." +msgstr "" + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "" + +#: ../source/contribute.rst:188 +msgid "The guide is meant to answer questions and solve problems with accurate and focused recommendations." +msgstr "" + +#: ../source/contribute.rst:191 +msgid "The guide isn't meant to be comprehensive and it's not meant to replace individual projects' documentation. For example, pip has dozens of commands, options, and settings. The pip documentation describes each of them in detail, while this guide describes only the parts of pip that are needed to complete the specific tasks described in this guide." +msgstr "" + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "" + +#: ../source/contribute.rst:203 +msgid "Don't forget that the Python community is big and welcoming. Readers may not share your age, gender, education, culture, and more, but they deserve to learn about packaging just as much as you do." +msgstr "" + +#: ../source/contribute.rst:207 +msgid "In particular, keep in mind that not all people who use Python see themselves as programmers. The audience of this guide includes astronomers or painters or students as well as professional software developers." +msgstr "" + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "" + +#: ../source/contribute.rst:215 +msgid "When writing this guide, strive to write with a voice that's approachable and humble, even if you have all the answers." +msgstr "" + +#: ../source/contribute.rst:218 +msgid "Imagine you're working on a Python project with someone you know to be smart and skilled. You like working with them and they like working with you. That person has asked you a question and you know the answer. How do you respond? *That* is how you should write this guide." +msgstr "" + +#: ../source/contribute.rst:223 +msgid "Here's a quick check: try reading aloud to get a sense for your writing's voice and tone. Does it sound like something you would say or does it sound like you're acting out a part or giving a speech? Feel free to use contractions and don't worry about sticking to fussy grammar rules. You are hereby granted permission to end a sentence in a preposition, if that's what you want to end it with." +msgstr "" + +#: ../source/contribute.rst:230 +msgid "When writing the guide, adjust your tone for the seriousness and difficulty of the topic. If you're writing an introductory tutorial, it's OK to make a joke, but if you're covering a sensitive security recommendation, you might want to avoid jokes altogether." +msgstr "" + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "" + +#: ../source/contribute.rst:240 +msgid "When giving recommendations or steps to take, address the reader as *you* or use the imperative mood." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "" + +#: ../source/contribute.rst:248 +msgid "Avoid making unstated assumptions. Reading on the web means that any page of the guide may be the first page of the guide that the reader ever sees. If you're going to make assumptions, then say what assumptions that you're going to make." +msgstr "" + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "" + +#: ../source/contribute.rst:254 +msgid "The first time you mention a tool or practice, link to the part of the guide that covers it, or link to a relevant document elsewhere. Save the reader a search." +msgstr "" + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "" + +#: ../source/contribute.rst:259 +msgid "When naming tools, sites, people, and other proper nouns, use their preferred capitalization." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "" + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "" + +#: ../source/contribute.rst:269 +msgid "Often, you'll address the reader directly with *you*, *your* and *yours*. Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or avoid pronouns entirely." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "" + +#: ../source/contribute.rst:278 +msgid "Write headings that use words the reader is searching for. A good way to do this is to have your heading complete an implied question. For example, a reader might want to know *How do I install MyLibrary?* so a good heading might be *Install MyLibrary*." +msgstr "" + +#: ../source/contribute.rst:283 +msgid "In section headings, use sentence case. In other words, write headings as you would write a typical sentence." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "In body text, write numbers one through nine as words. For other numbers or numbers in tables, use numerals." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "`Pynsist `__ is a tool that bundles Python programs together with the Python-interpreter into a single installer based on NSIS. In most cases, packaging only requires the user to choose a version of the Python-interpreter and declare the dependencies of the program. The tool downloads the specified Python-interpreter for Windows and packages it with all the dependencies in a single Windows-executable installer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "The installed program can be started from a shortcut that the installer adds to the start-menu. It uses a Python interpreter installed within its application directory, independent of any other Python installation on the computer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "A big advantage of Pynsist is that the Windows packages can be built on Linux. There are several examples for different kinds of programs (console, GUI) in the :any:`documentation `. The tool is released under the MIT-licence." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "`py2exe `__ is a distutils extension which allows to build standalone Windows executable programs (32-bit and 64-bit) from Python scripts. Python versions included in the official development cycle are supported (refers to `Status of Python branches`__). py2exe can build console executables and windows (GUI) executables. Building windows services, and DLL/EXE COM servers might work but it is not actively supported. The distutils extension is released under the MIT-licence and Mozilla Public License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "`py2app `__ is a Python setuptools command which will allow you to make standalone macOS application bundles and plugins from Python scripts. Note that py2app MUST be used on macOS to build applications, it cannot create Mac applications on other platforms. py2app is released under the MIT-license." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "`pex `__ is a library for generating .pex (Python EXecutable) files which are executable Python environments in the spirit of virtualenvs. pex is an expansion upon the ideas outlined in :pep:`441` and makes the deployment of Python applications as simple as cp. pex files may even include multiple platform-specific Python distributions, meaning that a single pex file can be portable across Linux and macOS. pex is released under the Apache License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "A number of different concepts are commonly referred to by the word \"package\". This page clarifies the differences between two distinct but related meanings in Python packaging, \"distribution package\" and \"import package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "A distribution package is a piece of software that you can install. Most of the time, this is synonymous with \"project\". When you type ``pip install pkg``, or when you write ``dependencies = [\"pkg\"]`` in your ``pyproject.toml``, ``pkg`` is the name of a distribution package. When you search or browse the PyPI_, the most widely known centralized source for installing Python libraries and tools, what you see is a list of distribution packages. Alternatively, the term \"distribution package\" can be used to refer to a specific file that contains a certain version of a project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "Note that in the Linux world, a \"distribution package\", most commonly abbreviated as \"distro package\" or just \"package\", is something provided by the system package manager of the `Linux distribution `_, which is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "An import package is a Python module. Thus, when you write ``import pkg`` or ``from pkg import func`` in your Python code, ``pkg`` is the name of an import package. More precisely, import packages are special Python modules that can contain submodules. For example, the ``numpy`` package contains modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package is a directory on the file system, containing modules as ``.py`` files and subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "You can use an import package as soon as you have installed a distribution package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "Most of the time, a distribution package provides one single import package (or non-package module), with a matching name. For example, ``pip install numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "However, this is only a convention. PyPI and other package indices *do not enforce any relationship* between the name of a distribution package and the import packages it provides. (A consequence of this is that you cannot blindly install the PyPI package ``foo`` if you see ``import foo``; this may install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "A distribution package could provide an import package with a different name. An example of this is the popular Pillow_ library for image processing. Its distribution package name is ``Pillow``, but it provides the import package ``PIL``. This is for historical reasons: Pillow started as a fork of the PIL library, thus it kept the import name ``PIL`` so that existing PIL users could switch to Pillow with little effort. More generally, a fork of an existing library is a common reason for differing names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "On a given package index (like PyPI), distribution package names must be unique. On the other hand, import packages have no such requirement. Import packages with the same name can be provided by several distribution packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "Conversely, a distribution package can provide several import packages, although this is less common. An example is the attrs_ distribution package, which provides both an ``attrs`` import package with a newer API, and an ``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "Import packages should have valid Python identifiers as their name (the :ref:`exact rules ` are found in the Python documentation) [#non-identifier-mod-name]_. In particular, they use underscores ``_`` as word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "On the other hand, distribution packages can use hyphens ``-`` or underscores ``_``. They can also contain dots ``.``, which is sometimes used for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as ``pip install awesome-package`` (the precise rules are given in the :ref:`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "Although it is technically possible to import packages/modules that do not have a valid Python identifier as their name, using :doc:`importlib `, this is vanishingly rare and strongly discouraged." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "While PyPI and the Python packaging tools such as :ref:`pip` are the primary means of distributing Python packages, they are also often made available as part of other packaging ecosystems. These repackaging efforts are collectively called *downstream* packaging (your own efforts are called *upstream* packaging), and include such projects as Linux distributions, Conda, Homebrew and MacPorts. They generally aim to provide improved support for use cases that cannot be handled via Python packaging tools alone, such as native integration with a specific operating system, or assured compatibility with specific versions of non-Python software." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "This discussion attempts to explain how downstream packaging is usually done, and what additional challenges downstream packagers typically face. It aims to provide some optional guidelines that project maintainers may choose to follow which help make downstream packaging *significantly* easier (without imposing any major maintenance hassles on the upstream project). Note that this is not an all-or-nothing proposal — anything that upstream maintainers can do is useful, even if it's only a small part. Downstream maintainers are also willing to prepare patches to resolve these issues. Having these patches merged can be very helpful, since it removes the need for different downstreams to carry and keep rebasing the same patches, and the risk of applying inconsistent solutions to the same problem." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "Establishing a good relationship between software maintainers and downstream packagers can bring mutual benefits. Downstreams are often willing to share their experience, time and hardware to improve your package. They are sometimes in a better position to see how your package is used in practice, and to provide information about its relationships with other packages that would otherwise require significant effort to obtain. Packagers can often find bugs before your users hit them in production, provide bug reports of good quality, and supply patches whenever they can. For example, they are regularly active in ensuring the packages they redistribute are updated for any compatibility issues that arise when a new Python version is released." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "Please note that downstream builds include not only binary redistribution, but also source builds done on user systems (in source-first distributions such as Gentoo Linux, for example)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "The vast majority of downstream packagers prefer to build packages from source, rather than use the upstream-provided binary packages. In some cases, using sources is actually required for the package to be included in the distribution. This is also true of pure Python packages that provide universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "Being able to easily apply patches, including backporting commits from the project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "Being able to build on a specific platform that is not covered by upstream builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "While it is usually possible to build packages from a Git repository, there are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "Fetching a single file is often more efficient, more reliable and better supported than e.g. using a Git clone. This can help users with poor Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "Downstreams often use hashes to verify the authenticity of source files on subsequent builds, which require that they remain bitwise identical over time. For example, automatically generated Git archives do not guarantee this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "Archive files can be mirrored, reducing both upstream and downstream bandwidth use. The actual builds can afterwards be performed in firewalled or offline environments, that can only access source files provided by the local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "Explicitly publishing archive files can ensure that any dependencies on version control system metadata are resolved when creating the source archive. For example, automatically generated Git archives omit all of the commit tag information, potentially resulting in incorrect version details in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "Ideally, **a source distribution archive published on PyPI should include all the files from the package's Git repository** that are necessary to build the package itself, run its test suite, build and install its documentation, and any other files that may be useful to end users, such as shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "This point applies only to the files belonging to the package itself. The downstream packaging process, much like Python package managers, will provision the necessary Python dependencies, system tools and external libraries that are needed by your package and its build scripts. However, the files listing these dependencies (for example, ``requirements*.txt`` files) should also be included, to help downstreams determine the needed dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "Some projects have concerns related to Python package managers using source distributions from PyPI. They do not wish to increase their size with files that are not used by these tools, or they do not wish to publish source distributions at all, as they enable a problematic or outright nonfunctional fallback to building the particular project from source. In these cases, a good compromise may be to publish a separate source archive for downstream use elsewhere, for example by attaching it to a GitHub release. Alternatively, large files, such as test data, can be split into separate archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "On the other hand, some projects (NumPy_, for instance) decide to include tests in their installed packages. This has the added advantage of permitting users to run tests after installing them, for example to check for regressions after upgrading a dependency. Yet another approach is to split tests or test data into a separate Python package. Such an approach was taken by the cryptography_ project, with the large test vectors being split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "A good idea is to use your source distribution in the release workflow. For example, the :ref:`build` tool does exactly that — it first builds a source distribution, and then uses it to build a wheel. This ensures that the source distribution actually works, and that it won't accidentally install fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "Ideally, also use the source distribution to run tests, build documentation, and so on, or add specific tests to make sure that all necessary files were actually included. Understandably, this requires more effort, so it's fine not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "Downstream builds are frequently done in sandboxed environments that cannot access the Internet. The package sources are unpacked into this environment, and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "Even if this is not the case, and assuming that you took sufficient care to properly authenticate downloads, using the Internet is discouraged for a number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "The Internet connection may be unstable (e.g. due to poor reception) or suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "The remote resources may become temporarily or even permanently unavailable, making the build no longer possible. This is especially problematic when someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "Accessing remote servers poses a privacy issue and a potential security issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "The user may be using a service with a limited data plan, in which uncontrolled Internet access may result in additional charges or other inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "If the package is implementing any custom build *backend* actions that use the Internet, for example by automatically downloading vendored dependencies or fetching Git submodules, its source distribution should either include all of these files or allow provisioning them externally, and the Internet must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "Note that this point does not apply to Python dependencies that are specified in the package metadata, and are fetched during the build and installation process by *frontends* (such as :ref:`build` or :ref:`pip`). Downstreams use frontends that use local provisioning for Python dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "Ideally, custom build scripts should not even attempt to access the Internet at all, unless explicitly requested to. If any resources are missing and need to be fetched, they should ask the user for permission first. If that is not feasible, the next best thing is to provide an opt-out switch to disable all Internet access. This could be done e.g. by checking whether a ``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "Since downstreams frequently also run tests and build documentation, the above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "Please also remember that if you are fetching remote resources, you absolutely must *verify their authenticity* (usually against a hash), to protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "Some Python projects have non-Python dependencies, such as libraries written in C or C++. Trying to use the system versions of these dependencies in upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "The published wheels require a binary-compatible version of the used library to be present on the user's system. If the library is missing or an incompatible version is installed, the Python package may fail with errors that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "Building from a source distribution requires a source-compatible version of the dependency to be present, along with its development headers and other auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "Even for an experienced user, installing a compatible dependency version may be very hard. For example, the used Linux distribution may not provide the required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "The linkage between the Python package and its system dependency is not recorded by the packaging system. The next system update may upgrade the library to a newer version that breaks binary compatibility with the Python package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "For these reasons, you may reasonably decide to either statically link your dependencies, or to provide local copies in the installed package. You may also vendor the dependency in your source distribution. Sometimes these dependencies are also repackaged on PyPI, and can be declared as project dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "However, none of these issues apply to downstream packaging, and downstreams have good reasons to prefer dynamically linking to system dependencies. In particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "In many cases, reliably sharing dynamic dependencies between components is a large part of the *purpose* of a downstream packaging ecosystem. Helping to support that makes it easier for users of those systems to access upstream projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "Static linking and vendoring obscures the use of external dependencies, making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "Dynamic linking makes it possible to quickly and systematically replace the used libraries across an entire downstream packaging ecosystem, which can be particularly important when they turn out to contain a security vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "Using system dependencies makes the package benefit from downstream customization that can improve the user experience on a particular platform, without the downstream maintainers having to consistently patch the dependencies vendored in different packages. This can include compatibility improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "Static linking and vendoring can result in multiple different versions of the same library being loaded in the same process (for example, attempting to import two Python packages that link to different versions of the same library). This sometimes works without incident, but it can also lead to anything from library loading errors, to subtle runtime bugs, to catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "Last but not least, static linking and vendoring results in duplication, and may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "A good compromise between the needs of both parties is to provide a switch between using vendored and system dependencies. Ideally, if the package has multiple vendored dependencies, it should provide both individual switches for each dependency, and a general switch to control the default for them, e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "If the user requests using system dependencies, and a particular dependency is either missing or incompatible, the build should fail with an explanatory message rather than fall back to a vendored version. This gives the packager the opportunity to notice their mistake and a chance to consciously decide how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "It is reasonable for upstream projects to leave *testing* of building with system dependencies to their downstream repackagers. The goal of these guidelines is to facilitate more effective collaboration between upstream projects and downstream repackagers, not to suggest upstream projects take on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "A variety of downstream projects run some degree of testing on the packaged Python projects. Depending on the particular case, this can range from minimal smoke testing to comprehensive runs of the complete test suite. There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "Finding subtle bugs that can only be reproduced with particular hardware, system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "Testing the released package against newer (or older) dependency versions than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "Testing the package in an environment closely resembling the production setup. This can detect issues caused by non-trivial interactions between different installed packages, including packages that are not dependencies of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "Testing the released package against newer Python versions (including newer point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "Admittedly, sometimes downstream testing may yield false positives or bug reports about scenarios the upstream project is not interested in supporting. However, perhaps even more often it does provide early notice of problems, or find non-trivial bugs that would otherwise cause issues for the upstream project's users. While mistakes do happen, the majority of downstream packagers are doing their best to double-check their results, and help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "There are a number of things that upstream projects can do to help downstream repackagers test their packages efficiently and effectively, including some of the suggestions already mentioned above. These are typically improvements that make the test suite more reliable and easier to use for everyone, not just downstream packagers. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "Include the test files and fixtures in the source distribution, or make it possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "Do not write to the package directories during testing. Downstream test setups sometimes run tests on top of the installed package, and modifications performed during testing and temporary test files may end up being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "Make the test suite work offline. Mock network interactions, using packages such as responses_ or vcrpy_. If that is not possible, make it possible to easily disable the tests using Internet access, e.g. via a pytest_ marker. Use pytest-socket_ to verify that your tests work offline. This often makes your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "Make your tests work without a specialized setup, or perform the necessary setup as part of test fixtures. Do not ever assume that you can connect to system services such as databases — in an extreme case, you could crash a production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "If your package has optional dependencies, make their tests optional as well. Either skip them if the needed packages are not installed, or add markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "More generally, add markers to tests with special requirements. These can include e.g. significant space usage, significant memory usage, long runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "Do not assume that the test suite will be run with ``-Werror``. Downstreams often need to disable that, as it causes false positives, e.g. due to newer dependency versions. Assert for warnings using ``pytest.warns()`` rather than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "Aim to make your test suite reliable and reproducible. Avoid flaky tests. Avoid depending on specific platform details, don't rely on exact results of floating-point computation, or timing of operations, and so on. Fuzzing has its advantages, but you want to have static test cases for completeness as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "Split tests by their purpose, and make it easy to skip categories that are irrelevant or problematic. Since the primary purpose of downstream testing is to ensure that the package itself works, downstreams are not generally interested in tasks such as checking code coverage, code formatting, typechecking or running benchmarks. These tests can fail as dependencies are upgraded or the system is under load, without actually affecting the package itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "If your test suite takes significant time to run, support testing in parallel. Downstreams often maintain a large number of packages, and testing them all takes a lot of time. Using pytest-xdist_ can help them avoid bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "Ideally, support running your test suite via ``pytest``. pytest_ has many command-line arguments that are truly helpful to downstreams, such as the ability to conveniently deselect tests, rerun flaky tests (via pytest-rerunfailures_), add a timeout to prevent tests from hanging (via pytest-timeout_) or run tests in parallel (via pytest-xdist_). Note that test suites don't need to be *written* with ``pytest`` to be *executed* with ``pytest``: ``pytest`` is able to find and execute almost all test cases that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "Many downstreams provide stable release channels in addition to the main package streams. The goal of these channels is to provide more conservative upgrades to users with higher stability needs. These users often prefer to trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "While the exact policies differ, an important criterion for including a new package version in a stable release channel is for it to be available in testing for some time already, and have no known major regressions. For example, in Gentoo Linux a package is usually marked stable after being available in testing for a month, and being tested against the versions of its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "However, there are circumstances which demand more prompt action. For example, if a security vulnerability or a major bug is found in the version that is currently available in the stable channel, the downstream is facing a need to resolve it. In this case, they need to consider various options, such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "Each of these options involves certain risks and a certain amount of work, and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "There are some things that upstreams can do to tailor their workflow to stable release channels. These actions often are beneficial to the package's users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "Adjust the release frequency to the rate of code changes. Packages that are released rarely often bring significant changes with every release, and a higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "Avoid mixing bug fixes and new features, if possible. In particular, if there are known bug fixes merged already, consider making a new release before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "Consider making prereleases after major changes, to provide more testing opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "If your project is subject to very intense development, consider splitting one or more branches that include a more conservative subset of commits, and are released separately. For example, Django_ currently maintains three release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "Even if you don't wish to maintain additional branches permanently, consider making additional patch releases with minimal changes to the previous version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "Split your changes into focused commits that address one problem at a time, to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "**Discussions** are focused on providing comprehensive information about a specific topic. If you're just trying to get stuff done, see :doc:`/guides/index`." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that should be used to specify what a project **minimally** needs to run correctly. When the project is installed by :ref:`pip`, this is the specification that is used to install its dependencies." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "For example, if the project requires A and B, your ``install_requires`` would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "For example, it may be known, that your project requires at least v1 of 'A', and v2 of 'B', so it would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "It may also be known that project 'A' introduced a change in its v2 that breaks the compatibility of your project with v2 of 'A' and later, so it makes sense to not allow v2:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "It is not considered best practice to use ``install_requires`` to pin dependencies to specific versions, or to specify sub-dependencies (i.e. dependencies of your dependencies). This is overly-restrictive, and prevents the user from gaining the benefit of dependency upgrades." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "Lastly, it's important to understand that ``install_requires`` is a listing of \"Abstract\" requirements, i.e just names and version restrictions that don't determine where the dependencies will be fulfilled from (i.e. from what index or source). The where (i.e. how they are to be made \"Concrete\") is to be determined at install time using :ref:`pip` options. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:463 +msgid "Requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid ":ref:`Requirements Files ` described most simply, are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "Whereas ``install_requires`` defines the dependencies for a single project, :ref:`Requirements Files ` are often used to define the requirements for a complete Python environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "Whereas ``install_requires`` requirements are minimal, requirements files often contain an exhaustive listing of pinned versions for the purpose of achieving :ref:`repeatable installations ` of a complete environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "Whereas ``install_requires`` requirements are \"Abstract\", i.e. not associated with any particular index, requirements files often contain pip options like ``--index-url`` or ``--find-links`` to make requirements \"Concrete\", i.e. associated with a particular index or directory of packages. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "Whereas ``install_requires`` metadata is automatically analyzed by pip during an install, requirements files are not, and only are used when a user specifically installs them using ``python -m pip install -r``." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "For more on \"Abstract\" vs \"Concrete\" requirements, see https://caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "" + +#: ../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 +msgid "What is a source distribution?" +msgstr "" + +#: ../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 +msgid "What about eggs?" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid ":ref:`pip` came later in 2008, as an 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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "https://setuptools.readthedocs.io/en/latest/deprecated/easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "However, ``python setup.py`` and the use of :file:`setup.py` as a command line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python setup.py install``" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python -m pip install --editable .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "The command ``python setup.py install`` was deprecated in setuptools version *58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "``python setup.py check``, ``python setup.py register``, and ``python setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:104 +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "Not necessary, nor supported on :term:`PyPI `. But might be necessary on other :term:`package indexes ` (for example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "This guide does not make suggestions of replacement solutions for those commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "Custom build steps that for example either overwrite existing steps such as ``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "Although the usage of :file:`setup.py` as an executable script is deprecated, its usage as a configuration file for setuptools is absolutely fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** for a project to have a :file:`pyproject.toml` file at the root of its source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "One way to look at it is that the scope of setuptools has now been reduced to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr "" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +msgid "Complete" +msgstr "" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "" + +#: ../source/discussions/single-source-version.rst:10 +msgid "Many Python :term:`distribution packages ` publish a single Python :term:`import package ` where it is desired that the runtime ``__version__`` attribute on the import package report the same version specifier as :func:`importlib.metadata.version` reports for the distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "It is also frequently desired that this version information be derived from a version control system *tag* (such as ``v1.2.3``) rather than being manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "Some projects may choose to simply live with the data entry duplication, and rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "Alternatively, a project's chosen build system may offer a way to define a single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "If the code is in a version control system (VCS), such as Git, then the version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "The version can be hard-coded into the :file:`pyproject.toml` file -- and the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "The version string can be hard-coded into the source code -- either in a special purpose file, such as :file:`_version.txt` (which must then be shipped as part of the project's source distribution package), or as an attribute in a particular module, such as :file:`__init__.py`. The build system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "When the intention is that a distribution package and its associated import package share the same version, it is recommended that the project include an automated test case that ensures ``import_name.__version__`` and ``importlib.metadata.version(\"dist-name\")`` report the same value (note: for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "The following are links to some build system's documentation for handling version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:58 +msgid "`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "Here's a breakdown of the important behaviour differences between the src layout and the flat layout:" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "The src layout requires installation of the project to be able to run its code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "The src layout helps prevent accidental usage of the in-development copy of the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "This is especially relevant when the editable installation is implemented using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "Due to the firstly mentioned specialty of the src layout, a command-line interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development Mode ` for testing purposes. Since this can be unpractical in some situations, a workaround could be to prepend the package folder to Python's :py:data:`sys.path` when called via its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:358 +msgid "Versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "A post-release of an alpha release (possible, but discouraged): ``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "Finally, epochs were intended to fix the sorting order when changing the versioning scheme. For example, if a project was using calendar versioning, with versions like ``23.12``, and switched to semantic versioning, with versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go the wrong way. To correct this, the new version numbers would have an explicit epoch, as in ``1!1.0``, in order to be treated as more recent than the old version numbers. However, this is discouraged, and it is preferable to use a higher version number that is unlikely to cause user confusion, such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:87 +msgid "The idea of *semantic versioning* (or SemVer) is to use 3-part version numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "Python projects adopting semantic versioning should abide by clauses 1-8 of the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +msgid "Calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:127 +msgid "Semantic versioning is not a suitable choice for all projects, such as those with a regular time-based release cadence and a deprecation process that provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "Calendar version numbers typically take the form *year.month* (for example, 23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid ":doc:`Pip `, the standard Python package installer, uses calendar versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +msgid "Other schemes" +msgstr "" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "Version information for all :term:`distribution packages ` that are locally available in the current environment can be obtained at runtime using the standard library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "Many projects also choose to version their top level :term:`import packages ` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "This technique can be particularly valuable for CLI applications which want to ensure that version query invocations (such as ``pip -V``) run as quickly as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "Package publishers wishing to ensure their reported distribution package and import package versions are consistent with each other can review the :ref:`single-source-version` discussion for potential approaches to doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "As import packages and modules are not *required* to publish runtime version information in this way (see the withdrawn proposal in :pep:`PEP 396 <396>`), the ``__version__`` attribute should either only be queried with interfaces that are known to provide it (such as a project querying its own version or the version of one of its direct dependencies), or else the querying code should be designed to handle the case where the attribute is missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "Some projects may need to publish version information for external APIs that aren't the version of the module itself. Such projects should define their own project-specific ways of obtaining the relevant information at runtime. For example, the standard library's :mod:`ssl` module offers multiple ways to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "Some more examples of unusual version numbers are given in a `blog post `_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "A full list mapping the top level names available for import to the distribution packages that provide those import packages and modules may be obtained through the standard library's :func:`importlib.metadata.packages_distributions` function. This means that even code that is attempting to infer a version to report for all importable top-level names has a means to fall back to reporting the distribution version information if no ``__version__`` attribute is defined. Only standard library modules, and modules added via means other than Python package installation would fail to have version information reported in that case." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "Have a source tree containing the package. This is typically a checkout from a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "These last 2 steps are typically performed by :ref:`pip` when an end user runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "Refer to the :ref:`pyproject.toml guide ` for a complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 +#: ../source/flow.rst:143 +msgid "The :ref:`build` package knows how to invoke your build tool to create one of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "The default behaviour of :ref:`build` is to make both an sdist and a wheel from the source in the current directory; the above examples are deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, or :ref:`pdm`." +msgstr "" + +#: ../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 :term:`source tree ` and builds a :term:`source distribution ` or :term:`built distribution ` from it. The build is delegated to the backend by a :term:`frontend `. All backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "The concrete form :term:`Core Metadata` takes when included inside an installed :term:`Project` (``METADATA`` file) or a :term:`Distribution Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "The :ref:`specification ` and the set of :term:`Core Metadata Field`\\s it defines that describe key static attributes of a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "A single key-value pair (or sequence of such with the same name, for multiple-use fields) defined in the :term:`Core Metadata` spec and stored in the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "" + +#: ../source/glossary.rst:86 +msgid "The physical distribution artifact (i.e. a file on disk) for a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "" + +#: ../source/glossary.rst:92 +msgid "A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "" + +#: ../source/glossary.rst:108 +msgid "A :term:`Built Distribution` format introduced by :ref:`setuptools`, which has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "" + +#: ../source/glossary.rst:124 +msgid "A Python module which can contain other modules or recursively, other packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +msgid "Installed Project" +msgstr "" + +#: ../source/glossary.rst:136 +msgid "A :term:`Project` that is installed for use with a Python interpreter or :term:`Virtual Environment`, as described in the specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "" + +#: ../source/glossary.rst:152 +msgid "A PyPI Trove classifier (as :ref:`described ` in the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 +#: ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "A string with valid SPDX license expression syntax, including one or more SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "A valid SPDX short-form license identifier, originally specified in :pep:`639`. This includes all valid SPDX identifiers and the custom ``LicenseRef-[idstring]`` strings conforming to the SPDX specification. Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "" + +#: ../source/glossary.rst:192 +msgid "A repository of distributions with a web interface to automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "" + +#: ../source/glossary.rst:198 +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:202 +#: ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +msgid "Project Root Directory" +msgstr "" + +#: ../source/glossary.rst:229 +msgid "The filesystem directory in which a :term:`Project`'s :term:`source tree ` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "The on-disk format of a :term:`Project` used for development, containing its raw source code before being packaged into a :term:`Source Distribution ` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "Metadata defined by the package author in a :term:`Project`'s :term:`source tree `, to be transformed into :term:`Core Metadata field`\\s in the :term:`Built Metadata` by the project's :term:`build backend `. Can be written as :term:`Pyproject Metadata`, or in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "" + +#: ../source/glossary.rst:257 +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:260 +msgid "Pyproject Metadata" +msgstr "" + +#: ../source/glossary.rst:263 +msgid "The :term:`Project Source Metadata` format defined by the :ref:`declaring-project-metadata` specification and originally introduced in :pep:`621`, stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of a :term:`pyproject.toml` file. Notably, *not* a tool-specific source metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +msgid "Pyproject Metadata Key" +msgstr "" + +#: ../source/glossary.rst:274 +msgid "A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "" + +#: ../source/glossary.rst:287 +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 discuss issues on the `distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "" + +#: ../source/glossary.rst:311 +msgid "The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "" + +#: ../source/glossary.rst:316 +msgid "A snapshot of a :term:`Project` at a particular point in time, denoted by a version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "" + +#: ../source/glossary.rst:344 +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:348 +msgid "Root License Directory" +msgstr "" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "The directory under which license files are stored in a :term:`Project Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, this is the :term:`Project Root Directory`. For a :term:`Built Distribution` or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` directory of the wheel archive or project folder respectively. Also, the root directory that paths recorded in the ``License-File`` :term:`Core Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "" + +#: ../source/glossary.rst:369 +msgid "The project specification files for :ref:`distutils` and :ref:`setuptools`. See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "" + +#: ../source/glossary.rst:391 +msgid "A package provided in a format native to the operating system, e.g. an rpm or dpkg file." +msgstr "" + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "" + +#: ../source/glossary.rst:414 +msgid "The standard :term:`Built Distribution` format originally introduced in :pep:`427` and defined by the :ref:`binary-distribution-format` specification. See :ref:`package-formats` for more information. Not to be confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +msgid "Wheel Project" +msgstr "" + +#: ../source/glossary.rst:424 +msgid "The PyPA reference implementation of the :term:`Wheel Format`; see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "Unofficial scripts or attempts at download count inflation (raises download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ [#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "Enable the `BigQuery API `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "For more detailed instructions on how to get started with BigQuery, check out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:214 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:33 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "The following query counts the total number of downloads for the project \"pytest\"." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "To count downloads from pip only, filter on the ``details.installer.name`` column." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "Extract the Python version from the ``details.python`` column. Warning: This query processes over 500 GB of data." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "The URL generated here is not guaranteed to be stable, but currently aligns with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "https://files.pythonhosted.org/packages/eb/45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/sampleproject-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "https://files.pythonhosted.org/packages/56/0a/178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +msgid "https://files.pythonhosted.org/packages/63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/sampleproject_nomura-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +msgid "https://files.pythonhosted.org/packages/21/e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "https://files.pythonhosted.org/packages/6f/5b/2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/sampleproject-1.3.1.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "Besides using the BigQuery console, there are some additional tools which may be useful when analyzing download statistics." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "The `ClickPy`_ project provides a public application to visualize download statistics, with free direct SQL access to the underlying open-source `ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:713 +msgid "References" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "For example if you have a package named ``myapp-plugin-a`` and it includes the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "In this example, ``discovered_plugins`` would be a collection of type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "Now the module of your choice can be imported by executing ``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "Since this specification is part of the :doc:`standard library `, most packaging tools other than setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "This guide will walk you through creating and packaging a standalone command-line application that can be installed with :ref:`pipx`, a tool for creating and managing :term:`Python Virtual Environments ` and exposing the executable scripts of packages (and available manual pages) for use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +msgid "Creating the package" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "First of all, create a source tree for the :term:`project `. For the sake of an example, we'll build a simple tool outputting a greeting (a string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "Advise on the optimal structure of a Python package in another guide or discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "This project will adhere to :ref:`src-layout ` and in the end be alike this file tree, with the top-level folder and package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "The actual code responsible for the tool's functionality will be stored in the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "The above function receives several keyword arguments that determine how the greeting to output is constructed. Now, construct the command-line interface to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "The command-line interface is built with typer_, an easy-to-use CLI parser based on Python type hints. It provides auto-completion and nicely styled command-line help out of the box. Another option would be :py:mod:`argparse`, a command-line parser which is included in Python's standard library. It is sufficient for most needs, but requires a lot of code, usually in ``cli.py``, to function properly. Alternatively, docopt_ makes it possible to create CLI interfaces based solely on docstrings; advanced users are encouraged to make use of click_ (on which ``typer`` is based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "Now, add an empty :file:`__init__.py` file, to define the project as a regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "The file :file:`__main__.py` marks the main entry point for the application when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works immediately with flat layout, but requires installation of the package with src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "In order to enable calling the command-line interface directly from the :term:`source tree `, i.e. as ``python src/greetings``, a certain hack could be placed in this file; read more at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +msgid "``pyproject.toml``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "The project's :term:`metadata ` is placed in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` (this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "For the project to be recognised as a command-line tool, additionally a ``console_scripts`` :ref:`entry point ` (see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "Now, the project's source tree is ready to be transformed into a :term:`distribution package `, which makes it installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +msgid "Installing the package with ``pipx``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "After installing ``pipx`` as described in :ref:`installing-stand-alone-command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "This will expose the executable script we defined as an entry point and make the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "Since this example uses ``typer``, you could now also get an overview of the program's usage by calling it with the ``--help`` option, or configure completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "To just run the program without installing it permanently, use ``pipx run``, which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "This syntax is a bit impractical, however; as the name of the entry point we defined above does not match the package name, we need to state explicitly which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "There is, however, a more practical solution to this problem, in the form of an entry point specific to ``pipx run``. The same can be defined as follows in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "Thanks to this entry point (which *must* match the package name), ``pipx`` will pick up the executable script as the default one and run it, which makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +msgid "Conclusion" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "You know by now how to package a command-line application written in Python. A further step could be to distribute your package, meaning uploading it to a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions at :ref:`Packaging your project`. And once you're done, don't forget to :ref:`do some research ` on how your package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "This section covers some additional details on configuring, packaging and distributing Python projects with ``setuptools`` that aren't covered by the 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "The section does *not* aim to cover best practices for Python project development as a whole. For example, it does not provide guidance or tool recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "For more reference material, see :std:doc:`Building and Distributing Packages ` in the :ref:`setuptools` docs, but note that some advisory content there may be outdated. In the event of conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "First, make sure you have already fulfilled the :ref:`requirements for installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below `)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "It's the file where various aspects of your project are configured. The primary feature of :file:`setup.py` is that it contains a global ``setup()`` 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "It's the command line interface for running various commands that relate to packaging tasks. To get a listing of available commands, run ``python3 setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid ":file:`setup.cfg` is an ini file that contains option defaults for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "All projects should contain a readme file that covers the goal of the project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "Projects using :ref:`setuptools` 0.6.27+ have standard readme files (:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "However, you may not have to use a :file:`MANIFEST.in`. For an example, the `PyPA sample project `_ has removed its manifest file, since all the necessary files have been included by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid ":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "Every package should include a license file detailing the terms of distribution. In many jurisdictions, packages without an explicit license 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "Although it's not required, the most common practice is to include your Python modules and packages under a single top-level package that has the same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "For an example, see the `sample `_ package that's included in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "As mentioned above, the primary feature of :file:`setup.py` is that it contains a global ``setup()`` function. The keyword arguments to this function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "Some are temporarily explained below until their information is moved elsewhere. The full list can be found :doc:`in the setuptools documentation `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "Most of the snippets given are taken from the `setup.py `_ contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "See :ref:`Choosing a versioning scheme` for more information on ways to use versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "Set ``packages`` to a list of all :term:`packages ` in your project, including their subpackages, sub-subpackages, etc. Although the 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "\"install_requires\" should be used to specify what dependencies a project minimally needs to run. When the project is installed by :ref:`pip`, this is the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "For more on using \"install_requires\" see :ref:`install_requires vs Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the package’s implementation, or text files containing documentation that might be of interest to programmers using the package. These files are called \"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "The value must be a mapping from package name to a list of relative path names that should be copied into the package. The paths are interpreted as relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "For more information, see :std:doc:`Including Data Files ` from the :std:doc:`setuptools docs `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "Although configuring :ref:`Package Data` is sufficient for most needs, in some cases you may need to place data files *outside* of your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "For more information see the distutils section on :ref:`Installing Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:158 +#: ../source/specifications/pyproject-toml.rst:656 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, the recommended approach to achieve cross-platform compatibility is to use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "To install a Python package in \"editable\"/\"development\" mode Change directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "To have your project installable from a :term:`Package Index` like :term:`PyPI `, you'll need to create a :term:`Distribution ` (aka \":term:`Package `\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "Before you can build wheels and sdists for your project, you'll need to install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "If your project is pure Python then you'll be creating a :ref:`\"Pure Python Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "If your project contains compiled extensions, then you'll be creating what's called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "If your project also supports Python 2 *and* contains no C extensions, then you should create what's called a *Universal Wheel* by adding the following to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "Only use this setting if your project does not have any C extensions *and* supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "*Pure Python Wheels* contain no compiled extensions, and therefore only require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "The ``wheel`` package will detect that the code is pure Python, and build a wheel that's named such that it's usable on any Python 3 installation. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "*Platform Wheels* are wheels that are specific to a certain platform like Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "The ``wheel`` package will detect that the code is not pure Python, and build a wheel that's named such that it's only usable on the platform that it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid ":term:`PyPI ` currently supports uploads of platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "When you ran the command to create your distribution, a new directory ``dist/`` was created under your project's root directory. That's where you'll find your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "First, you need a :term:`PyPI ` user account. You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "Now you'll create a PyPI `API token`_ so you will be able to securely upload your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "Go to https://pypi.org/manage/account/#api-tokens and create a new `API token`_; don't limit its scope to a particular project, since you are creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "**Don't close the page until you have copied and saved the token — you won't see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "To avoid having to copy and paste the token every time you upload, you can create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "Once you have an account you can upload your distributions to :term:`PyPI ` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "The process for uploading a release is the same regardless of whether or not the project already exists on PyPI - if it doesn't exist yet, it will be automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "For the second and subsequent releases, PyPI only requires that the version number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:669 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "The ability to drop support for older Python versions is enabled by the standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "This mechanism can be used to drop support for older Python versions, by amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "This workflow requires that the user installing the package uses Pip [#]_, or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "If you use this method, either remove this option or section, or explicitly set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "Regarding :ref:`deprecated ` direct ``setup.py`` invocations, passing the ``--universal`` flag on the command line could override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +msgid "1. Install twine" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "Set the version ranges declaring which Python distributions are supported within your project's :file:`pyproject.toml`. The :ref:`requires-python` configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "You can specify version ranges and exclusion rules (complying with the :ref:`version-specifiers` specification), such as at least Python 3.9. Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "If using the :ref:`setuptools` build backend, consult the `dependency-management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "Avoid adding upper bounds to the version ranges, e.g. ``\">= 3.8, < 3.10\"``. Doing so can cause different errors and version conflicts. See the `discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "Within a Python source package (the zip or the tar-gz file you download) is a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "This file is generated by the :term:`build backend ` when it generates the source package. The file contains a set of keys and values, the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "The ``Requires-Python`` field is set and matches your specification in the configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +msgid "Dropping a Python version" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "In principle, at least metadata support for Python versions should be kept as long as possible, because once that has been dropped, people still depending on a version will be forced to downgrade. If however supporting a specific version becomes a blocker for a new feature or other issues occur, the metadata ``Requires-Python`` should be amended. Of course this also depends on whether the project needs to be stable and well-covered for a wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "When dropping a Python version, it might also be rewarding to upgrade the project's code syntax generally, apart from updating the versions used in visible places (like the testing environment). Tools like pyupgrade_ or `ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "If you wish to host your own simple repository [1]_, you can either use a software package like :doc:`devpi ` or you can simply create the proper directory structure and use any web server that can serve static files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:65 +#: ../source/guides/index-mirrors-and-caches.rst:56 +#: ../source/guides/supporting-windows-using-appveyor.rst:139 +msgid "Additional notes" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:67 +#: ../source/guides/index-mirrors-and-caches.rst:58 +msgid ":ref:`devpi`" +msgstr "" + +#: ../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/hosting-your-own-index.rst:70 +msgid "multiple indexes with inheritance, with syncing, replication, fail-over; mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "For complete documentation of the simple repository protocol, see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "Can be configured to fall back to PyPI (or another package index) if a requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "pip provides a number of facilities for speeding up installation by using local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "A variation on the above which pre-builds the installation files for the requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "multiple indexes with inheritance; syncing, replication, fail-over; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr "" + +#: ../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 "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 "" + +#: ../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 vectorized instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "The extensions provided in these installers are typically compatible with the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "The SciPy site lists `several distributions `_ that provide the full SciPy stack to end users in an easy to use and update format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "Some of these distributions may not be compatible with the standard ``pip`` and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "``conda`` is an open source (BSD licensed) package management system and environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "Anaconda `Anaconda `_ is a Python distribution published by Anaconda, Inc. It is a stable collection of Open Source packages for big data and scientific use, and a collection of Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "In addition to the full distribution provided by Anaconda, the conda package manager itself is available in `miniconda `_, `miniforge `_, and `pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "Conda packages are available on multiple channels on Anaconda.org, including the default channel supported by Anaconda, Inc, the community supported conda-forge channel, which provides a wide variety of pre-built packages, and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "Many packages provide command line applications. Examples of such packages are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "Now you can install packages with ``pipx install`` and run the package's applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:113 +msgid "For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "To see a list of packages installed with pipx and which applications are available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "pipx also allows you to install and run the latest version of an application in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "This section covers how to install :ref:`pip`, :ref:`setuptools`, and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "To learn more about Python in Fedora, please visit the `official Fedora docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "Enable the `EPEL repository `_ using `these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "Since EPEL only offers extra, non-conflicting packages, EPEL does not offer setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "To install pip, wheel, and setuptools, in a parallel, non-system environment (using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "Use the \"Software Collections\" feature to enable a parallel collection that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "For Redhat, see here: https://developers.redhat.com/products/softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:108 +msgid "openSUSE" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:118 +msgid "Debian/Ubuntu and derivatives" +msgstr "" + +#: ../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 "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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +msgid "Install packages in a virtual environment using pip and venv" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "This guide uses the term **package** to refer to a :term:`Distribution Package`, which commonly is installed from an external host. This differs from the term :term:`Import Package` which refers to import modules in your Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../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 ":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 "" + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "The second argument is the location to create the virtual environment. Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "You should exclude your virtual environment directory from your version control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "Before you can start installing or using packages in your virtual environment you'll need to ``activate`` it. Activating a virtual environment will put the virtual environment-specific ``python`` and ``pip`` executables into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "To confirm the virtual environment is activated, check the location of your Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "While the virtual environment is active, the above command will output a filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "While a virtual environment is activated, pip will install packages into that specific environment. This enables you to import and use packages in your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "If you want to switch projects or leave your virtual environment, ``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "Closing your shell will deactivate the virtual environment. If you open a new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "If you want to reactivate an existing virtual environment, follow the same instructions about activating a virtual environment. There's no need to create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid ":ref:`pip` is the reference Python package manager. It's used to install and update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "The Python installers for macOS include pip. On Linux, you may have to install an additional package such as ``python3-pip``. You can make sure that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "Afterwards, you should have the latest version of pip installed in your user site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "The Python installers for Windows include pip. You can make sure that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +msgid "Install packages using pip" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "When your virtual environment is activated, you can install packages. Use the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "For example, let's install the `Requests`_ library from the :term:`Python Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "pip allows you to specify which version of a package to install using :term:`version specifiers `. For example, to install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +msgid "Install extras" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "Some packages have optional `extras`_. You can tell pip to install these by specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "pip can install a package directly from its source code. For example, to install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../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 "pip can install packages directly from their version control system. For example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "For more information on supported version control systems and syntax, see pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "If you have a local copy of a :term:`Distribution Package`'s archive (a zip, wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "If you have a directory containing archives of multiple packages, you can tell pip to look for packages there and not to use the :term:`Python Package Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "This is useful if you are installing packages on a system with limited connectivity or if you want to strictly control the origin of distribution packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "If you want to download packages from a different index than the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "If you want to allow packages from both the :term:`Python Package Index (PyPI)` and a separate index, you can use the ``--extra-index-url`` flag instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:392 +msgid "Upgrading packages" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "pip can upgrade packages in-place using the ``--upgrade`` flag. For example, to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "Instead of installing packages individually, pip allows you to declare all dependencies in a :ref:`Requirements File `. For example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "And tell pip to install all of the packages in this file using the ``-r`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +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/installing-using-pip-and-virtual-environments.rst:511 +msgid "The ``pip freeze`` command is useful for creating :ref:`pip:Requirements Files` that can re-create the exact versions of all packages installed in an environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid ":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s license and paths to license files and other legally required information. This document aims to provide clear guidance how to migrate from the legacy to the standardized way of declaring licenses. Make sure your preferred build backend supports :pep:`639` before trying to apply the newer guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "The Setuptools project itself, as of `version 75.6.0 `__, does not use the ``License`` field in its own project source metadata. Further, it no longer explicitly specifies ``license_file``/``license_files`` as it did previously, since Setuptools relies on its own automatic inclusion of license-related files matching common patterns, such as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "It includes the following license-related metadata in its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/LICENSE` in the wheel, and unpacked from there into the site directory (e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the respective archive and ``{VERSION}`` the version of the Setuptools release in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "Suppose Setuptools were to include the licenses of the third-party projects that are vendored in the :file:`setuptools/_vendor/` and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "A comprehensive license expression covering both Setuptools proper and its vendored dependencies would contain these metadata, combining all the license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "In addition, per the requirements of the licenses, the relevant license files must be included in the package. Suppose the :file:`LICENSE` file contains the text of the MIT license and the copyrights used by Setuptools, ``pyparsing``, ``more_itertools`` and ``ordered-set``; and the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` directory contain the Apache 2.0 and 2-clause BSD license text, and the Packaging copyright statement and `license choice notice `__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "Specifically, we assume the license files are located at the following paths in the project source tree (relative to the project root and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "Or alternatively, the license files can be specified explicitly (paths will be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "In the resulting sdist, with :file:`/` as the root of the archive and ``{VERSION}`` the version of the Setuptools release specified in the Core Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "In the built wheel, with :file:`/` being the root of the archive and ``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "Finally, in the installed project, with :file:`site-packages/` being the site dir and ``{VERSION}`` as the previous, the license files would be installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "The following covers the range of common use cases from a user perspective, providing guidance for each. Do note that the following should **not** be considered legal advice, and readers should consult a licensed legal practitioner in their jurisdiction if they are unsure about the specifics for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "If your package isn't shared publicly, i.e. outside your company, organization or household, it *usually* isn't strictly necessary to include a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "However, it is still a good idea to include ``LicenseRef-Proprietary`` as a license expression in your package configuration, and/or a copyright statement and any legal notices in a :file:`LICENSE.txt` file in the root of your project directory, which will be automatically included by packaging tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "While you aren't required to include a license, if you don't, no one has `any permission to download, use or improve your work `__, so that's probably the *opposite* of what you actually want. The `MIT license `__ is a great choice instead, as it's simple, widely used and allows anyone to do whatever they want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "To apply it, just paste `the text `__ into a file named :file:`LICENSE.txt` at the root of your repo, and add the year and your name to the copyright line. Then, just add ``license = \"MIT\"`` under ``[project]`` in your :file:`pyproject.toml` if your packaging tool supports it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "To use a particular license, simply paste its text into a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in a file starting with :file:`LICENSE` or :file:`COPYING` already, and add ``license = \"LICENSE-ID\"`` under ``[project]`` in your :file:`pyproject.toml` if your packaging tool supports it, or else in its config file. You can find the ``LICENSE-ID`` and copyable license text on sites like `ChooseALicense `__ or `SPDX `__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "Many popular code hosts, project templates and packaging tools can add the license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "If you already have license files and metadata in your project, you should only need to make a couple of tweaks to take advantage of the new functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "In your project config file, enter your license expression under ``license`` (``[project]`` table in :file:`pyproject.toml`), or the equivalent for your packaging tool, and make sure to remove any legacy ``license`` table subkeys or ``License ::`` classifiers. Your existing ``license`` value may already be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); otherwise, check the `SPDX license list `__ for the identifier that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "Make sure to list your license files under ``license-files`` under ``[project]`` in :file:`pyproject.toml` or else in your tool's configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "See the :ref:`licensing-example-basic` for a simple but complete real-world demo of how this works in practice. See also the best-effort guidance on how to translate license classifiers into license expression provided by the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers `__. Packaging tools may support automatically converting legacy licensing metadata; check your tool's documentation for more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "If your project includes code from others covered by different licenses, such as vendored dependencies or files copied from other open source software, you can construct a license expression to describe the licenses involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "In short, ``License-1 AND License-2`` mean that *both* licenses apply (for example, you included a file under another license), and ``License-1 OR License-2`` means that *either* of the licenses can be used, at the user's option (for example, you want to allow users a choice of multiple licenses). You can use parenthesis (``()``) for grouping to form expressions that cover even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "In your project config file, enter your license expression under ``license`` (``[project]`` table of :file:`pyproject.toml`), or the equivalent for your packaging tool, and make sure to remove any legacy ``license`` table subkeys or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "Also, make sure you add the full license text of all the licenses as files somewhere in your project repository. List the relative path or glob patterns to each of them under ``license-files`` under ``[project]`` in :file:`pyproject.toml` (if your tool supports it), or else in your tool's configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "As an example, if your project was licensed MIT but incorporated a vendored dependency (say, ``packaging``) that was licensed under either Apache 2.0 or the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in the :file:`_vendor/` subdirectory, so to include all of them, you'd specify ``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or ``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "See a fully worked out :ref:`licensing-example-advanced` for an end-to-end application of this to a real-world complex project, with many technical details, and consult a `tutorial `__ for more help and examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "README files for Python projects are often named ``README``, ``README.txt``, ``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "For your README to display properly on PyPI, choose a markup language supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "`reStructuredText `_ (without Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "Markdown (`GitHub Flavored Markdown `_ by default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "If you're using GitHub-flavored Markdown to write a project's description, ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "It's recommended that you use ``twine`` to upload the project's distribution packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "Install the latest version of `twine `_; version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 ":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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "The default upload settings switched to ``pypi.org`` in the following versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "Then simply delete the line starting with ``repository`` and you will use your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "As a result, attempting explicit registration after switching to using PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "The solution is to skip the registration step, and proceed directly to uploading artifacts." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "``pypi.org`` provides a fully functional interface for logged in users to manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python -m build``" +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "The :term:`project` must contain a :file:`pyproject.toml` file at the root of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "Note that the presence of a :file:`pyproject.toml` file (even if empty) triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays unchanged):" +msgstr "" + +#: ../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 "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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "For some projects this isolation is unwanted and it can be deactivated as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:126 +msgid "``python -m build --no-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:127 +msgid "``python -m pip install --no-build-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "All static metadata can optionally be moved to a ``[project]`` table in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "Read :ref:`pyproject-project-table` for the full specification of the content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "If some packaging metadata fields are not static they need to be listed as ``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "For example, a process exists that can not be changed easily and it needs to execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "The typical use cases for binary extensions break down into just three conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "require that end users be able to either build them from source, or else that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "may not be compatible with different builds of the CPython reference interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "often will not work correctly with alternative interpreters such as PyPy, IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "`SWIG `__ is a wrapper interface generator that allows a variety of programming languages, including Python, to interface with C and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "The CPython :doc:`Extending and Embedding ` guide includes an introduction to writing a :doc:`custom extension module in C `." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "FIXME: Elaborate that all this is one of the reasons why you probably *don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 `." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../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 "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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "For a more in depth explanation of how extension modules are used by CPython on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "The `pypackaging-native `_ website has additional coverage of packaging Python packages with native code. It aims to provide an overview of the most important packaging issues for such projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "Examples of topics covered are non-Python compiled dependencies (\"native dependencies\"), the importance of the ABI (Application Binary Interface) of native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "Namespace packages can be useful for a large collection of loosely-related packages (such as a large corpus of client libraries for multiple products 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "There are currently two different approaches to creating namespace packages, from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "Use `native namespace packages`_. This type of namespace package is defined in :pep:`420` and is available in Python 3.3 and later. This is recommended if packages in your namespace only ever need to support Python 3 and installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "Use `legacy namespace packages`_. This comprises `pkgutil-style namespace packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "Python 3.3 added **implicit** namespace packages from :pep:`420`. All that is required to create a native namespace package is that you just omit :file:`__init__.py` from the namespace package directory. An example file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "It is extremely important that every distribution that uses the namespace package omits the :file:`__init__.py` or uses a pkgutil-style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "The ``src-layout`` directory structure allows automatic discovery of packages by most :term:`build backends `. See :ref:`src-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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid ":ref:`setuptools` will search the directory structure for implicit namespace packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "A complete working example of two native namespace packages can be found in the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "To migrate an existing package, all packages sharing the namespace must be migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "To create a pkgutil-style namespace package, you need to provide an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "The :file:`__init__.py` file for the namespace package needs to contain the following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "A complete working example of two pkgutil-style namespace packages can be found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "The information in this section is obsolete and is no longer functional (as of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "``pkg_resources`` has been deprecated and was fully removed in Setuptools 82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid ":doc:`Setuptools ` previously provided the ``pkg_resources.declare_namespace`` function and the ``namespace_packages`` argument to :func:`~setuptools.setup`. Together these could be used to declare namespace packages. While this approach is no longer supported, it may still be encountered in environments using older ``setuptools`` versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "To create a pkg_resources-style namespace package, you need to provide an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "Some older recommendations advise the following in the namespace package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "Finally, every distribution must provide the ``namespace_packages`` argument to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the second step, but this time, enter ``testpypi`` as the name of the GitHub Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "Your \"pending\" publishers are now ready for their first use and will create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "GitHub CI/CD workflows are declared in YAML files stored in the ``.github/workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "Start it with a meaningful name and define the event that should make GitHub run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "We will have to define two jobs to publish to PyPI and TestPyPI respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "First, we'll define the job for building the dist packages of your project and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:112 +msgid "If you adapt this workflow to build multiple platform-specific wheels, use uniquely named artifacts for each build job and adjust the download step accordingly. The `cibuildwheel GitHub Actions examples`_ show a fuller wheel matrix layout." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:122 +msgid "This will download your repository into the CI runner and then install and activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:125 +msgid "And now we can build the dists from source and store them. In this example, we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:135 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:137 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:151 +msgid "This will also ensure that the PyPI publishing workflow is only triggered if the current commit is tagged." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:155 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "Finally, add the following steps at the end:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the stored distribution package has been downloaded by the `download-artifact`_ action, it uploads the contents of the ``dist/`` folder into PyPI unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:171 +msgid "Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates and uploads :pep:`740`-compatible attestations for each distribution by default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:179 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:181 +msgid "Now, repeat these steps and create another job for publishing to the TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:191 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:195 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:197 +msgid "This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:205 +msgid "That's all, folks!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:207 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:215 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:223 +msgid "It is recommended to keep the integrated GitHub Actions at their latest versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:744 +msgid "Installation" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +msgid "`GitHub Actions `_ provides Windows, Linux and a macOS environments." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:67 +msgid "`Appveyor `_ provides a Windows environment (Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:78 +msgid "Both `GitHub Actions`_ 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 "" + +#: ../source/guides/supporting-multiple-python-versions.rst:83 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:87 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:89 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:98 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:105 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:115 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:122 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:124 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:31 +msgid "Setting up" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:33 +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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:38 +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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:42 +msgid "Once you have set up your Appveyor account and added your project, Appveyor will automatically build your project each time a commit occurs." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:46 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:48 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:61 +msgid "appveyor.yml" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:67 +msgid "This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:69 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:72 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:80 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:86 +msgid "The ``build`` section simply switches off builds - there is no build step needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:89 +msgid "The main sections that will need to be tailored to your project are ``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:92 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:101 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:106 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:111 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +msgid "You can simply download the batch file and include it in your project unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:129 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:131 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:142 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:144 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:148 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:152 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:157 +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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:162 +msgid "``DISTUTILS_USE_SDK``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:163 +msgid "``MSSdk``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:164 +msgid "``INCLUDE``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:165 +msgid "``LIB``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:167 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:173 +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 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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:180 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:184 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:189 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:195 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:197 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:208 +msgid "External dependencies" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:210 +msgid "The supplied scripts will successfully build any distribution that does not rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:213 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:222 +msgid "Support scripts" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:224 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:226 +msgid "``appveyor-sample/build.cmd``" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:5 +msgid "Tool recommendations" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +msgid "Installing packages" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "Popular :term:`build backends ` for pure-Python packages include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid ":doc:`Flit-core ` -- developed with but separate from :ref:`Flit`. A minimal and opinionated build backend. It does not support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid ":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "If you use setuptools, please be aware that some features that predate standardisation efforts are now deprecated and only *temporarily kept* for compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid ":ref:`setuptools` -- natively supports C and C++ (with third-party plugins for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid ":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid ":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +msgid "Building distributions" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "For projects hosted on or published via supported CI/CD platforms, it is recommended to use the :ref:`Trusted Publishing `, which allows the package to be securely uploaded to PyPI from a CI/CD workflow without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "As of November 2024, PyPI supports the following platforms as Trusted Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "The other available method is to upload the package manually using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "**Never** use ``python setup.py upload`` for this task. In addition to being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "The information on this page has moved to :doc:`setuptools:userguide/miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "The database for TestPyPI may be periodically pruned, so it is not unusual for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "You can upload your distributions to TestPyPI using :ref:`twine` by specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "If you want to avoid being prompted for your username and password every time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "The ``[build-system]`` table should always be present, regardless of which build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "On the other hand, the ``[project]`` table is understood by *most* build backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "A notable exception is Poetry_, which before version 2.0 (released January 5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` table instead. With version 2.0, it supports both. Also, the setuptools_ build backend supports both the ``[project]`` table, and the older format in ``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "When a field is dynamic, it is the build backend's responsibility to fill it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:129 +#: ../source/specifications/pyproject-toml.rst:154 +#: ../source/specifications/pyproject-toml.rst:166 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "Put the name of your project on PyPI. This field is required and is the only field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "The project name must consist of ASCII letters, digits, underscores \"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "Comparison of project names is case insensitive and treats arbitrarily long runs of underscores, hyphens, and/or periods as equal. For example, if you register a project named ``cool-stuff``, users will be able to download it or declare a dependency on it using any of the following spellings: ``Cool-Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:134 +#: ../source/specifications/pyproject-toml.rst:160 +#: ../source/specifications/pyproject-toml.rst:181 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha release) are possible; see the :ref:`specification ` for full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "This allows use cases such as filling the version from a ``__version__`` attribute or a Git tag. Consult the :ref:`single-source-version` discussion for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +msgid "``dependencies``/``optional-dependencies``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "See :ref:`Dependency specifiers ` for the full syntax you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "You may want to make some of your dependencies optional, if they are only needed for a specific feature of your package. In that case, put them in ``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "Each of the keys defines a \"packaging extra\". In the example above, one could use, e.g., ``pip install your-project-name[gui]`` to install your project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:157 +#: ../source/specifications/pyproject-toml.rst:250 +msgid "``requires-python``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "This lets you declare the minimum version of Python that you support [#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "To install a command as part of your package, declare it in the ``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "In this example, after installing your project, a ``spam-cli`` command will be available. Executing this command will do the equivalent of ``import sys; from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "On Windows, scripts packaged this way need a terminal, so if you launch them from within a graphical application, they will make a terminal pop up. To prevent this from happening, use the ``[project.gui-scripts]`` table instead of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "In that case, launching your script from the command line will give back control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:337 +msgid "``authors``/``maintainers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "Both of these fields contain lists of people identified by a name and/or an email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:196 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:156 +#: ../source/specifications/pyproject-toml.rst:209 +msgid "``readme``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "This is a longer description of your project, to display on your project page on PyPI. Typically, your project will have a ``README.md`` or ``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "``license`` is an :term:`SPDX license expression ` consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "A previous PEP had specified ``license`` to be a table with a ``file`` or a ``text`` key, this format is now deprecated. Most :term:`build backends` now support the new format as shown in the following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:313 +msgid "setuptools" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:317 +msgid "uv-build" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:151 +#: ../source/specifications/pyproject-toml.rst:262 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "The new format for ``license`` is a valid :term:`SPDX license expression ` consisting of one or more :term:`license identifiers `. The full license list is available at the `SPDX license list page `_. The supported list version is 3.17 or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "If you get a build error that ``license`` should be a dict/table, your build backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is `described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "As a general rule, it is a good idea to use a standard, well-known license, both to avoid confusion and because some organizations avoid software whose license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "If your :term:`Distribution Archive` is licensed with a license that doesn't have an existing SPDX identifier, you can create a custom one in format ``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX specification, `clause 10.1 `_ of the version 2.2 or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:298 +#: ../source/specifications/pyproject-toml.rst:653 +msgid "``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "This is a list of license files and files containing other legal information you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots (``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "Special characters: ``*``, ``?``, ``**`` and character ranges: [] are supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "Patterns are relative to the directory containing :file:`pyproject.toml`, and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "Literal paths are valid globs. Any characters or character sequences not covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:381 +#: ../source/specifications/pyproject-toml.rst:652 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "This will help PyPI's search box to suggest your project when people search for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:393 +#: ../source/specifications/pyproject-toml.rst:646 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "A list of PyPI classifiers that apply to your project. Check the `full list of possibilities `_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "Although the list of classifiers is often used to declare what Python versions a project supports, this information is only used for searching and browsing projects on PyPI, not for installing projects. To actually restrict what Python versions a project can be installed on, use the :ref:`requires-python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "To prevent a package from being uploaded to PyPI, use the special ``Private :: Do Not Upload`` classifier. PyPI will always reject packages with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:159 +#: ../source/specifications/pyproject-toml.rst:411 +#: ../source/specifications/pyproject-toml.rst:657 +msgid "``urls``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "A list of URLs associated with your project, displayed on the left sidebar of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "See :ref:`well-known-labels` for a listing of labels that PyPI and other packaging tools are specifically aware of, and `PyPI's project metadata docs `_ for PyPI-specific URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "Note that if the label contains spaces, it needs to be quoted, e.g., ``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "Users are advised to use :ref:`well-known-labels` for their project URLs where appropriate, since consumers of metadata (like package indices) can specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "For example in the following metadata, neither ``MyHomepage`` nor ``\"Download Link\"`` is a well-known label, so they will be rendered verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known equivalents (``homepage`` and ``download``), and can be presented with those semantics in mind (the project's home page and its external download location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "Some packages can be extended through plugins. Examples include Pytest_ and Pygments_. To create such a plugin, you need to declare it in a subtable of ``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "Think twice before applying an upper bound like ``requires-python = \"<= 3.10\"`` here. `This blog post `_ contains some information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "flit-core `does not yet `_ support WITH in SPDX license expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "The Python Packaging User Guide (PyPUG) is a collection of tutorials and guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 +#: ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "This guide is maintained on `GitHub`_ by the :doc:`Python Packaging Authority `. We happily accept :doc:`contributions and feedback `. 😊" +msgstr "" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "To get an overview of the workflow used to publish your code, see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "The :doc:`guides/index` section provides \"how to\" instructions in three major areas: package installation; building and distributing packages; miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "The :doc:`discussions/index` section provides in-depth explanations and discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "" + +#: ../source/index.rst:91 +msgid "The :doc:`specifications/index` section for packaging interoperability specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "The list of :doc:`other projects ` maintained by members of the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "" + +#: ../source/key_projects.rst:8 +msgid "Summaries and links for the most relevant projects in the space of Python installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "" + +#: ../source/key_projects.rst:21 +msgid "`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "" + +#: ../source/key_projects.rst:39 +msgid ":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:44 +msgid "``build`` is a :pep:`517` compatible Python package builder. It provides a CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "" + +#: ../source/key_projects.rst:53 +msgid "`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | `Discussions `__ | `Discord #cibuildwheel `__" +msgstr "" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "" + +#: ../source/key_projects.rst:68 +msgid ":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "" + +#: ../source/key_projects.rst:118 +msgid "`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "" + +#: ../source/key_projects.rst:144 +msgid "`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "" + +#: ../source/key_projects.rst:159 +msgid ":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:164 +msgid "Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "" + +#: ../source/key_projects.rst:188 +msgid "`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:193 +msgid "The most popular tool for installing Python packages, and the one included with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "" + +#: ../source/key_projects.rst:206 +msgid ":doc:`Docs ` | `Source `__ | `Issues `__ | `PyPI `__" +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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "" + +#: ../source/key_projects.rst:238 +msgid "`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid ":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "" + +#: ../source/key_projects.rst:260 +msgid "`GitHub and docs `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "" + +#: ../source/key_projects.rst:276 +msgid "`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:281 +msgid "Setuptools (which includes ``easy_install``) is a collection of enhancements to the Python distutils that allow you to more easily build and distribute Python :term:`distributions `, especially ones that have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "" + +#: ../source/key_projects.rst:291 +msgid "`Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "" + +#: ../source/key_projects.rst:316 +msgid "`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:331 +#: ../source/overview.rst:405 +msgid "virtualenv" +msgstr "" + +#: ../source/key_projects.rst:333 +msgid "`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "" + +#: ../source/key_projects.rst:352 +msgid "`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "" + +#: ../source/key_projects.rst:366 +msgid "`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "" + +#: ../source/key_projects.rst:391 +msgid "`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "Conda is a package, dependency, and environment management system for any language — Python, R, Ruby, C/C++, Fortran, and more. It is written in Python and widely used in the Python scientific computing community, due to its support for non-Python compiled libraries and extensions. It is used as the basis of the `Anaconda `__ Python distribution from Anaconda, Inc. It was originally aimed at the scientific community, but can also be used on its own, or with the :doc:`miniconda `, `miniforge `_ or `pixi `_ systems. It is available for Windows, Mac and Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, but provides many of their combined features, such as package management, virtual environment management and deployment of binary extensions and other binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "Conda does not install packages from PyPI -- it can only manage packages built specifically for conda, which can be made available on a \"conda channel\", such as those hosted on `anaconda.org `__, or a local (e.g. intranet) package server. In addition to the \"default\" channels managed by `Anaconda, Inc. `__, there are a wide variety of packages from the community supported `conda-forge project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "Note that :ref:`pip` can be installed into, and work side-by-side with conda for managing :term:`distributions ` from PyPI. It is also possible to build conda packages from Python source packages using tools such as `conda skeleton `__: a tool to automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "" + +#: ../source/key_projects.rst:437 +msgid "`Docs `__ | :gh:`Issues ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "" + +#: ../source/key_projects.rst:466 +msgid ":gh:`Source ` | :gh:`Issues ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 +#: ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "Flask-Pypi-Proxy is a :term:`package index ` as a cached proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "" + +#: ../source/key_projects.rst:501 +msgid "`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:521 +msgid "Maturin is a build backend for Rust extension modules, also written in Rust. It supports building wheels for python 3.7+ on Windows, Linux, macOS and FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "" + +#: ../source/key_projects.rst:531 +msgid "`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:548 +msgid "Multibuild is a set of CI scripts for building and testing Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "nginx_pypi_cache is a :term:`package index ` caching proxy using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:570 +msgid "PDM is a modern Python package manager. It uses :term:`pyproject.toml` to store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "" + +#: ../source/key_projects.rst:596 +msgid "`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid ":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "pip2pi is a :term:`package index ` server where specific packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "" + +#: ../source/key_projects.rst:625 +msgid "`Website `__ | :doc:`Docs ` | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "" + +#: ../source/key_projects.rst:640 +msgid "`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid ":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "proxpi is a simple :term:`package index ` which proxies PyPI and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "" + +#: ../source/key_projects.rst:667 +msgid "`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "" + +#: ../source/key_projects.rst:697 +msgid ":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "" + +#: ../source/key_projects.rst:708 +msgid "`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid ":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "pywharf is a :term:`package index ` server, serving files locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "" + +#: ../source/key_projects.rst:754 +msgid "`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "" + +#: ../source/key_projects.rst:771 +msgid "`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "" + +#: ../source/key_projects.rst:787 +msgid "`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid ":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid ":doc:`Docs ` | `GitHub `__ | `Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "Spack is not in PyPI (yet), but it requires no installation and can be used immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "uv" +msgstr "" + +#: ../source/key_projects.rst:835 +msgid "`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:839 +msgid "A Python package and project manager, written in Rust for high performance. It supports creating and managing virtual environments, installing packages, locking dependencies, and managing Python versions and projects." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "zest.releaser" +msgstr "" + +#: ../source/key_projects.rst:848 +msgid "`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:852 +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." +msgstr "" + +#: ../source/key_projects.rst:859 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "ensurepip" +msgstr "" + +#: ../source/key_projects.rst:866 +msgid "`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:869 +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." +msgstr "" + +#: ../source/key_projects.rst:877 +msgid "http.server" +msgstr "" + +#: ../source/key_projects.rst:879 +msgid ":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:882 +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`)." +msgstr "" + +#: ../source/key_projects.rst:889 +msgid "venv" +msgstr "" + +#: ../source/key_projects.rst:891 +msgid "`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:894 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "" + +#: ../source/news.rst:4 +msgid "This document is not currently updated. Previously, the document highlighted changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "" + +#: ../source/news.rst:35 +msgid "Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "" + +#: ../source/news.rst:45 +msgid "Elaborate upon the differences between the tutorial and the real packaging process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "" + +#: ../source/news.rst:130 +msgid "Added python3-venv and python3-pip to Debian installation instructions. (:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "" + +#: ../source/news.rst:145 +msgid "Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "" + +#: ../source/news.rst:153 +msgid "Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "Updated the *Single Sourcing Package Version* tutorial to reflect pip's current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "Added documentation about the ``py_modules`` argument to ``setup``. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "" + +#: ../source/news.rst:162 +msgid "Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "Created a new guide for managing packages using ``pip`` and ``virtualenv``. (:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "" + +#: ../source/news.rst:169 +msgid "Encouraged using ``readme_renderer`` to validate :file:`README.rst`. (:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "" + +#: ../source/news.rst:176 +msgid "Added a new, experimental tutorial on installing packages using ``Pipenv``. (:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "Updated this guide's ``readme`` with instructions on how to build the guide locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "Made the new ``TestPyPI`` URL more visible, adding note to homepage about pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "Added a note about PyPI migration in the *Tool Recommendations* tutorial. (:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "" + +#: ../source/news.rst:206 +msgid "Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "Documented ``pip`` and ``easy_install``'s differences for per-project indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "Mentioned the requirement of the ``wheel`` package for creating wheels (:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "Removed the ``twine register`` reference in the *Distributing Packages* tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "Added documentation explaining prominently how to install ``pip`` in ``/usr/local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "Updated development mode documentation to mention that order of local packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "Swapped order of :file:`setup.py` arguments for the upload command, as order is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "Explained how to install from unsupported sources using a helper application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 `." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "Python's recommended built-in library and tool packaging technologies. Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +msgid "`Kivy `_" +msgstr "" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid ":doc:`zipapp ` (does not help manage dependencies, requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "A similar model involves installing an alternative Python distribution, but does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "`pyInstaller `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "`constructor `_ - For command-line installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "Most of the above imply single-user deployments. For multi-component server applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "These techniques are mostly Python agnostic, because they package whole OS filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "Adoption is most extensive among Linux servers, where the technology originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "`VHD `_, `AMI `_, and :doc:`other formats `" +msgstr "" + +#: ../source/overview.rst:356 +msgid "`OpenStack `_ - A cloud management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "In most deployment pipelines, the OS package manager is just one piece of the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "" + +#: ../source/overview.rst:423 +msgid "The further down the gradient you come, the harder it gets to update components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "This page specifies the binary distribution format for Python packages, also called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "A wheel is a ZIP-format archive with a specially formatted file name and the ``.whl`` extension. It contains a single distribution nearly as it would be 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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "Check that installer is compatible with Wheel-Version. Warn if minor version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "Move each subtree of ``distribution-1.0.data/`` onto its destination path. Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of destination directories, such as ``distribution-1.0.data/(purelib|platlib|headers|scripts|data)``. These subdirectories are :ref:`installation paths defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "If applicable, update scripts starting with ``#!python`` to point to the correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "Compile any installed .py to .pyc. (Uninstallers should be smart enough to remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "In wheel, scripts packaged on Unix systems will certainly not have accompanying .exe wrappers. Windows installers may want to add them during install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "Archivers are encouraged to place the ``.dist-info`` files physically at the end of the archive. This enables some potentially interesting ZIP tricks including the ability to amend the metadata without rewriting the entire archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "A common use-case for build numbers is rebuilding a binary distribution due to a change in the build environment, like when using the manylinux image to build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "Build numbers are not a part of the distribution version and thus are difficult to reference externally, especially so outside the Python ecosystem of tools and standards. A common case where a distribution would need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "Due to this limitation, new distributions which need to be referenced externally **should not** use build numbers when building the new distribution. Instead a **new distribution version** should be created for such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "Version numbers should be normalised according to the :ref:`Version specifier specification `. Normalised version numbers cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "The remaining components may not contain ``-`` characters, so no escaping is necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "The archive filename is Unicode. It will be some time before the tools are updated to support non-ASCII filenames, but they are supported in this specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "The filenames *inside* the archive are encoded as UTF-8. Although some ZIP clients in common use do not properly display UTF-8 filenames, the encoding is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "The contents of a wheel file, where {distribution} is replaced with the :ref:`normalized name ` of the package, e.g. ``beaglevote`` and {version} is replaced with its :ref:`normalized version `, e.g. ``1.0.0``, (with dash/``-`` characters replaced with underscore/``_`` characters in both fields) consist of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "``/``, the root of the archive, contains all files to be installed in ``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and ``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid ":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The ``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "``Generator`` is the name and optionally the version of the software that produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "``Root-Is-Purelib`` is true if the top level directory of the archive should be installed into purelib; otherwise the root should be installed into platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "A wheel installer should warn if Wheel-Version is greater than the version it supports, and must fail if Wheel-Version has a greater major version than the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "Wheel .dist-info directories include at a minimum METADATA, WHEEL, and RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "RECORD.jws and RECORD.p7s are deprecated. Where they are still used, neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends and other tools must not add them to wheels anymore, installers should be aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "During extraction, wheel installers verify all the hashes in RECORD against the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, installation will fail if any file in the archive is not both mentioned and correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "Subdirectories under :file:`.dist-info/` are reserved for future use. The following subdirectory names under :file:`.dist-info/` are reserved for specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "Subdirectory name" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +msgid "``licenses``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "If the metadata version is 2.4 or greater and one or more ``License-File`` fields is specified, the :file:`.dist-info/` directory MUST contain a :file:`licenses/` subdirectory, which MUST contain the files listed in the ``License-File`` fields in the :file:`METADATA` file at their respective paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:284 +msgid "All files contained within the :file:`.dist-info/sboms/` directory MUST be Software Bill-of-Materials (SBOM) files that describe software contained within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:291 +msgid "Any file that is not normally installed inside site-packages goes into the .data directory, named as the .dist-info directory but with the .data/ extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:299 +msgid "The .data directory contains subdirectories with the scripts, headers, documentation and so forth from the distribution. During installation the contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:305 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:311 +msgid "This specification does not have an opinion on how you should organize your code. The .data directory is just a place for any files that are not normally installed inside ``site-packages`` or on the PYTHONPATH. In other words, you may continue to use ``pkgutil.get_data(package, resource)`` even though *those* files will usually not be distributed in *wheel's* ``.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:322 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:327 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:332 +msgid "In practice a wheel should have only one of \"purelib\" or \"platlib\" depending on whether it is pure Python or not and those files should be at the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:348 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:357 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:374 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:382 +#: ../source/specifications/core-metadata.rst:1043 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:680 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../source/specifications/direct-url.rst:67 +#: ../source/specifications/entry-points.rst:163 +#: ../source/specifications/externally-managed-environments.rst:472 +#: ../source/specifications/glob-patterns.rst:118 +#: ../source/specifications/inline-script-metadata.rst:224 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:841 +#: ../source/specifications/pyproject-toml.rst:692 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:983 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:384 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:385 +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:387 +msgid "December 2024: Clarified that the ``scripts`` folder should only contain regular files (the expected behaviour of consuming tools when encountering symlinks or subdirectories in this folder is not formally defined, and hence may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "December 2024: The :file:`.dist-info/licenses/` directory was specified through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2025: Clarified that name and version needs to be normalized for ``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:395 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Appendix" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:401 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "The ``build-details.json`` file is a standardized file format that provides build-specfic information of a Python installation, such as its version, extension ABI details, and other information that is specific to that particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "Starting from Python 3.14, a ``build-details.json`` file is installed in the platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "Please refer to the :ref:`latest version ` for its specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:111 +#: ../source/specifications/pylock-toml.rst:737 +msgid "Example" +msgstr "" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:30 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "https://packaging.python.org/en/latest/specifications/schemas/build-details-v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*build-details.json — a static description file with build details of Python installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*object*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Schema version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This is a string following the format ``.``, where ```` and ```` are unpaded numbers and represent the **major** and **minor** components of the version. Versions may be arithmetically compared by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "For this specification version, this value is constant and **MUST** be ``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Future versions of this schema **MUST** use a higher version number. Future versions of this schema **MUST NOT** use the same **major** version component as other schema version unless its specification is deemed backwards-compatible with them — it can't change, or extend, any parts of the current specification in such a way as the semantics of the interpreted data differ, or that data valid under the new specification is invalid under the older specification, with the exception of additional properties (errors caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to directory where this file is contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "examples" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **MUST** be present if the installation provides an interpreter executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "String representation the Python language version — a version string consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "version\\_info" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*number*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**implementation**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It follows specification defined in PEP 421, meaning that on top of the required keys, implementation-specific keys can also exist, but must be prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`, containing the implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**flags**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The flags **MUST** be defined in the order they appear on the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **MUST** be present if the Python implementation supports extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **MUST** be present if the Python implementation has a stable ABI extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **MUST** be present if the Python installation supports importing external files, and it **SHOULD** be equivalent to the ``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Additionally, if a Python implementation provides extension kinds other than the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **MUST** by present if Python installation provides a ``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **MUST** be present if the Python installation provides a dynamic ``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **MUST** be present if the Python installation provides a dynamic ``libpython`` library targeting the Stable ABI, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **MUST** be present if the Python installation provides a static ``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **MUST** be present if the Python implementation provides a C API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**headers**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **MUST** be present if the Python implementation provides pkg-config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This is meant to be used as an escape-hatch, to include any relevant data that is not covered by this specification. Implementations may choose what data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.6, approved in May 2026." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "Fields defined in the following specification should be considered valid, complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", \"2.1\", \"2.2\", \"2.3\", \"2.4\", \"2.5\", and \"2.6\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "For broader compatibility, build tools MAY choose to produce distribution metadata using the lowest metadata version that includes all of the needed fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:184 +#: ../source/specifications/core-metadata.rst:199 +#: ../source/specifications/core-metadata.rst:237 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:317 +#: ../source/specifications/core-metadata.rst:321 +#: ../source/specifications/core-metadata.rst:353 +#: ../source/specifications/core-metadata.rst:375 +#: ../source/specifications/core-metadata.rst:393 +#: ../source/specifications/core-metadata.rst:418 +#: ../source/specifications/core-metadata.rst:440 +#: ../source/specifications/core-metadata.rst:666 +#: ../source/specifications/core-metadata.rst:701 +#: ../source/specifications/core-metadata.rst:711 +#: ../source/specifications/core-metadata.rst:940 +#: ../source/specifications/core-metadata.rst:1037 +msgid "Example::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "A string containing the distribution's version number. This field must be in the format specified in the :ref:`Version specifier specification `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:112 +msgid "A multiple use field that is present in the sdist and also marked ``Dynamic`` may only be appended to in a wheel built from the sdist. Previously any field listed in Dynamic was ignored in an sdist." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "A string containing the name of another core metadata field. The field names ``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:121 +msgid "When found in the metadata of a source distribution, the following rules apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:124 +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 "" + +#: ../source/specifications/core-metadata.rst:128 +msgid "If a single-use field is marked as ``Dynamic``, it may contain any valid value in a wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:130 +msgid "If a multiple use field is present in the sdist and also marked ``Dynamic``, then a wheel built from the sdist MUST include the value(s) present in the sdist. The wheel MAY add further values, but it MUST NOT remove, reorder, or modify the values present in the sdist." +msgstr "" + +#: ../source/specifications/core-metadata.rst:135 +msgid "If the sdist metadata version is older than version 2.2, then all fields should be treated as if they were specified with ``Dynamic`` (i.e. there are no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:139 +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 "" + +#: ../source/specifications/core-metadata.rst:144 +msgid "Note in particular that if you have obtained a prebuilt wheel, you cannot assume that a field which is not marked as ``Dynamic`` will have the same value in other wheels, as some wheels are not built directly from the sdist, but are modified from existing wheels (the ``auditwheel`` tool does this, for example, and it's commonly used when building wheels for PyPI). Such modifications *could* include changing metadata (even non-dynamic metadata). Similarly, if you have a sdist and a wheel which you didn't build from that sdist, you cannot assume that the wheel's metadata matches that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:154 +msgid "Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:163 +msgid "A Platform specification describing an operating system supported by the distribution which is not listed in the \"Operating System\" Trove classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:167 +#: ../source/specifications/core-metadata.rst:473 +#: ../source/specifications/core-metadata.rst:500 +#: ../source/specifications/core-metadata.rst:523 +#: ../source/specifications/core-metadata.rst:552 +#: ../source/specifications/core-metadata.rst:593 +#: ../source/specifications/core-metadata.rst:649 +#: ../source/specifications/core-metadata.rst:783 +#: ../source/specifications/core-metadata.rst:824 +#: ../source/specifications/core-metadata.rst:881 +#: ../source/specifications/core-metadata.rst:911 +#: ../source/specifications/core-metadata.rst:991 +#: ../source/specifications/core-metadata.rst:1013 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:175 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:179 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:193 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:197 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:220 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:225 +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 "" + +#: ../source/specifications/core-metadata.rst:231 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:248 +msgid "This encoding implies that any occurrences of a CRLF followed by 7 spaces and a pipe char have to be replaced by a single CRLF when the field is unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:252 +msgid "Alternatively, the distribution's description may instead be provided in the message body (i.e., after a completely blank line following the headers, with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:261 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:265 +msgid "A string stating the markup syntax (if any) used in the distribution's description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:268 +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 "" + +#: ../source/specifications/core-metadata.rst:281 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:287 +msgid "Format::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:291 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +msgid "``text/plain``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:294 +msgid "``text/x-rst``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:295 +msgid "``text/markdown``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:297 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:301 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:306 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:307 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "If a ``Description-Content-Type`` is not specified, then applications should attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to ``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "If a ``Description-Content-Type`` is an unrecognized value, then the assumed content type is ``text/plain`` (Although PyPI will probably reject anything with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:333 +msgid "If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is not specified or is set to an unrecognized value, then the assumed ``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:337 +msgid "So for the last example above, the ``charset`` defaults to ``UTF-8`` and the ``variant`` defaults to ``GFM`` and thus it is equivalent to the example before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:346 +msgid "Keywords" +msgstr "" + +#: ../source/specifications/core-metadata.rst:350 +msgid "A list of additional keywords, separated by commas, to be used to assist searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:359 +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 "" + +#: ../source/specifications/core-metadata.rst:368 +msgid "Author" +msgstr "" + +#: ../source/specifications/core-metadata.rst:372 +msgid "A string containing the author's name at a minimum; additional contact information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:385 +msgid "Author-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +msgid "A string containing the author's e-mail address. It can contain a name and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:397 +#: ../source/specifications/core-metadata.rst:444 +msgid "Per RFC-822, this field may contain multiple comma-separated e-mail addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:407 +msgid "Maintainer" +msgstr "" + +#: ../source/specifications/core-metadata.rst:411 +msgid "A string containing the maintainer's name at a minimum; additional contact information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:414 +msgid "Note that this field is intended for use when a project is being maintained by someone other than the original author: it should be omitted if it is identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "Maintainer-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:432 +msgid "A string containing the maintainer's e-mail address. It can contain a name and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:436 +msgid "Note that this field is intended for use when a project is being maintained by someone other than the original author: it should be omitted if it is identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:454 +msgid "License" +msgstr "" + +#: ../source/specifications/core-metadata.rst:457 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:461 +msgid "As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually exclusive. If both are specified, tools which parse metadata will disregard ``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:466 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:490 +msgid "Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:494 +msgid "Note that the expression in this field only applies to the :term:`Distribution Archive` containing the metadata with this field (e.g., :term:`Source Distribution ` or :term:`Wheel`), not the project overall or other files related to the project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:515 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:519 +msgid "Each entry is a string representation of the path of a license-related file. The path is located within the project source tree, relative to the project root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:536 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:540 +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 "" + +#: ../source/specifications/core-metadata.rst:546 +msgid "The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use ``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:550 +#: ../source/specifications/core-metadata.rst:640 +#: ../source/specifications/core-metadata.rst:879 +#: ../source/specifications/core-metadata.rst:904 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:561 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:564 +#: ../source/specifications/core-metadata.rst:627 +#: ../source/specifications/core-metadata.rst:851 +#: ../source/specifications/core-metadata.rst:893 +msgid "The field format specification was relaxed to accept the syntax used by popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:568 +msgid "Each entry contains a string naming some other distutils project required by this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:573 +msgid "A project name, in the same format as the ``Name:`` field. The only mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:575 +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 "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "A version specifier. Tools parsing the format should accept optional parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "An environment marker after a semicolon. This means that the requirement is only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:585 +msgid "The project names should correspond to names as found on the `Python Package Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:588 +msgid "Version specifiers must follow the rules described in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:591 +msgid "See :ref:`dependency-specifiers` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:608 +msgid "This field specifies the Python version(s) that the distribution is compatible with. Installation tools may look at this when picking which version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:612 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:614 +msgid "For example, if a distribution uses :ref:`f-strings ` then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:619 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:624 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:631 +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 "" + +#: ../source/specifications/core-metadata.rst:636 +msgid "The format of a requirement string is a name of an external dependency, optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:642 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:647 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:659 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:663 +msgid "A string containing a browsable URL for the project and a label for it, separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:670 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:672 +msgid "Starting with :pep:`753`, project metadata consumers (such as the Python Package Index) can use a standard normalization process to discover \"well-known\" labels, which can then be given special presentations when being rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:685 +msgid ":pep:`685` restricted valid values to be unambiguous (i.e. no normalization required). For older metadata versions, value restrictions were brought into line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:690 +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 "" + +#: ../source/specifications/core-metadata.rst:698 +msgid "The specified name may be used to make a dependency conditional on whether the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:706 +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/core-metadata.rst:716 +msgid "Two feature names ``test`` and ``doc`` are reserved to mark dependencies that are needed for running automated tests and generating documentation, respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:720 +msgid "It is legal to specify ``Provides-Extra:`` without referencing it in any ``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:723 +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 "" + +#: ../source/specifications/core-metadata.rst:728 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:738 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:742 +msgid "A string containing an import name that the project exclusively provides when installed. The specified import name MUST be a valid Python identifier or can be empty. The import names listed in this field MUST be importable when the project is installed on *some* platform for the same version of the project. This implies that the metadata MUST be consistent across all sdists and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:749 +#: ../source/specifications/core-metadata.rst:804 +msgid "An import name MAY be followed by a semicolon and the term \"private\" (e.g. ``; private``) with any amount of whitespace surrounding the semicolon. This signals to tools that the import name is not part of the public API for the project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +#: ../source/specifications/core-metadata.rst:809 +msgid "Projects SHOULD list all the shortest import names that are exclusively provided by the project. If any of the shortest names are dotted names, all intervening names from that name to the top-level name SHOULD also be listed appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:759 +#: ../source/specifications/core-metadata.rst:819 +msgid "If a project lists the same name in both ``Import-Name`` and ``Import-Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "Tools SHOULD raise an error when two projects that are about to be installed list names that overlap in each other's ``Import-Name`` entries, or when a project has an entry in ``Import-Name`` that overlaps with another project's ``Import-Namespace`` entries. This is to avoid projects unexpectedly shadowing another project's code. Tools MAY warn or raise an error when installing a project into a preexisting environment where there is import name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:770 +msgid "Projects MAY have an empty ``Import-Name`` field in their metadata to represent a project with no import names (i.e. there are no Python modules of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:774 +msgid "Since projects MAY have no ``Import-Name`` metadata (either because the project uses an older metadata version, or because it didn't specify any), then tools have no information about what names the project provides. However, in practice the majority of projects have their project name match what their import name would be. As such, it is a reasonable assumption to make that a project name that is normalized in some way to an import name (e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:794 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:798 +msgid "A string containing an import name that the project provides when installed, but not exclusively. The specified import name MUST be a valid Python identifier. This field is used for namespace packages where multiple projects can contribute to the same import namespace. Projects all listing the same import name in ``Import-Namespace`` can be installed together without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "The import names listed in this field MUST be importable when the project is installed on *some* platform for the same version of the project. This implies that the metadata MUST be consistent across all sdists and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:822 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:831 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:833 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:838 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:848 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:855 +msgid "Each entry contains a string naming a Distutils project which is contained within this distribution. This field *must* include the project identified in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:860 +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 "" + +#: ../source/specifications/core-metadata.rst:867 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:875 +msgid "A version declaration may be supplied and must follow the rules described in :doc:`version-specifiers`. The distribution's version number will be implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:890 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:897 +msgid "Each entry contains a string describing a distutils project's distribution which this distribution renders obsolete, meaning that the two projects should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:901 +msgid "Version declarations can be supplied. Version numbers must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:906 +msgid "The most common use of this field will be in case a project name changes, e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:919 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:921 +msgid "Deprecated fields should be avoided, but they are valid metadata fields. They may be removed in future versions of the core metadata standard (at which point they will only be valid in files that specify a metadata version prior to the removal). Tools SHOULD warn users when deprecated fields are used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:936 +#: ../source/specifications/core-metadata.rst:953 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:938 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:955 +msgid "A string containing the URL from which this version of the distribution can be downloaded. (This means that the URL can't be something like \"``.../BeagleVote-latest.tgz``\", but instead must be \"``.../BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:961 +msgid "Requires" +msgstr "" + +#: ../source/specifications/core-metadata.rst:964 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:967 +msgid "Each entry contains a string describing some other module or package required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:970 +msgid "The format of a requirement string is identical to that of a module or package name usable with the ``import`` statement, optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:982 +msgid "Any number of conditional operators can be specified, e.g. the string \">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:985 +msgid "All of the following are possible requirement strings: \"rfc822\", \"zlib (>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:988 +msgid "There’s no canonical list of what strings should be used; the Python community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1001 +msgid "Provides" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1004 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1007 +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 "" + +#: ../source/specifications/core-metadata.rst:1023 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1026 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1029 +msgid "Each entry contains a string describing a package or module that this package renders obsolete, meaning that the two packages should not be installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1033 +msgid "The most common use of this field will be in case a package name changes, e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1054 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1061 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1063 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1065 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1067 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1070 +msgid "August 2025: Clarified that ``Dynamic`` only affects how fields must be treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1074 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1077 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1079 +msgid "October 2025: Clarified that ``License-Expression`` applies to the containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1082 +#: ../source/specifications/pyproject-toml.rst:710 +msgid "January 2026: Replaced outdated direct reference to :pep:`508` with a reference to :ref:`dependency-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1085 +msgid "May 2026: Core metadata 2.6 was approved through :pep:`808`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1087 +msgid "Allowed a multiple use field marked ``Dynamic`` to be appended to in a wheel built from a sdist, requiring the wheel to preserve the value(s) present in the sdist." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1093 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1098 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "This specification defines dependency groups, a mechanism for storing package requirements in ``pyproject.toml`` files such that they are not included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "Dependency groups are suitable for internal development use-cases like linting and testing, as well as for projects which are not built for distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "Fundamentally, dependency groups should be thought of as being a standardized subset of the capabilities of ``requirements.txt`` files (which are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "and a similar table which defines ``docs``, ``test``, and ``coverage`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "Dependency groups are defined as a table in ``pyproject.toml`` named ``dependency-groups``. The ``dependency-groups`` table contains an arbitrary number of user-defined keys, each of which has, as its value, a list of requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "``[dependency-groups]`` keys, sometimes also called \"group names\", must be :ref:`valid non-normalized names `. Tools which handle Dependency Groups MUST :ref:`normalize ` these names before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "Tools SHOULD prefer to present the original, non-normalized name to users, and if duplicate names are detected after normalization, tools SHOULD emit an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "Requirement lists, the values in ``[dependency-groups]``, may contain strings, tables (``dict`` in Python), or a mix of strings and tables. Strings must be valid :ref:`dependency specifiers `, and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "A Dependency Group Include includes another Dependency Group in the current group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "An include is a table with exactly one key, ``\"include-group\"``, whose value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "Includes are defined to be exactly equivalent to the contents of the named Dependency Group, inserted into the current group at the location of the include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = [\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "Dependency Group Includes may specify the same package multiple times. Tools SHOULD NOT deduplicate or otherwise alter the list contents produced by the include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", \"foo<1.0\"]``. Tools should handle such a list exactly as they would handle any other case in which they are asked to process the same requirement multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "Dependency Group Includes may include groups containing Dependency Group Includes, in which case those includes should be expanded as well. Dependency Group Includes MUST NOT include cycles, and tools SHOULD report an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +msgid "Package Building" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "Build backends MUST NOT include Dependency Group data in built distributions as package metadata. This means that sdist ``PKG-INFO`` and wheel ``METADATA`` files should not include referenceable fields containing dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "It is, however, valid to use dependency groups in the evaluation of dynamic metadata, and ``pyproject.toml`` files included in sdists will still contain ``[dependency-groups]``. However, the table's contents are not part of a built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "There is no syntax or specification-defined interface for installing or referring to dependency groups. Tools are expected to provide dedicated interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "Tools MAY choose to provide the same or similar interfaces for interacting with dependency groups as they do for managing extras. Tools authors are advised that the specification does not forbid having an extra whose name matches a Dependency Group. Separately, users are advised to avoid creating dependency groups whose names match extras, and tools MAY treat such matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "Tools supporting dependency groups may want to validate data before using it. When implementing such validation, authors should be aware of the possibility of future extensions to the specification, so that they do not unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "Tools SHOULD error when evaluating or processing unrecognized data in dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "Tools SHOULD NOT eagerly validate the contents of *all* dependency groups unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "This means that in the presence of the following data, most tools should allow the ``foo`` group to be used and only error if the ``bar`` group is used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "There are several known cases of tools which have good cause to be stricter. Linters and validators are an example, as their purpose is to validate the contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:134 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "The following Reference Implementation prints the contents of a Dependency Group to stdout, newline delimited. The output is therefore valid ``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "This document defines the format used to specify dependencies on other projects. The language defined is a compact line based format which was adapted from the format originally used in ``pip`` requirements files." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:13 +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 on one platform, or only some versions are acceptable, so the language permits describing all these cases." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:19 +msgid "Whether tools should be strict or permissive in their processing of dependency specifiers is largely dependent on the role of the tool in the wider ecosystem:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:22 +msgid "publishing tools and index servers SHOULD be strict in their processing for new releases, encouraging the consistency of published specifiers to improve over time" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:25 +msgid "locking and installation tools MAY be permissive in their processing, allowing consumption of older packages which may contain dependency specifiers that are arguably nonsensical" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:35 +msgid "All features of the language shown with a name based lookup::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:39 +msgid "A minimal URL based lookup::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:44 +msgid "Concepts" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:46 +msgid "A dependency specification always specifies a distribution name. It may include extras, which expand the dependencies of the named distribution to enable optional features. The version installed can be controlled using version limits, or giving the URL to a specific artifact to install. Finally the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:53 +msgid "Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:55 +msgid "We first cover the grammar briefly and then drill into the semantics of each section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:58 +msgid "A distribution specification is written in ASCII text. We use a parsley [#parsley]_ grammar to provide a precise grammar. It is expected that the specification will be embedded into a larger system which offers framing such as comments, multiple line support via continuations, or other such features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:63 +msgid "The full grammar including annotations to build a useful parse tree is included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:66 +msgid "Versions may be specified according to the rules of the :ref:`Version specifier specification `. (Note: URI is defined in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:77 +msgid "Environment markers allow making a specification only take effect in some environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:106 +msgid "Optional components of a distribution may be specified using the extras field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:115 +msgid "Giving us a rule for name based requirements::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:119 +msgid "And a rule for direct reference specifications::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:123 +msgid "Leading to the unified rule that can specify a dependency.::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:128 +msgid "Whitespace" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:130 +msgid "Non line-breaking whitespace is mostly optional with no semantic meaning. The sole exceptions are detecting the end of a URL requirement and inside user supplied constants in environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:137 +msgid "Names" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:139 +msgid "Distribution names are defined in the :ref:`Core metadata `. 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." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:144 +msgid "Valid distribution names are defined in the :ref:`name format specification `." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:151 +msgid "Extras" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:153 +msgid "An extra is an optional part of a distribution. Distributions can specify as many extras as they wish, and each extra results in the declaration of additional dependencies of the distribution **when** the extra is used in a dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:160 +msgid "Extras union in the dependencies they define with the dependencies of the distribution they are attached to. The example above would result in requests being installed, and requests own dependencies, and also any dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:165 +msgid "If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:167 +msgid "Restrictions on names for extras are defined in the :ref:`Core metadata specification `. Publication tools SHOULD enforce these restrictions in dependency specifiers, while locking and installation tools MAY normalize invalid extra names in order to accept published metadata using core metadata versions prior to 2.3." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:176 +msgid "Versions" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:178 +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 comparisons are also used in environment markers. The optional brackets around a version are present for compatibility with :pep:`345` but should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:189 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +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 ``pywin32`` when running on Windows. This can be expressed as::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:197 +msgid "A marker expression evaluates to either True or False for a given deployment environment. When it evaluates to False, the dependency should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:200 +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." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:204 +msgid "Markers were first defined in :pep:`345`, formally specified in :pep:`508`, then subsequently amended over time (amendments since :pep:`508` are recorded :ref:`at the end of this specification `)." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:209 +msgid "Marker field types" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:211 +msgid "Environment marker fields are each defined as one of the following types:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "``String``: the contents of the field are always treated as an opaque string." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:214 +msgid "``Set of strings``: the contents of the field are always treated as a set containing opaque strings. In comparisons, the user supplied constant MUST still be a single string (as set literals are not part of the marker syntax)." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:217 +msgid "``Version``: the contents of the field are always expected to be a valid :ref:`version specifier `. Publishing tools SHOULD emit an error if that is not the case, but installation tools MAY fall back to treating the field as a string field." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:221 +msgid "``Version | String``: the contents of the field are expected to be a valid :ref:`version specifier ` on some platforms, but an opaque string on others. The specifics of this distinction are field dependent and whether or not tools actually make the distinction will be tool dependent." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:227 +msgid "Marker comparisons" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:229 +msgid "All marker comparison expressions are expected to compare a named marker field against a given user supplied constant. The type of the comparison is determined by the comparison operator used and the type of the named field as given in :ref:`the table below `. Tools MAY emit an error if no marker field is referenced in a comparison (that is, both operands are given as constants)." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:236 +msgid "The follow comparison operations are defined in the marker expression grammar:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:238 +msgid "``==`` (for example, ``sys_platform == \"win32\"``)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "``!=`` (for example, ``sys_platform != \"win32\"``)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:240 +msgid "``>`` (for example, ``python_version > \"3.10\"``)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:241 +msgid "``>=`` (for example, ``python_version >= \"3.10\"``)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:242 +msgid "``<`` (for example, ``python_version < \"3.10\"``)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:243 +msgid "``<=`` (for example, ``python_version <= \"3.10\"``)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:244 +msgid "``~=`` (for example, ``python_version ~= \"3\"``)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:245 +msgid "``===`` (for example, ``implementation_version === \"not.a.valid.version\"``)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:246 +msgid "``in`` (for example, ``\"gui\" in extras``, ``\"SMP\" in platform_version``)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "``not in`` (for example, ``\"dev\" not in dependency_groups``)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "For ``String`` fields, ``==``, ``!=``, ``in``, and ``not in`` are defined as they are for Python strings (case sensitive, with no value normalization of any kind). The use of ``~=`` or ``===`` with string fields is explicitly discouraged and publishing tools SHOULD emit an error, index servers MAY disallow uploads containing such environment markers, while locking and installation tools MAY instead interpret them as equivalent to ``==``. The use of ordered comparisons (``<``, ``<=``, ``>``, ``>=``) with string fields is explicitly discouraged (as it makes no semantic sense in the packaging context) and publishing tools SHOULD emit an error, index servers MAY disallow uploads containing such environment markers, while locking and installation tools SHOULD implement the following behavior:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid "treat ``>=`` and ``<=`` as equivalent to ``==``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:262 +msgid "treat ``>`` and ``<`` as always being False" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "For ``Set of String`` fields, as there is no marker syntax for set literals, the only valid operations are ``in`` and ``not in`` comparisons with a user supplied string literal as the left operand. Publishing tools SHOULD emit an error if environment markers attempt to use any other comparison operations on these fields and index servers MAY disallow uploads containing such environment markers, while locking and installation tools SHOULD treat such operations as always being False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "For ``Version`` fields, the comparison operations are defined by the :ref:`Version specifier specification ` when either both the marker field value and the user supplied constant can be parsed as valid version specifiers or the ``===`` arbitrary equivalence comparison operator is used. When an operator other than ``===`` is used, publishing tools SHOULD emit an error if the user supplied constant cannot be parsed as a valid version specifier, index servers MAY disallow uploads containing such environment markers, while locking and installation tools MAY either emit an error or else fall back to ``String`` field comparison logic if either the marker field value or the user supplied constant cannot be parsed as a valid version specifier. Note that ``in`` and ``not in`` containment checks are NOT valid for ``Version`` fields and publishing tools SHOULD emit an error, index servers MAY disallow uploads containing such environment markers, while locking and installation tools MAY treat them as always being False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid "For ``Version | String`` fields, comparison operations are defined as they are for ``Version`` fields, while ``in`` and ``not in`` containment checks are defined as they are for ``String`` fields. However, there is no consistent cross-platform expectation that the parsing of the marker field value or the user supplied constant as a valid version will succeed, so tools SHOULD fall back to processing the field as a ``String`` field if parsing either value as a version fails. Tools MAY emit a warning if the field is expected to contain a valid version on a given platform but does not in fact do so. Tools SHOULD NOT unconditionally treat such fields as ``String`` fields, as doing so may give incorrect answers for environment markers that are appropriately scoped to the relevant platforms before performing a version based comparison." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "Composing marker expressions" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:303 +msgid "More complex marker expressions may be composed using the ``and`` and ``or`` logical operators. Parentheses may be used as necessary to control operand precedence (with all comparison operations having a higher precedence)." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:313 +msgid "Python's comparison chaining (such as ``3.4 < python_version < 3.9``) is NOT supported in environment markers (such expressions must instead be written out as two separate comparisons joined by ``and``)." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:318 +msgid "User supplied constants" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:320 +msgid "User supplied constants are always given as strings within either ``'`` or ``\"`` quote marks. Triple-quoted multi-line strings are NOT permitted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:323 +msgid "Backslash escapes are not specified, although tools MAY support them. They are not included in the specification because they add complexity and there is currently no known need for treating user supplied constants as anything other than either opaque strings or valid version specifiers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:328 +msgid "Similarly, non-ASCII character support is not specified, but tools MAY accept them (usually based on the text encoding of the file or stream containing the dependency specifier). This may be revisited in the future if it becomes more common for the runtime variables typically referenced in environment markers to contain non-ASCII text that users wish to perform comparisons against." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:335 +msgid "Unknown marker fields" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "References to unknown marker fields SHOULD render a package version ineligible for installation or inclusion in a locked dependency tree rather than resulting in a comparison that evaluates to True or False. This is so that published package versions with unknown marker fields are either ignored when resolving dependencies or emit a descriptive installation failure, rather than producing an apparently successful installation that then fails at runtime due to missing dependencies (if the unknown marker is treated as False) or a potentially cryptic installation failure of a dependency that is not valid for the current platform (if the unknown marker is treated as True)." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:347 +msgid "Variables whose value cannot be calculated on a given Python implementation should evaluate to ``0`` for ``Version`` fields, and an empty string for all other variables (including ``Version | String`` fields)." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:355 +msgid "Defined environment marker fields" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:357 +msgid "Unless otherwise noted below, marker evaluation environments MUST support all of the following marker fields:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:363 +msgid "Marker" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:364 +msgid "Python equivalent" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:365 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:366 +msgid "Sample values & notes" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:367 +msgid "``os_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:368 +msgid ":py:data:`os.name`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:369 +#: ../source/specifications/dependency-specifiers.rst:373 +#: ../source/specifications/dependency-specifiers.rst:379 +#: ../source/specifications/dependency-specifiers.rst:385 +#: ../source/specifications/dependency-specifiers.rst:394 +#: ../source/specifications/dependency-specifiers.rst:414 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:370 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:371 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:372 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:374 +msgid "``linux``, ``win32``, ``darwin``, ``java1.8.0_51`` (note that this is the most well defined field for use when declaring platform specific dependencies)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:377 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:378 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:380 +msgid "``x86_64``, ``aarch64``, ``AMD64``, ``arm64`` (note that this value is provided by the operating system, so the same CPU architecture may use different strings on different platforms)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:383 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:384 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:386 +msgid "``CPython``, ``PyPy``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:387 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:388 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:389 +#: ../source/specifications/dependency-specifiers.rst:398 +msgid "Version | String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:390 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51`` (may be a valid version field, for example on macOS/darwin)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:392 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:393 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:395 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:396 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:397 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:399 +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`` ``13`` (may be a valid version field, for example on iOS or Android)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:404 +msgid "``python_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:405 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:406 +#: ../source/specifications/dependency-specifiers.rst:410 +#: ../source/specifications/dependency-specifiers.rst:418 +msgid ":ref:`Version `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:407 +msgid "``3.9``, ``3.15``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:408 +msgid "``python_full_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:409 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:411 +msgid "``3.10.12``, ``3.15.0a1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:412 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:413 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:415 +msgid "``cpython``, ``pypy``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:416 +msgid "``implementation_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:417 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:419 +msgid "``3.10.12``, ``7.3.17`` (examples are for CPython and PyPy respectively)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:421 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:422 +msgid "Used to indicate optional dependencies in project dependency metadata. An error except when defined by the context interpreting the specifier." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:425 +msgid "Special (see below)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:426 +msgid "``toml`` (publishing tools SHOULD permit use of this field)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:428 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:429 +msgid "Used to indicate optional public dependencies in lock files. An error except when defined by the context interpreting the specifier." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:431 +#: ../source/specifications/dependency-specifiers.rst:439 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:432 +msgid "``{\"toml\"}`` (publishing tools SHOULD NOT permit use of this field and index servers SHOULD NOT accept uploads containing such environment markers)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:435 +msgid "``dependency_groups``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:436 +msgid "Used to indicate optional project internal dependencies in lock files. An error except when defined by the context interpreting the specifier." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:440 +msgid "``{\"test\"}`` (publishing tools SHOULD NOT permit use of this field and index servers SHOULD NOT accept uploads containing such environment markers)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:444 +msgid "For backwards compatibility with older locking and installation tools, the ``extras`` and ``dependency_groups`` fields are currently only valid for use in ``packages.marker`` fields in :ref:`lock files `. For these comparisons, the ``extras`` and ``dependency_groups`` sets used for the marker evaluation refer to the *currently selected* extras and dependency groups when installing from the lock file, not the full set of defined extras and dependency groups listed in the corresponding top level lock file fields. The interface for selecting which extras and dependency groups to install is tool dependent. Publishing tools SHOULD emit an error if projects attempt to reference the ``extras`` or ``dependency_groups`` fields in their published dependency declaration metadata, and index servers SHOULD NOT accept uploads referencing these fields. Outside lock file processing, marker evaluation environments DO NOT need to define these fields." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:458 +msgid "The ``extra`` field is also special, as it expects set-like behaviour, but predates the addition of ``Set of strings`` as a defined marker field type. Accordingly, ``extra == \"name\"`` in a dependency declaration is similar to ``\"name\" in extras``, while ``extra != \"name\"`` is similar to ``\"name\" not in extras``. For dependency marker evaluations, the set of extra names used for these comparisons is the full set of requested extras for *that particular package*, whether requested directly in a top level dependency declaration, or indirectly in a transitive dependency declaration. Other comparison operations on ``extra`` are not defined and publishing tools SHOULD emit an error, index servers MAY disallow uploads containing such environment markers, while locking and installation tools SHOULD evaluate them as False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:470 +msgid "Unlike the newer ``extras`` field, environment markers using this field SHOULD be accepted by both publishing tools and index servers. Marker evaluation environments intended for project dependency declarations will typically need to handle evaluation of ``extra`` field comparisons, while other evaluations of environment markers will not generally need to do so. The legacy ``extra`` comparison syntax is NOT permitted in lock file ``packages.marker`` fields, and installation tools SHOULD reject lock files containing such comparisons as invalid." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:479 +msgid "The ``implementation_version`` marker variable is derived from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:499 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:501 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:608 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:682 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:683 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:688 +msgid "March 2022: Standardised the normalization of extra names at publication time (for core metadata 2.3 and later) through :pep:`685`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:690 +msgid "June 2024: The definition of ``version_many`` was changed to allow trailing commas, matching with the behavior of the Python implementation that has been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:693 +msgid "April 2025: Added ``extras`` and ``dependency_groups`` marker field for :ref:`lock-file-spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:695 +#: ../source/specifications/name-normalization.rst:56 +msgid "August 2025: The suggested name validation regex was fixed to match the field specification (it previously finished with ``$`` instead of ``\\Z``, incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:698 +msgid "December 2025: Ensure ``===`` is before ``==`` in grammar, to allow arbitrary equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:700 +msgid "January 2026: Amend the definition of environment marker comparison operations to restrict version comparison semantics to fields where they make sense, make extra name restrictions more explicit, adjust the way ordered comparisons are defined for strings, and make the fallback from version comparisons to string comparisons when version parsing fails optional. Also provide different tool behaviour recommendations for publishing tools vs installation tools. This brought the nominal specification into line with the way tools actually work. [#marker_comparison_logic]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:708 +msgid "January 2026: fix outdated references to other documents that were inadvertently retained from :pep:`508`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:715 +msgid "pip, the recommended installer for Python packages (http://pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:718 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:721 +msgid "Future Python versions might be problematic with the definition of Environment Marker Variable ``python_version`` (https://github.com/python/peps/issues/560)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:725 +msgid "Resolving inconsistencies between actual tool behavior and the nominal definitions of environment marker field comparisons (https://discuss.python.org/t/spec-change-bugfix-dependency-specifiers-simplification-pep-508/105203)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "This document specifies a :file:`direct_url.json` file in the ``*.dist-info`` directory of an installed distribution, to record the Direct URL Origin of the distribution. The general structure and usage of ``*.dist-info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` directory by installers when installing a distribution from a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "This file MUST NOT be created when installing a distribution from an other type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "When the requested URL has the file:// scheme and points to a local directory that happens to contain a VCS checkout, installers MUST NOT attempt to infer any VCS information and therefore MUST NOT output any VCS related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "As a general rule, installers should as much as possible preserve the information that was provided in the requested URL when generating :file:`direct_url.json`. For example user:password environment variables should be preserved and ``requested_revision`` should reflect the revision that was provided in the requested URL as faithfully as possible. This information is however *enriched* with more precise data, such as ``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "``pip install \"app @ git+https://example.com/repo/app.git#subdirectory=setup\"``" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "``pip install --editable \"app @ git+https://example.com/repo/app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local directory where the git repository has been cloned to, and ``dir_info`` will be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "This document specifies a JSON-serializable abstract data structure that can represent URLs to python projects and distribution artifacts such as VCS source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 `." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "The Direct URL Data Structure MUST be a dictionary, serializable to JSON according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "When persisted, ``url`` MUST be stripped of any sensitive authentication information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "The user:password section of the URL MAY however be composed of environment variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "A ``vcs`` key (type ``string``) MUST be present, containing the name of the VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be registered by writing a PEP to amend this specification. The ``url`` value MUST be compatible with the corresponding VCS, so an installer can hand it off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "A ``requested_revision`` key (type ``string``) MAY be present naming a branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). This 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:70 +msgid "A ``commit_id`` key (type ``string``) MUST be present, containing the exact commit/revision number that was/is to be installed. If the VCS supports commit-hash based revision identifiers, such commit-hash MUST be used as ``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "When ``url`` refers to a source archive or a wheel, the ``archive_info`` key MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "A deprecated ``hash`` key (type ``string``) MAY be present for backwards compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "Producers of the data structure SHOULD emit the ``hashes`` key whether one or multiple hashes are available. Producers SHOULD continue to emit the ``hash`` key in contexts where they did so before, so as to keep backwards compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "When both the ``hash`` and ``hashes`` keys are present, the hash represented in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so consumers can consider the ``hashes`` key only if it is present, and fall back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "When ``url`` refers to a local directory, it MUST have the ``file`` scheme and be compliant with :rfc:`8089`. In particular, the path component must be absolute. Symbolic links SHOULD be preserved when making relative paths absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "This section lists the registered VCS's; expanded, VCS-specific information on how to use the ``vcs``, ``requested_revision``, and other fields of ``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY support other VCS's although it is RECOMMENDED to register them by writing a PEP to amend this specification. The ``vcs`` field SHOULD be the command name (lowercased). Additional fields that would be necessary to support such VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to determine if the ``requested_revision`` corresponds to a Git ref. In turn, a ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "The following JSON Schema can be used to validate the contents of ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "Applications can use entry points to load plugins; e.g. Pygments (a syntax highlighting tool) can use additional lexers and styles from separately installed packages. For more about this, see :doc:`/guides/creating-and-discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "The **group** that an entry point belongs to indicates what sort of object it provides. For instance, the group ``console_scripts`` is for entry points referring to functions which can be used as a command, while ``pygments.styles`` is the group for classes defining pygments styles. The consumer typically defines the expected interface. To avoid clashes, consumers defining a new group should use names starting with a PyPI name owned by the consumer project, followed by ``.``. Group names must be one or more groups of letters, numbers and underscores, separated by dots (regex ``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "The **name** identifies this entry point within its group. The precise meaning of this is up to the consumer. For console scripts, the name of the entry point is the command that will be used to launch it. Within a distribution, entry point names should be unique. If different distributions provide the same name, the consumer decides how to handle such conflicts. The name may contain any characters except ``=``, but it cannot start or end with any whitespace character, or start with ``[``. For new entry points, it is recommended to use only letters, numbers, underscores, dots and dashes (regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "The **object reference** points to a Python object. It is either in the form ``importable.module``, or ``importable.module:object.attr``. Each of the parts delimited by dots and the colon is a valid Python identifier. It is intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "There is also an optional property: the **extras** are a set of strings identifying optional features of the distribution providing the entry point. If these are specified, the entry point requires the dependencies of those 'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "Using extras for an entry point is no longer recommended. Consumers should support parsing them from existing distributions, but may then ignore them. New publishing tools need not support specifying extras. The functionality of handling extras was tied to setuptools' model of managing 'egg' packages, but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "Entry points are defined in a file called :file:`entry_points.txt` in the :file:`*.dist-info` directory of the distribution. This is the directory described in :ref:`recording-installed-packages` for installed distributions, and in :ref:`binary-distribution-format` for wheels. The file uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "The file contents are in INI format, as read by Python's :mod:`configparser` module. However, configparser treats names as case-insensitive by default, whereas entry point names are case sensitive. A case-sensitive config parser can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "The entry points file must always use ``=`` to delimit names from values (whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "The sections of the config file represent entry point groups, the names are names, and the values encode both the object reference and the optional extras. If extras are used, they are a comma-separated list inside square brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "Within a value, readers must accept and ignore spaces (including multiple consecutive spaces) before or after the colon, between the object reference and the left square bracket, between the extra names and the square brackets and colons delimiting them, and after the right square bracket. The syntax for extras is formally specified in :ref:`dependency-specifiers`. For tools writing the file, it is recommended only to insert a space between the object reference and the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:127 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:129 +msgid "Two groups of entry points have special significance in packaging: ``console_scripts`` and ``gui_scripts``. In both groups, the name of the entry point should be usable as a command in a system shell after the package is installed. The object reference points to a function which will be called with no arguments when this command is run. The function may return an integer to be used as a process exit code, and returning ``None`` is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:137 +msgid "For instance, the entry point ``mycmd = mymod:main`` would create a command ``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:144 +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 "" + +#: ../source/specifications/entry-points.rst:152 +msgid "Install tools are expected to set up wrappers for both ``console_scripts`` and ``gui_scripts`` in the scripts directory of the install scheme. They are not responsible for putting this directory in the ``PATH`` environment variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:157 +msgid "As files are created from the names, and some filesystems are case-insensitive, packages should avoid using names in these groups which differ only in case. The behaviour of install tools when names differ only in case is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:165 +msgid "October 2017: This specification was written to formalize the existing entry points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:168 +msgid "January 2026: Replaced outdated direct references to :pep:`508` and :pep:`685` with a reference to :ref:`dependency-specifiers`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "While some Python installations are entirely managed by the user that installed Python, others may be provided and managed by another means (such as the operating system package manager in a Linux distribution, or as a bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "Attempting to use conventional Python packaging tools to manipulate such environments can be confusing at best and outright break the entire underlying operating system at worst. Documentation and interoperability guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows a Python installation to indicate to Python-specific tools such as ``pip`` that they neither install nor remove packages into the interpreter’s default installation environment, and should instead guide the end user towards using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "It also standardizes an interpretation of the ``sysconfig`` schemes so that, if a Python-specific package manager is about to install a package in an interpreter-wide context, it can do so in a manner that will avoid conflicting with the external package manager and reduces the risk of breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "A few terms used in this specification have multiple meanings in the contexts that it spans. For clarity, this specification uses the following terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "Short for \"distribution,\" a collection of various sorts of software, ideally designed to work properly together, including (in contexts relevant to this document) the Python interpreter itself, software written in Python, and software written in other languages. That is, this is the sense used in phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "A distro can be an operating system (OS) of its own, such as Debian, Fedora, or FreeBSD. It can also be an overlay distribution that installs on top of an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "This document uses the short term \"distro,\" because the term \"distribution\" has another meaning in Python packaging contexts: a source or binary distribution package of a single piece of Python language software, that is, in the sense of ``setuptools.dist.Distribution`` or \"sdist\". To avoid confusion, this document does not use the plain term \"distribution\" at all. In the Python packaging sense, it uses the full phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "The provider of a distro - the team or company that collects and publishes the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "A unit of software that can be installed and used within Python. That is, this refers to what Python-specific packaging tools tend to call a :term:`distribution package` or simply a \"distribution\"; the colloquial abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "This document does not use \"package\" in the sense of an importable name that contains Python modules, though in many cases, a distribution package consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "This document generally does not use the term \"package\" to refer to units of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` files). When needed, it uses phrasing such as \"a distro's package.\" (Again, in many cases, a Python package is shipped inside a distro's package named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "A tool for installing, upgrading, and/or removing Python packages in a manner that conforms to Python packaging standards. The most popular Python-specific package manager is pip_; other examples include the old `Easy Install command `_ as well as direct usage of a ``setup.py`` command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "(Note that the ``easy_install`` command was removed in setuptools version 52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "(Conda_ is a bit of a special case, as the ``conda`` command can install much more than just Python packages, making it more like a distro package manager in some senses. Since the ``conda`` command generally only operates on Conda-created environments, most of the concerns in this document do not apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "A tool for installing, upgrading, and/or removing a distro's packages in an installed instance of that distro, which is capable of installing Python packages as well as non-Python packages, and therefore generally has its own database of installed software unrelated to the :ref:`database of installed distributions `. Examples include ``apt``, ``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is that if a package was installed by a distro package manager, removing or upgrading it in a way that would satisfy a Python-specific package manager will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "This document also uses phrases like \"external package manager\" or \"system's package manager\" to refer to a distro package manager in certain contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "To shadow an installed Python package is to cause some other package to be preferred for imports without removing any files from the shadowed package. This requires multiple entries on ``sys.path``: if package A 2.0 installs module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module ``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "First, it describes **a way for distributors of a Python interpreter to mark that interpreter as having its packages managed by means external to Python**, such that Python-specific tools like pip should not change the installed packages in the interpreter's global ``sys.path`` in any way (add, upgrade/downgrade, or remove) unless specifically overridden. It also provides a means for the distributor to indicate how to use a virtual environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "This is an opt-in mechanism: by default, the Python interpreter compiled from upstream sources will not be so marked, and so running ``pip install`` with a self-compiled interpreter, or with a distro that has not explicitly marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "Second, it sets the rule that when installing packages to an interpreter's global context (either to an unmarked interpreter, or if overriding the marking), **Python-specific package managers should modify or delete files only within the directories of the sysconfig scheme in which they would create files**. This permits a distributor of a Python interpreter to set up two directories, one for its own managed packages, and one for unmanaged packages installed by the end user, and ensure that installing unmanaged packages will not delete (or overwrite) files owned by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "Before a Python-specific package installer (that is, a tool such as pip - not an external tool such as apt) installs a package into a certain Python context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "Is it running outside of a virtual environment? It can determine this by whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by ``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "If both of these conditions are true, the installer should exit with an error message indicating that package installation into this Python interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "The installer should have a way for the user to override these rules, such as a command-line flag ``--break-system-packages``. This option should not be enabled by default and should carry some connotation that its use is risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be parsable by the standard library configparser_ module. If the file can be parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 encoding, and it contains a section ``[externally-managed]``, then the installer should look for an error message specified in the file and output it as part of its error. If the first element of the tuple returned by ``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not ``None``, it should look for the error message as the value of a key named ``Error-`` followed by the language code. If that key does not exist, and if the language code contains underscore or hyphen, it should look for a key named ``Error-`` followed by the portion of the language code before the underscore or hyphen. If it cannot find either of those, or if the language code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "If the installer cannot find an error message in the file (either because the file cannot be parsed or because no suitable error key exists), then the installer should just use a pre-defined error message of its own, which should suggest that the user create a virtual environment to install packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "which provides useful and distro-relevant information to a user trying to install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "In certain contexts, such as single-application container images that aren't updated after creation, a distributor may choose not to ship an ``EXTERNALLY-MANAGED`` file, so that users can install whatever they like (as they can today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "Usually, a Python package installer installs to directories in a scheme returned by the ``sysconfig`` standard library package. Ordinarily, this is the scheme returned by ``sysconfig.get_default_scheme()``, but based on configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "Whenever the installer is installing to a ``sysconfig`` scheme, this specification declares that the installer should never modify or delete files outside of that scheme. For instance, if it's upgrading a package, and the package is already installed in a directory outside that scheme (perhaps in a directory from another scheme), it should leave the existing files alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "If the installer does end up shadowing an existing installation during an upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "If the installer is installing to a location outside of a ``sysconfig`` scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "This section is non-normative. It provides best practices we believe distros should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "The file should contain a useful and distro-relevant error message indicating both how to install system-wide packages via the distro's package manager and how to set up a virtual environment. If your distro is often used by users in a state where the ``python3`` command is available (and especially where ``pip`` or ``get-pip`` is available) but ``python3 -m venv`` does not work, the message should indicate clearly how to make ``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "Consider packaging pipx_, a tool for installing Python-language applications, and suggesting it in the error. pipx automatically creates a virtual environment for that application alone, which is a much better default for end users who want to install some Python-language software (which isn't available in the distro) but are not themselves Python users. Packaging pipx in the distro avoids the irony of instructing users to ``pip install --user --break-system-packages pipx`` to *avoid* breaking system packages. Consider arranging things so your distro's package / environment for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "Distros that produce official images for single-application containers (e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, preferably in a way that makes it not go away if a user of that image installs package updates inside their image (think ``RUN apt-get dist-upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "Distros should place two separate paths on the system interpreter's ``sys.path``, one for distro-installed packages and one for packages installed by the local system administrator, and configure ``sysconfig.get_default_scheme()`` to point at the latter path. This ensures that tools like pip will not modify distro-installed packages. The path for the local system administrator should come before the distro path on ``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "For example, Fedora and Debian (and their derivatives) both implement this split by using ``/usr/local`` for locally-installed packages and ``/usr`` for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as an additional layer of separation from a locally-compiled Python interpreter: if you build and install upstream CPython in ``/usr/local/bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian wishes to make sure that packages installed via the locally-built interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the ``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` and non-distro software installs to ``/usr/local`` by default. This split is `recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "There are two ways you could do this. One is, if you are building and packaging Python libraries directly (e.g., your packaging helpers unpack a wheel or call ``setup.py install``), arrange for those tools to use a directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "The other is to arrange for the default ``sysconfig`` scheme to change when running inside a package build versus when running on an installed system. The ``sysconfig`` customization hooks from bpo-43976_ should make this easy (once accepted and implemented): make your packaging tool set an environment variable or some other detectable configuration, and define a ``get_preferred_schemes`` function to return a different scheme when called from inside a package build. Then you can use ``pip install`` as part of your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "We propose adding a ``--scheme=...`` option to instruct pip to run against a specific scheme. (See `Implementation Notes`_ below for how pip currently determines schemes.) Once that's available, for local testing and possibly for actual packaging, you would be able to run something like ``pip install --scheme=posix_distro`` to explicitly install a package into your distro's location (bypassing ``get_preferred_schemes``). One could also, if absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "The advantage of setting these up to be automatic (suppressing the marker file in your build environment and having ``get_preferred_schemes`` automatically return your distro's scheme) is that an unadorned ``pip install`` will work inside a package build, which generally means that an unmodified upstream build script that happens to internally call ``pip install`` will do the right thing. You can, of course, just ensure that your packaging process always calls ``pip install --scheme=posix_distro --break-system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "The best approach here depends a lot on your distro's conventions and mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "Similarly, the ``sysconfig`` paths that are not for importable Python code - that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should also have two variants, one for use by distro-packaged software and one for use for locally-installed software, and the distro should be set up such that both are usable. For instance, a typical FHS-compliant distro will use ``/usr/local/include`` for the default scheme's ``include`` and ``/usr/include`` for distro-packaged headers and place both on the compiler's search path, and it will use ``/usr/local/bin`` for the default scheme's ``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "This section is non-normative and contains notes relevant to both the specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "Currently (as of May 2021), pip does not directly expose a way to choose a target ``sysconfig`` scheme, but it has three ways of looking up schemes when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream CPython and most current distros) the same as ``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "Finally, ``pip install --target=/some/path`` writes directly to ``/some/path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "Debian currently carries a `patch to change the default install location inside a virtual environment`__, using a few heuristics (including checking for the ``VIRTUAL_ENV`` environment variable), largely so that the directory used in a virtual environment remains ``site-packages`` and not ``dist-packages``. This does not particularly affect this proposal, because the implementation of that patch does not actually change the default ``sysconfig`` scheme, and notably does not change the result of ``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "Fedora currently carries a `patch to change the default install location when not running inside rpmbuild`__, which they use to implement the two-system-wide-directories approach. This is conceptually the sort of hook envisioned by bpo-43976_, except implemented as a code patch to ``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "The implementation of ``is_virtual_environment`` above, as well as the logic to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, may as well get added to the standard library (``sys`` and ``sysconfig``, respectively), to centralize their implementations, but they don't need to be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid ":pep:`592` includes changes to the HTML and JSON index APIs. These changes are documented in the :ref:`simple-repository-api` under :ref:`HTML - Project Detail ` and :ref:`JSON - Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +msgid "Installers" +msgstr "" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "They may choose to include yanked files, and additionally mirror the ``data-yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files `, accept certain types of *glob patterns* to match a given string containing wildcards and character ranges against files and directories. This specification defines which patterns are acceptable and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "For PyPA purposes, a *valid glob pattern* MUST be a string matched against filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "Alphanumeric characters, spaces (`` ``), underscores (``_``), hyphens (``-``), and dots (``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` containing only the verbatim matched characters MUST be supported. Within ``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order based on Unicode code points). Hyphens at the start or end are matched literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "Patterns always refer to *relative paths*, e.g., when used in :file:`pyproject.toml`, patterns should always be relative to the directory containing that file. Therefore the leading slash character MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "Any characters or character sequences not covered by this specification are invalid. Projects MUST NOT use such values. Tools consuming glob patterns SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "MUST treat each value as a glob pattern, and MUST raise an error if the pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "MUST raise an error if any individual user-specified pattern does not match at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +msgid "Reference implementation in Python" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "It is possible to defer the majority of the pattern matching against the file system to the :mod:`glob` module in Python's standard library. It is necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:120 +msgid "January 2025: Initial version" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:121 +msgid "March 2026: Treat spaces as a verbatim character" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 +msgid "This is a list of currently active interoperability specifications maintained by the Python Packaging Authority. The process for updating these standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid ":pep:`740` includes changes to the HTML and JSON index APIs. These changes are documented in the :ref:`simple-repository-api` under :ref:`simple-repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "The \"legacy\" upload API is not standardized. See `PyPI's Upload API documentation `_ for how attestations are uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "An attestation object is a JSON object with several required keys; applications or signers may include additional keys so long as all explicitly listed keys are provided. The required layout of an attestation object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "A full data model for each object in ``transparency_entries`` is provided in :ref:`appendix`. Attestation objects **SHOULD** include one or more transparency log entries, and **MAY** include additional keys for other sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a `Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "Attestation objects are versioned; this PEP specifies version 1. Each version is tied to a single cryptographic suite to minimize unnecessary cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "Certificates are specified as X.509 certificates, and comply with the profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "The message signature algorithm is ECDSA, with the P-256 curve for public keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "Future PEPs may change this suite (and the overall shape of the attestation object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "The *attestation statement* is the actual claim that is cryptographically signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "The attestation statement is encoded as a `v1 in-toto Statement object `__, in JSON form. When serialized the statement is treated as an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "In addition to being a v1 in-toto Statement, the attestation statement is constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "``subject[0].name`` is the distribution's filename, which **MUST** be a valid :ref:`source distribution ` or :ref:`wheel distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests **MAY** be present. The digests **MUST** be represented as hexadecimal strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "`SLSA Provenance `__: ``https://slsa.dev/provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "The signature over this statement is constructed using the `v1 DSSE signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other ``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "The index will serve uploaded attestations along with metadata that can assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "These *provenance objects* will be available via both the Simple Index and JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "``version`` is ``1``. Like attestation objects, provenance objects are versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "``attestation_bundles`` is a **required** JSON array, containing one or more \"bundles\" of attestations. Each bundle corresponds to a signing identity (such as a Trusted Publishing identity), and contains one or more attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "A ``claims`` key, which **MUST** be a JSON object containing any context-specific claims retained by the index during Trusted Publisher authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "Each array of attestation objects is a superset of the ``attestations`` array supplied by the uploaded through the ``attestations`` field at upload time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "Provenance objects are *not* immutable, and may change over time. Reasons for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "Addition of new attestations for a pre-existing signing identity: the index **MAY** choose to allow additional attestations by pre-existing signing identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "Addition of new signing identities and associated attestations: the index **MAY** choose to support attestations from sources other than the file's uploader, such as third-party auditors or the index itself. These attestations may be performed asynchronously, requiring the index to insert them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "Verifying an attestation object against a distribution file requires verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "``verification_material.certificate`` is a valid signing certificate, as issued by an *a priori* trusted authority (such as a root of trust already present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "``verification_material.certificate`` identifies an appropriate signing subject, such as the machine identity of the Trusted Publisher that published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "``envelope.statement`` is a valid in-toto v1 Statement, with a subject and digest that **MUST** match the distribution's filename and contents. For the distribution's filename, matching **MUST** be performed by parsing using the appropriate source distribution or wheel filename format, as the statement's subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "``envelope.signature`` is a valid signature for ``envelope.statement`` corresponding to ``verification_material.certificate``, as reconstituted via the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "In addition to the above required steps, a verifier **MAY** additionally verify ``verification_material.transparency_entries`` on a policy basis, e.g. requiring at least one transparency log entry or a threshold of entries. When verifying transparency entries, the verifier **MUST** confirm that the inclusion time for each entry lies within the signing certificate's validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "This appendix contains pseudocoded data models for transparency log entries in attestation objects. Each transparency log entry serves as a source of signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "This specification defines a metadata comment block format (loosely inspired by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a comment starting with ``#``. If there are characters after the ``#`` then the first character MUST be a space. The embedded content is formed by taking away the first two characters of each line if the second character is a space, otherwise just the first character (which means the line consists of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "Precedence for an ending line ``# ///`` is given when the next line is not a valid embedded content line as described above. For example, the following is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "A starting line MUST NOT be placed between another starting line and its ending line. In such cases tools MAY produce an error. Unclosed blocks MUST be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "When there are multiple comment blocks of the same ``TYPE`` defined, tools MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "Tools reading embedded metadata MAY respect the standard Python encoding declaration. If they choose not to do so, they MUST process the file as UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "This is the canonical regular expression that MAY be used to parse the metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "In circumstances where there is a discrepancy between the text specification and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "Tools MUST NOT read from metadata blocks with types that have not been standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:73 +msgid "Note that the specification only requires that *top-level* comment blocks are recognised as containing metadata. However, parsing Python code is non-trivial, and therefore:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:77 +msgid "Tools MAY choose to do a simple textual scan, rather than a full Python parse." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:78 +msgid "As a result of the previous point, the behaviour of scripts that contain data that looks like metadata within another Python construct such as a multi-line string is tool-dependent and should not be relied on." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:81 +msgid "The canonical regular expression provided above is an example of an implementation that does a simple textual scan." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:85 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:87 +msgid "The first type of metadata block is named ``script``, which contains script metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:90 +msgid "This document MAY include the top-level fields ``dependencies`` and ``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:93 +msgid "The ``[tool]`` table 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/inline-script-metadata.rst:97 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:99 +msgid "``dependencies``: A list of strings that specifies the runtime dependencies of the script. Each entry MUST be a valid :ref:`dependency specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "``requires-python``: A string that specifies the Python version(s) with which the script is compatible. The value of this field MUST be a valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:106 +msgid "Script runners MUST error if the specified ``dependencies`` cannot be provided. Script runners SHOULD error if no version of Python that satisfies the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:113 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:136 +msgid "The following is an example of how to read the metadata on Python 3.11 or higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:162 +msgid "Often tools will edit dependencies like package managers or dependency update automation in CI. The following is a crude example of modifying the content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:193 +msgid "Note that this example used a library that preserves TOML formatting. This is not a requirement for editing by any means but rather is a \"nice to have\" feature." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:197 +msgid "The following is an example of how to read a stream of arbitrary metadata blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +#: ../source/specifications/simple-repository-api.rst:925 +msgid "Recommendations" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:218 +msgid "Tools that support managing different versions of Python should attempt to use the highest available version of Python that is compatible with the script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:226 +msgid "October 2023: This specification was conditionally approved through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:227 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid ":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-Expression field `. This specification defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "License can be defined as a text string that is a valid SPDX :term:`license expression `, as documented in the `SPDX specification `__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "Any SPDX-listed license short-form identifiers that are published in the `SPDX License List `__, version 3.17 or any later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a unique string containing letters, numbers, ``.`` and/or ``-``, to identify licenses that are not included in the SPDX license list. The custom identifiers must follow the SPDX specification, `clause 10.1 `__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +msgid "Names and normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +msgid "Name normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "September 2015: The specification of name normalized was approved through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "November 2015: The specification of valid names was approved through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "Platform compatibility tags allow build tools to mark distributions as being compatible with specific platforms, and allows installers to understand which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "The ``wheel`` built package format includes these tags in its filenames, of the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "The Python tag indicates the implementation and version required by a distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "Other Python implementations should use :py:data:`sys.implementation.name `." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "The version is ``py_version_nodot``. CPython gets away with no dot, but if one is needed the underscore ``_`` is used instead. PyPy should probably use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "Importantly, major-version-only tags like ``py2`` and ``py3`` are not shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "A single-source Python 2/3 compatible distribution can use the compound tag ``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "The ABI tag indicates which Python ABI is required by any included extension modules. For implementation-specific ABIs, the implementation is abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "Implementations with a very unstable ABI may use the first 6 bytes (as 8 base64-encoded characters) of the SHA-256 hash of their source code revision and compiler flags, etc, but will probably not have a great need to distribute binary distributions. Each implementation's community may decide how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "Platform tags are dependent on the versioning of the operating system or platform they represent and may change over time as the underlying platform changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "In general, distributions built for older versions of the specification are forwards-compatible (meaning that ``manylinux1`` distributions should continue to work on modern systems) but not backwards-compatible (meaning that ``manylinux2010`` distributions are not expected to work on platforms that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "Package maintainers should attempt to target the most compatible specification possible, with the caveat that the provided build environment for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "The following table shows the minimum versions of relevant projects to support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical artefact of Apple's official macOS naming scheme). The schema for compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` corresponds to the minor version number of the macOS release. For macOS 11 and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds to the major version number of the macOS release. Following the published macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or ``>=26`` and corresponding to the year of the macOS release. For example, ``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "macOS binaries can be compiled for a single architecture, or can include support for multiple architectures in the same binary (sometimes called \"fat\" binaries). To indicate support for a single architecture, the value of ``arch`` must match the value of :py:func:`platform.machine()` on the system. To indicate support multiple architectures, the ``arch`` tag should be an identifier from the following list that describes the set of supported architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "The minimum supported macOS version may also be constrained by architecture. For example, macOS 11 (Big Sur) was the first release to support arm64. These additional constraints are enforced transparently by the macOS compilation toolchain when building binaries that support multiple architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "Android uses the schema :file:`android_{apilevel}_{abi}`, indicating compatibility with the given Android API level or later, on the given ABI. For example, ``android_27_arm64_v8a`` indicates support for API level 27 or later, on ``arm64_v8a`` devices. Android makes no distinction between physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "The API level should be a positive integer. This is *not* the same thing as the user-facing Android version. For example, the release known as Android 12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the specific Android version in use. Android's release documentation contains the `full list of Android versions and their corresponding API levels `__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "Virtually all current physical devices use one of the ARM architectures. ``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has not been supported as a development platform since 2020, and no new emulator images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "The value of ``x`` and ``y`` correspond to the major and minor version number of the iOS release, respectively. They must both be positive integers. The version number always includes a major *and* minor version, even if Apple's official version numbering only refers to the major value. For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "The value of ``arch`` must match the value of :py:func:`platform.machine()` on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or ``iphonesimulator`` (for device simulators). These SDKs have the same API surface, but are incompatible at the binary level, even if they are running on the same CPU architecture. Code compiled for an arm64 simulator will not run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "The tags are used by installers to decide which built distribution (if any) to download from a list of potential built distributions. The installer maintains a list of (pyver, abi, arch) tuples that it will support. If the built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "It is recommended that installers try to choose the most feature complete built distribution available (the one most specific to the installation environment) by default before falling back to pure Python versions published for older Python releases. Installers are also recommended to provide a way to configure and re-order the list of allowed compatibility tags; for example, a user might accept only the ``*-none-any`` tags to only download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "Another desirable installer feature might be to include \"re-compile from source if possible\" as more preferable than some of the compatible but legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "This example list is for an installer running under CPython 3.3 on a linux_x86_64 system. It is in order from most-preferred (a distribution with a compiled extension module, built for the current version of Python) to least-preferred (a pure-Python distribution built with an older version of Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "Built distributions may be platform specific for reasons other than C extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "Sometimes there will be more than one supported built distribution for a particular version of a package. For example, a packager could release a package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C extension and the same distribution tagged ``py3-none-any`` that does not. The index of the tag in the supported tags list breaks the tie, and the package with the C extension is installed in preference to the package without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python package that is written to run under Python 2 and 3 with the same source code, could distribute a bdist with the tag ``py2.py3-none-any``. The full list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "A bdist format that implements this scheme should include the expanded tags in bdist-specific metadata. This compression scheme can generate large numbers of unsupported tags and \"impossible\" tags that are supported by no Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "Tools should use the most-preferred architecture dependent tag e.g. ``cp33-cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` by default. If the packager overrides the default it indicates that they intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "What tag do I use if my distribution uses a feature exclusive to the newest version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "Compatibility tags aid installers in selecting the *most compatible* build of a *single version* of a distribution. For example, when there is no Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 exclusive feature) it may still use the ``py3-none-any`` tag instead of the ``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such as a requirement for the older release ``beaglevote-1.1.0`` that does not use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "CPython has lasted 20+ years without a 3-digit major release. This should continue for some time. Other implementations may use _ as a delimiter, since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "To avoid conflicting with the ``.`` and ``-`` characters that separate components of the filename, and for better compatibility with the widest range of filesystem limitations for filenames (including being usable in URL paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "Either because that character is inconvenient or potentially confusing in some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to denote the user's home directory in POSIX), or because the advantages weren't sufficiently compelling to justify changing the existing reference implementation for the wheel format defined in :pep:`427` (for example, using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "New two-letter abbreviations can be requested on the python-dev mailing list. As a rule of thumb, abbreviations are reserved for the current 4 most prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "No. The compatibility tag is part of the built distribution's metadata. METADATA / PKG-INFO should be valid for an entire distribution, not a single build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "The abbreviated tags facilitate sharing compiled Python code in a public index. Your Python implementation can use this specification too, but with longer tags. Recall that all \"pure Python\" built distributions just use ``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "Why is the ABI tag (the second tag) sometimes \"none\" in the reference implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "Since Python 2 does not have an easy way to get to the SOABI (the concept comes from newer versions of Python 3) the reference implementation at the time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" analogous to newer versions of Python, but in the meantime \"none\" is a good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "February 2013: The original version of this specification was approved through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "November 2019: The ``manylinux_x_y`` perennial tag was approved through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +msgid "Project Status Markers" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid ":pep:`792` includes changes to the HTML and JSON index APIs. These changes are documented in the :ref:`simple-repository-api` under :ref:`HTML - Project Detail ` and :ref:`JSON - Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "A project always has exactly one status. If no status is explicitly noted, then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "Indices **MAY** implement any subset of the status markers specified, as applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "This standard does not prescribe *which* principals (i.e. project maintainers, index administrators, etc.) are allowed to set and unset which statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "The index hosting the project **MUST** allow uploads of new distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +msgid "Installer semantics: none." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "The index hosting the project **MUST NOT** allow uploads of new distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +msgid "Installer semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "Description: The project is considered generally unsafe for use, e.g. due to malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "Installers **MAY** produce warnings about a project's quarantine, although doing so is effectively moot (as the index will not offer any distributions for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +msgid "``deprecated``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "Description: The project is considered obsolete, and may have been superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +msgid "``pylock.toml`` Specification" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "The ``pylock.toml`` file format is for specifying dependencies to enable reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "A lock file MUST be named :file:`pylock.toml` or match the regular expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is desired or if multiple lock files exist (i.e. the regular expression ``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and suffix of a named file MUST be lowercase when possible, for easy detection and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "The expectation is that services that automatically install from lock files will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "A multi-use :file:`pylock.toml` with a dependency group with the name of the service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "E.g. a cloud host service named \"spam\" would first look for :file:`pylock.spam.toml` to install from, and if that file didn't exist then install from :file:`pylock.toml` and look for a dependency group named \"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "The lock file(s) SHOULD be located in the directory as appropriate for the scope of the lock file. Locking against a single :file:`pyproject.toml`, for instance, would place the :file:`pylock.toml` in the same directory. If the lock file covered multiple projects in a monorepo, then the expectation is the :file:`pylock.toml` file would be in the directory that held all the projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "Tools SHOULD write their lock files in a consistent way to minimize noise in diff output. Keys in tables -- including the top-level table -- SHOULD be recorded in a consistent order (if inspiration is desired, this specification has tried to write down keys in a logical order). As well, tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +msgid "``lock-version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:505 +#: ../source/specifications/pylock-toml.rst:704 +msgid "**Required?**: yes" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "This PEP specifies the initial version -- and only valid value until future updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "If a tool supports the major version but not the minor version, a tool SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +msgid "``environments``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:480 +#: ../source/specifications/pylock-toml.rst:493 +#: ../source/specifications/pylock-toml.rst:530 +#: ../source/specifications/pylock-toml.rst:689 +#: ../source/specifications/pylock-toml.rst:715 +#: ../source/specifications/pylock-toml.rst:730 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:531 +#: ../source/specifications/pylock-toml.rst:549 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "A list of :ref:`dependency-specifiers-environment-markers` for which the lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "Tools SHOULD write exclusive/non-overlapping environment markers to ease in understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:452 +#: ../source/specifications/pylock-toml.rst:463 +#: ../source/specifications/pylock-toml.rst:529 +#: ../source/specifications/pylock-toml.rst:562 +#: ../source/specifications/pylock-toml.rst:633 +#: ../source/specifications/pylock-toml.rst:703 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:566 +#: ../source/specifications/pylock-toml.rst:621 +#: ../source/specifications/pylock-toml.rst:637 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "Specifies the :ref:`core-metadata-requires-python` for the minimum Python version compatible for any environment supported by the lock file (i.e. the minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "The list of :ref:`extras ` supported by this lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "Lockers MAY choose to not support writing lock files that support extras and dependency groups (i.e. tools may only support exporting a single-use lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "Tools should explicitly set this key to an empty array to signal that the inputs used to generate the lock file had no extras (e.g. a :ref:`pyproject.toml ` file had no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +msgid "``dependency-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:716 +#: ../source/specifications/pylock-toml.rst:731 +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "The list of :ref:`dependency-groups` publicly supported by this lock file (i.e. dependency groups users are expected to be able to specify via a tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "Tools SHOULD explicitly set this key to an empty array to signal that the inputs used to generate the lock file had no dependency groups (e.g. a :ref:`pyproject.toml ` file had no :ref:`[dependency-groups] ` table), signalling that the lock file is, in effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "The name of synthetic dependency groups to represent what should be installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "Meant to be used in situations where :ref:`pylock-packages-marker` necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "The groups listed by this key SHOULD NOT be listed in :ref:`pylock-dependency-groups` as the groups are not meant to be directly exposed to users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "Tools MAY use the :ref:`pylock-tool` table to record enough details that it can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "Tools SHOULD record the normalized name of the tool if it is available as a Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +msgid "``[[packages]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:618 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "Packages MAY be listed multiple times with varying data, but all packages to be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +msgid "``packages.version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +msgid "The version of the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "The version SHOULD be specified when the version is known to be stable (i.e. when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "The version MUST NOT be included when it cannot be guaranteed to be consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "The :ref:`environment marker ` which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "Holds the :ref:`version-specifiers` for Python version compatibility for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +msgid "``[[packages.dependencies]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "Records the other entries in :ref:`pylock-packages` which are direct dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "Each entry is a table which contains the minimum information required to tell which other package entry it corresponds to where doing a key-by-key comparison would find the appropriate package with no ambiguity (e.g. if there are two entries for the ``spam`` package, then you can include the version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "Tools MUST NOT use this information when doing installation; it is purely informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:546 +#: ../source/specifications/pylock-toml.rst:714 +#: ../source/specifications/pylock-toml.rst:729 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "**Required?**: no; mutually-exclusive with :ref:`pylock-packages-directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "Tools MAY choose to not support version control systems, both from a locking and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "Tools SHOULD provide a way for users to opt in/out of using version control systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "Installation from a version control system is considered originating from a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "**Type**: string; supported values specified in :ref:`direct-url-data-structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +#: ../source/specifications/pylock-toml.rst:467 +msgid "If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +#: ../source/specifications/pylock-toml.rst:468 +msgid "If the path is relative it MAY use POSIX-style path separators explicitly for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "This is purely informational and to facilitate writing the :ref:`direct-url-data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "If the VCS supports commit-hash based revision identifiers, such a commit-hash, it MUST be used as the commit ID in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "**Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "Tools MAY choose to not support local directories, both from a locking and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "Tools SHOULD provide a way for users to opt in/out of using local directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "Installation from a directory is considered originating from a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "If the path is relative it MAY use POSIX-style path separators for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "A flag representing whether the source tree was an editable install at lock time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "An installer MAY choose to ignore this flag if user actions or context would make an editable install unnecessary or undesirable (e.g. a container image that will not be mounted for development purposes but instead deployed to production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:521 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:436 +#: ../source/specifications/pylock-toml.rst:454 +#: ../source/specifications/pylock-toml.rst:465 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "A direct reference to an archive file to install from (this can include wheels and sdists, as well as other archive formats containing a source tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "Tools MAY choose to not support archive files, both from a locking and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "Installation from an archive file is considered originating from a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:453 +msgid "**Required?**: if :ref:`pylock-packages-archive-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:455 +msgid "The URL_ to the archive." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:461 +msgid "``packages.archive.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:464 +msgid "**Required?**: if :ref:`pylock-packages-archive-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +msgid "The path to the archive." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "If :ref:`pylock-packages-archive-url` is also specified, the filename as specified by this key takes precedence." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:477 +msgid "``packages.archive.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:482 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "Tools SHOULD provide the file size when reasonably possible (e.g. the file size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:490 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:492 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:494 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "The time the file was uploaded." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:502 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:504 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:506 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:507 +msgid "A table listing known hash values of the file where the key is the hash algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:509 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:510 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:511 +msgid "At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` SHOULD always be included (at time of writing, sha256 specifically is recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:519 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:527 +msgid "``packages.index``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:532 +msgid "The base URL for the package index from :ref:`simple-repository-api` where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:534 +msgid "When possible, this SHOULD be specified to assist with generating `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:537 +msgid "Tools MAY support installing from an index if the URL recorded for a specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:544 +msgid "``[packages.sdist]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:547 +#: ../source/specifications/pylock-toml.rst:619 +msgid "**Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:550 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "Tools MAY choose to not support sdist files, both from a locking and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:554 +msgid "Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:560 +msgid "``packages.sdist.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:563 +msgid "**Required?**: no, not when the last component of :ref:`pylock-packages-sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:567 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:568 +msgid "If specified, this key's value takes precedence over the file name found in either :ref:`pylock-packages-sdist-url` or :ref:`pylock-packages-sdist-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:575 +msgid "``packages.sdist.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:577 +#: ../source/specifications/pylock-toml.rst:648 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:583 +msgid "``packages.sdist.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:585 +#: ../source/specifications/pylock-toml.rst:656 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:591 +msgid "``packages.sdist.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:593 +#: ../source/specifications/pylock-toml.rst:664 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:599 +msgid "``packages.sdist.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:601 +#: ../source/specifications/pylock-toml.rst:672 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:607 +msgid "``packages.sdist.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:609 +#: ../source/specifications/pylock-toml.rst:680 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:616 +msgid "``[[packages.wheels]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:622 +msgid "For recording the wheel files as specified by :ref:`binary-distribution-format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:624 +msgid "Tools MUST support wheel files, both from a locking and installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:634 +msgid "**Required?**: no, not when the last component of :ref:`pylock-packages-wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:638 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "If specified, this key's value takes precedence over the file name found in either :ref:`pylock-packages-wheels-url` or :ref:`pylock-packages-wheels-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:646 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:654 +msgid "``packages.wheels.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:662 +msgid "``packages.wheels.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:670 +msgid "``packages.wheels.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "``packages.wheels.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:690 +#: ../source/specifications/pylock-toml.rst:705 +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:692 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:693 +msgid "Publisher-specific keys are to be included in the table as-is (i.e. top-level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:701 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:706 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[packages.tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "Similar usage as that of the :ref:`pylock-tool` table from the :ref:`pyproject-toml-spec`, but at the package version level instead of at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:720 +msgid "Data recorded in the table MUST be disposable (i.e. it MUST NOT affect installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:727 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:732 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:746 +msgid "The following outlines the steps to be taken to install from a lock file (while the requirements are prescriptive, the general steps and order are a suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "Gather the extras and dependency groups to install and set ``extras`` and ``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:753 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:757 +msgid "Check if the metadata version specified by :ref:`pylock-lock-version` is supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:759 +msgid "If :ref:`pylock-requires-python` is specified, check that the environment being installed for meets the requirement; an error MUST be raised if it is not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:762 +msgid "If :ref:`pylock-environments` is specified, check that at least one of the environment marker expressions is satisfied; an error MUST be raised if no expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "If :ref:`pylock-packages-requires-python` is specified, check if it is satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +msgid "Check that no other conflicting instance of the package has been slated to be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Check that the source of the package is specified appropriately (i.e. there are no conflicting sources in the package entry); an error MUST be raised if any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:776 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:778 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:780 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid ":ref:`Build ` the package, respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:792 +#: ../source/specifications/pylock-toml.rst:801 +#: ../source/specifications/pylock-toml.rst:821 +#: ../source/specifications/pylock-toml.rst:836 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid ":ref:`Build ` the package, respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +#: ../source/specifications/pylock-toml.rst:826 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:799 +msgid ":ref:`Build ` the package, respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:803 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:805 +msgid "Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-name`; if one is not found then move on to :ref:`pylock-packages-sdist` or an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:809 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:811 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:812 +msgid "Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism to download the selected wheel file (tools MUST NOT try to change what wheel file to download based on what's available; what file to install should be determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:819 +msgid "Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:823 +msgid "Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:829 +msgid "Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism to download the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:833 +msgid "Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:835 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:843 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:844 +msgid "March 2026: Clarify file name precedence for archives, sdists, and wheels." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" + +#: ../source/specifications/pypirc.rst:8 +msgid "A :file:`.pypirc` file allows you to define the configuration for :term:`package indexes ` (referred to here as \"repositories\"), so that you don't have to enter the URL, username, or password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "" + +#: ../source/specifications/pypirc.rst:15 +msgid "Tools that read or write :file:`.pypirc` files may not function correctly if another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "The ``distutils`` section defines an ``index-servers`` field that lists the name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "Be aware that this stores your password in plain text. For better security, consider an alternative like `keyring`_, setting environment variables, or providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "Otherwise, set the permissions on :file:`.pypirc` so that only you can view or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also use :file:`.pypirc`, but with different defaults. Please refer to each project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "Twine's default configuration mimics a :file:`.pypirc` with repository sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "Twine will add additional configuration from :file:`$HOME/.pypirc`, the command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "For :ref:`TestPyPI `, add a ``[testpypi]`` section, using the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "To configure an additional repository, you'll need to redefine the ``index-servers`` field to include the repository name. Here is a complete example of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "Instead of using the ``password`` field, consider saving your API tokens and passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "This is a **technical, formal specification**. For a gentle, user-friendly guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "The ``[build-system]`` table declares any Python level dependencies that must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "The ``[build-system]`` table is used to store build-related data. Initially, only one key of the table is valid and is mandatory for the table: ``requires``. This key must have a value of a list of strings representing dependencies required to execute the build system. The strings in this list follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "An example ``[build-system]`` table for a project built with ``setuptools`` is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "Build tools are expected to use the example configuration file above as their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "Tools may choose to present an error to the user if the file exists, ``[build-system]`` table is missing, and there is no clear indication that the project should be built (e.g., no setup.py/setup.cfg or other build configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "To provide a type-specific representation of the resulting data from the TOML file for illustrative purposes only, the following `JSON Schema `_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "There are two kinds of metadata: *static* and *dynamic*. Static metadata is specified in the ``pyproject.toml`` file directly and cannot be specified or changed by a tool (this includes data *referred* to by the metadata, e.g. the contents of files referenced by the metadata). Dynamic metadata is listed via the ``dynamic`` key (defined later in this specification) and represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "A key whose value is a list or a table of arbitrary entries MAY be specified statically *and* listed in ``dynamic`` at the same time. In that case the entries given statically are fixed and a build back-end MAY only *append* further entries to them; the back-end MUST NOT remove, reorder, or modify any statically-specified entries. See the :ref:`dynamic ` key for details." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "The lack of a ``[project]`` table implicitly means the :term:`build backend ` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:127 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:131 +msgid "The keys which are required but may be specified *either* statically or listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "All other keys are considered optional and may be specified statically, listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:645 +msgid "``authors``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:459 +#: ../source/specifications/pyproject-toml.rst:647 +msgid "``dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:604 +msgid "``dynamic``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +#: ../source/specifications/pyproject-toml.rst:648 +msgid "``entry-points``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:649 +msgid "``gui-scripts``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:148 +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:650 +msgid "``import-names``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:563 +#: ../source/specifications/pyproject-toml.rst:651 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:654 +msgid "``maintainers``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:155 +#: ../source/specifications/pyproject-toml.rst:483 +#: ../source/specifications/pyproject-toml.rst:655 +msgid "``optional-dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:168 +#: ../source/specifications/pyproject-toml.rst:183 +#: ../source/specifications/pyproject-toml.rst:198 +#: ../source/specifications/pyproject-toml.rst:252 +#: ../source/specifications/pyproject-toml.rst:264 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:169 +msgid "Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:172 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:174 +msgid "Tools SHOULD :ref:`normalize ` this name, as soon as it is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:184 +msgid "Corresponding :ref:`core metadata ` field: :ref:`Version `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:187 +msgid "The version of the project, as defined in the :ref:`Version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:190 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:199 +msgid "Corresponding :ref:`core metadata ` field: :ref:`Summary `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:202 +msgid "The summary description of the project in one line. Tools MAY error if this includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:212 +msgid "Corresponding :ref:`core metadata ` field: :ref:`Description ` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:216 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:218 +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 specification, it MAY infer the content-type for the user without specifying this key as ``dynamic``. For all unrecognized suffixes when a content-type is not provided, tools MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "The ``readme`` key may also take a table. The ``file`` key has a string value representing a path relative to ``pyproject.toml`` to a file containing the full description. The ``text`` key has a string value which is the full description. These keys are mutually-exclusive, thus tools MUST raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:236 +msgid "A table specified in the ``readme`` key also has a ``content-type`` key which takes a string specifying the content-type of the full description. A tool MUST raise an error if the metadata does not specify this key in the table. If the metadata does not specify the ``charset`` parameter, then it is assumed to be UTF-8. Tools MAY support other encodings if they choose to. Tools MAY support alternative content-types which they can transform to a content-type as supported by the :ref:`core metadata `. Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:253 +msgid "Corresponding :ref:`core metadata ` field: :ref:`Requires-Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:256 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:265 +msgid "Corresponding :ref:`core metadata ` field: :ref:`License-Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:268 +msgid "Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +msgid "This key should **only** be specified if the license expression for any and all distribution files created by a build backend using the :file:`pyproject.toml` is the same as the one specified. If the license expression will differ then it should either be specified as dynamic or not set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:280 +msgid "Legacy specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:282 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:283 +msgid "Corresponding :ref:`core metadata ` field: :ref:`License `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "The table may have one of two keys. The ``file`` key has a string value that is a file path relative to :file:`pyproject.toml` to the file which contains the license for the project. Tools MUST assume the file's encoding is UTF-8. The ``text`` key has a string value which is the license of the project. These keys are mutually exclusive, so a tool MUST raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +msgid "The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:300 +#: ../source/specifications/pyproject-toml.rst:383 +#: ../source/specifications/pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:514 +#: ../source/specifications/pyproject-toml.rst:565 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:301 +msgid "Corresponding :ref:`core metadata ` field: :ref:`License-File `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:304 +msgid "An array specifying paths in the project source tree relative to the project root directory (i.e. directory containing :file:`pyproject.toml` or legacy project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) to file(s) containing licenses and other legal notices to be distributed with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:310 +msgid "The strings MUST contain valid glob patterns, as specified in :doc:`/specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "Tools MUST assume that license file content is valid UTF-8 encoded text, and SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:320 +msgid "MUST include all files matched by a listed pattern in all distribution archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:322 +msgid "MUST list each matched file path under a License-File field in the Core Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:325 +msgid "If the ``license-files`` key is present and is set to a value of an empty array, then tools MUST NOT include any license files and MUST NOT raise an error. If the ``license-files`` key is not defined, tools can decide how to handle license files. For example they can choose not to include any files or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:340 +msgid "Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:346 +msgid "The people or organizations considered to be the \"authors\" of the project. The exact meaning is open to interpretation — it may list the original or primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:351 +msgid "The \"maintainers\" key is similar to \"authors\" in that its exact meaning is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "These keys accept an array of tables with 2 keys: ``name`` and ``email``. Both values must be strings. The ``name`` value MUST be a valid email name (i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not contain commas. The ``email`` value MUST be a valid email address. Both keys are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:361 +msgid "Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:367 +msgid "If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:371 +msgid "If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:375 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:384 +msgid "Corresponding :ref:`core metadata ` field: :ref:`Keywords `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:387 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:396 +msgid "Corresponding :ref:`core metadata ` field: :ref:`Classifier `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:399 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:401 +msgid "The use of ``License ::`` classifiers is deprecated and tools MAY issue a warning informing users about that. Build tools MAY raise an error if both the ``license`` string value (translating to ``License-Expression`` metadata field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:413 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:414 +msgid "Corresponding :ref:`core metadata ` field: :ref:`Project-URL `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:417 +msgid "A table of URLs where the key is the URL label and the value is the URL itself. See :ref:`well-known-project-urls` for normalization rules and well-known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:427 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:429 +msgid "TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and ``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:431 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:433 +msgid "There are three tables related to entry points. The ``[project.scripts]`` table corresponds to the ``console_scripts`` group in the :ref:`entry points specification `. The key of the table is the name of the entry point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:439 +msgid "The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group in the :ref:`entry points specification `. Its format is the same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:443 +msgid "The ``[project.entry-points]`` table is a collection of tables. Each sub-table's name is an entry point group. The key and value semantics are the same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:449 +msgid "Build back-ends MUST raise an error if the metadata defines a ``[project.entry-points.console_scripts]`` or ``[project.entry-points.gui_scripts]`` table, as they would be ambiguous in the face of ``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:461 +msgid "TOML_ type: Array of :ref:`dependency specifier ` strings (``dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:463 +msgid "Corresponding :ref:`core metadata ` field: :ref:`Requires-Dist `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:466 +msgid "``dependencies`` lists the expected dependencies of the project as an array of strings." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "Each string represents a dependency of the project and MUST be formatted as a valid :ref:`dependency specifier `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:472 +msgid "Each string maps directly to a :ref:`Requires-Dist ` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:475 +msgid "Dependencies listed in this array are always considered for installation, but may still contain environment markers that cause them to be skipped in some environments." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "TOML_ type: table with string keys mapping to arrays of :ref:`dependency specifier ` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:487 +msgid "Corresponding :ref:`core metadata ` fields: :ref:`Requires-Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:491 +msgid "``optional-dependencies`` is a table where each key specifies an extra and whose value is an array of strings using the same format as the ``dependencies`` array (the strings in the arrays must be valid :ref:`dependency specifiers `)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:496 +msgid "The keys MUST be valid values for :ref:`Provides-Extra `. Each value in the array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:503 +msgid "The optionality of these dependencies is recorded by modifying the environment marker clause on the related ``Requires-Dist`` entries to check the extra name. Optional dependencies are thus only considered for installation if installation if the associated extra name is requested." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +msgid "Corresponding :ref:`core metadata ` field: :ref:`Import-Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:518 +msgid "An array of strings specifying the import names that the project exclusively provides when installed. Each string MUST be a valid Python identifier or can be empty. An import name MAY be followed by a semicolon and the term \"private\" (e.g. ``\"; private\"``) with any amount of whitespace surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:523 +msgid "Projects SHOULD list all the shortest import names that are exclusively provided by the project. If any of the shortest names are dotted names, all intervening names from that name to the top-level name should also be listed appropriately in ``import-names`` and/or ``import-namespaces``. For instance, a project which is a single package named spam with multiple submodules would only list ``project.import-names = [\"spam\"]``. A project that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and ``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. Listing all names acts as a check that the intent of the import names is as expected. As well, projects SHOULD list all import names, public or private, using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:535 +#: ../source/specifications/pyproject-toml.rst:584 +msgid "If a project lists the same name in both ``import-names`` and ``import-namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:538 +msgid "Projects MAY set ``import-names`` to an empty array to represent a project with no import names (i.e. there are no Python modules of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:542 +#: ../source/specifications/pyproject-toml.rst:587 +msgid "Build back-ends MAY support dynamically calculating the value if the user declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "Examples:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:566 +msgid "Corresponding :ref:`core metadata ` field: :ref:`Import-Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:569 +msgid "An array of strings specifying the import names that the project provides when installed, but not exclusively. Each string MUST be a valid Python identifier. An import name MAY be followed by a semicolon and the term \"private\" (e.g. ``\"; private\"``) with any amount of whitespace surrounding the semicolon. Note that unlike ``import-names``, ``import-namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:575 +msgid "Projects SHOULD list all the shortest import names that are exclusively provided by the project. If any of the shortest names are dotted names, all intervening names from that name to the top-level name should also be listed appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "This field is used for namespace packages where multiple projects can contribute to the same import namespace. Projects all listing the same import name in ``import-namespaces`` can be installed together without shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +msgid "Example:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:606 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:607 +msgid "Corresponding :ref:`core metadata ` field: :ref:`Dynamic `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:610 +msgid "Specifies which keys listed by this PEP were intentionally unspecified so another tool can/will provide such metadata dynamically. This clearly delineates which metadata is purposefully unspecified and expected to stay unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:616 +msgid "A build back-end MUST honour statically-specified metadata (which means the metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:618 +msgid "A build back-end MUST raise an error if the metadata specifies ``name`` in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:620 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:625 +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 "" + +#: ../source/specifications/pyproject-toml.rst:629 +msgid "Build back-ends MUST raise an error if the metadata specifies a key statically as well as being listed in ``dynamic``, *unless* the key represents a list or arbitrary table that can be extended, listed below." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:632 +msgid "If the metadata does not list a key in ``dynamic``, then a build back-end CANNOT fill in the requisite metadata on behalf of the user (i.e. ``dynamic`` is the only way to allow a tool to fill in metadata and the user must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:636 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "A key whose value is a list or a table of arbitrary entries MAY be specified statically and listed in ``dynamic`` simultaneously. The keys fitting that description are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:659 +msgid "When such a key is specified both statically and listed in ``dynamic``:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:662 +msgid "A build back-end MAY only *append* entries to the value; it MUST NOT remove, reorder, or modify any statically-specified entries. For tables (such as ``optional-dependencies`` or ``entry-points``) this means a back-end MAY add new keys and MAY append to the values of existing keys (in the case of a list), but MUST NOT change or remove the entries given statically." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:668 +msgid "A build back-end SHOULD raise an error if a key is listed in ``dynamic`` and it does not support extending that key." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:675 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:677 +msgid "The ``[tool]`` table is where any tool related to your Python project, not just build tools, can have users specify configuration data as long as they use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:683 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:694 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:698 +msgid "November 2020: The specification of the ``[project]`` table was approved through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:701 +msgid "December 2024: The ``license`` key was redefined, the ``license-files`` key was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:704 +msgid "September 2025: Clarity that the ``license`` key applies to all distribution files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:707 +msgid "October 2025: The ``import-names`` and ``import-namespaces`` keys were added through :pep:`794`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:713 +msgid "May 2026: Allowed list and table keys to be specified statically as well as listed in ``dynamic``, with build back-ends only able to append entries, through :pep:`808`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "This document specifies a common format of recording information about Python :term:`projects ` installed in an environment. A common metadata format allows tools to query, manage or uninstall projects, regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "Almost all information is optional. This allows tools outside the Python ecosystem, such as Linux package managers, to integrate with Python tooling 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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "This ``.dist-info`` directory may contain the following files, described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "The ``METADATA`` file is mandatory. All other files may be omitted at the installing tool's discretion. Additional installer-specific files may be present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "This :file:`.dist-info/` directory may contain the following directories, described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "The ``METADATA`` file contains metadata as described in the :ref:`core-metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "The ``METADATA`` file is mandatory. If it cannot be created, or if required core metadata is not available, installers must report an error and fail to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "The ``RECORD`` file holds the list of installed files. It is a CSV file containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "The CSV dialect must be readable with the default ``reader`` of Python's ``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "Each record is composed of three elements: the file's **path**, the **hash** of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "The *size* is either the empty string, or file's size in bytes, as a base 10 integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "To completely uninstall a package, a tool needs to remove all files listed in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "This file MUST be created by installers when installing a distribution from a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "If the metadata version is 2.4 or greater and one or more ``License-File`` fields is specified, the :file:`.dist-info/` directory MUST contain a :file:`licenses/` subdirectory which MUST contain the files listed in the ``License-File`` fields in the :file:`METADATA` file at their respective paths relative to the :file:`licenses/` directory. Any files in this directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "All files contained within the :file:`.dist-info/sboms/` directory MUST be Software Bill-of-Materials (SBOM) files that describe software contained within the installed package. Any files in this directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "Write an ``INSTALLER`` file indicating the name of the tool that should be used to manage the package (this allows ``RECORD``-aware tools to provide better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "September 2020: Various amendments and clarifications were approved through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +msgid "PyPA schemas" +msgstr "" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +msgid "Python Description Formats" +msgstr "" + +#: ../source/specifications/section-reproducible-environments.rst:3 +msgid "Reproducible Environments" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "The interface for querying available package versions and retrieving packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +msgid "Normalized Names" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "This section contains only an abbreviated history of changes, as marked by the API version number. For a full history of changes including changes made before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "API version 1.2: Added repository \"tracks\" metadata, declared with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "When encountering a minor version greater than expected, clients **SHOULD** warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +msgid "HTML Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:127 +msgid "The HTML representation is considered \"frozen\" and is not expected to be updated. Producers and consumers of the simple API should prefer the :ref:`JSON representation `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:131 +msgid "See :pep:`833` for additional information about the HTML representation's status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:134 +msgid "The following constraints apply to all HTML serialized responses described in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:137 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:138 +msgid "HTML responses **MAY** contain one or more ``meta`` tags in the ```` section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:142 +#: ../source/specifications/simple-repository-api.rst:437 +msgid "Project List" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:144 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:148 +msgid "The text of each 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:165 +#: ../source/specifications/simple-repository-api.rst:482 +msgid "Project Detail" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:173 +msgid "For example, a project named \"HolyGrail\" would have a URL like ``/holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:176 +msgid "The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:181 +msgid "Each file 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:186 +msgid "In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:188 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:192 +msgid "URLs may be either absolute or relative as long as they point to the correct location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:195 +msgid "There are no constraints on where the files must be hosted relative to the repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:198 +msgid "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:201 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:206 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:217 +msgid "A repository **MAY** include a ``data-core-metadata`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "The repository **SHOULD** provide the hash of the Core Metadata file as the ``data-core-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:226 +msgid "A repository **MAY** include a ``data-dist-info-metadata`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:229 +msgid "Index clients **MAY** consume this key if present, as a legacy fallback for ``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:234 +msgid "``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to ``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:237 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:241 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:251 +msgid "In the attribute value, < and > have to be HTML encoded as ``<`` and ``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:254 +msgid "A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:256 +msgid "The ``data-yanked`` attribute 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:262 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:267 +#: ../source/specifications/simple-repository-api.rst:612 +msgid "The semantics of how tools should handle yanked files is described in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:270 +msgid "A repository **MAY** include a ``data-provenance`` attribute on a file link. The value of this attribute **MUST** be a fully qualified URL, signaling that the file's provenance can be found at that URL. This URL **MUST** represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:281 +msgid "The format of the linked provenance is defined in :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +msgid "A repository **MAY** include ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:286 +msgid "The value of ``pypi:project-status`` **MUST** be a valid project status marker, while the value of ``pypi:project-status-reason`` **MUST** be an arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:292 +#: ../source/specifications/simple-repository-api.rst:498 +msgid "The set of valid project status markers and their semantics is described in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:297 +msgid "The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:303 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:305 +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:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:320 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:328 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:330 +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/simple-repository-api.rst:334 +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:343 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:345 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:350 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:360 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:367 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:373 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:377 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:381 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:385 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:391 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "JSON Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:401 +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:405 +msgid "The following constraints apply to all JSON serialized responses described in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:408 +msgid "All JSON responses will *always* be a JSON object rather than an array or other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:411 +msgid "While JSON doesn't natively support a 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:416 +msgid "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:419 +msgid "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:422 +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:428 +msgid "All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:431 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:439 +msgid "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:442 +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:443 +#: ../source/specifications/simple-repository-api.rst:517 +msgid "``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:445 +#: ../source/specifications/simple-repository-api.rst:643 +msgid "As an example:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:462 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:472 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:484 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:489 +msgid "This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:491 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:492 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:503 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "``reason``: If present, this **MUST** be an arbitrary string description of the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:510 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:514 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +msgid "``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:518 +msgid "``versions``: A list of version strings specifying all of the project versions uploaded for this project. The value of ``versions`` is logically a set, and as such may not contain duplicates, and the order of the versions is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:525 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:532 +msgid "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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:540 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:544 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:545 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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:555 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:566 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:569 +msgid "``core-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:577 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:585 +msgid "It is recommended that servers make the hashes of the metadata file available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:588 +msgid "``dist-info-metadata``: An **optional**, deprecated alias for ``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:590 +msgid "Index clients **MAY** consume this key if present, as a legacy fallback for ``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +msgid "``dist-info-metadata`` was standardized with :pep:`658` and renamed to ``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:598 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:604 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:615 +msgid "``size``: A **mandatory** key. It **MUST** contain an integer which is the file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:619 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:621 +msgid "``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "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/simple-repository-api.rst:632 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:634 +msgid "``provenance``: An **optional** key which, if present **MUST** be either a JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's associated provenance, with the same rules as ``data-provenance`` in the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:641 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:679 +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:688 +msgid "Content-Types" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:690 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:694 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:700 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:705 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:707 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:708 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:710 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:722 +msgid "Version + Format Selection" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:724 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:729 +msgid "To enable this, this spec standardizes on the use of HTTP's `Server-Driven Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:732 +msgid "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:735 +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:737 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +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:744 +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:746 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:749 +msgid "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:751 +msgid "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:754 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:759 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:766 +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. an ``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:773 +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:777 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:778 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:779 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:781 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:785 +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:792 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:798 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:802 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:809 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:860 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:866 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:868 +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:876 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:878 +msgid "Servers that implement the Simple API may choose to support a URL parameter named ``format`` to allow the clients to request a specific version of the URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:885 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:890 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:902 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:904 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:908 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:912 +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/simple-repository-api.rst:919 +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/simple-repository-api.rst:927 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:931 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:936 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:942 +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/simple-repository-api.rst:947 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:950 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:956 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:958 +msgid "Support all 3 content types described in this spec, using server-driven content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:961 +msgid "When constructing an ``Accept`` header, include all of the content types that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:964 +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/simple-repository-api.rst:970 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:974 +msgid "Explicitly select what versions they are looking for, rather than using the ``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "Check the ``Content-Type`` of the response and ensure it matches something that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:986 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:987 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:988 +msgid "July 2020: API versioning convention and metadata, and declaring the HTML format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "May 2021: providing package metadata independently from a package, in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:992 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:994 +msgid "October 2022: project versions and file size and upload-time in the JSON format, in :pep:`700`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:996 +msgid "June 2023: renaming the field which provides package metadata independently from a package, in :pep:`714`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:998 +msgid "November 2024: provenance metadata in the HTML and JSON formats, in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:999 +msgid "July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:1000 +msgid "July 2025: layout changes (dedicated page for file yanking, introduce concepts before API details)" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:1001 +msgid "June 2026: :pep:`833` formally \"freezes\" the HTML representation of the simple API" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "The name and version components of the filename MUST match the values stored in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format described in the :ref:`core-metadata` specification. The metadata MUST conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "If the metadata version is 2.4 or greater, the source distribution MUST contain any license files specified by the ``License-File`` field in the :file:`PKG-INFO` at their respective paths relative to the root directory of the sdist (containing the :file:`pyproject.toml` and the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +msgid "The tarball must 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 "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "Because extracting tar files as-is is dangerous, and the results are platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "The following are also invalid. Tools MAY treat them as above, but are NOT REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "Tools MAY unpack links (symbolic or hard) as regular files, using content from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "Leading slashes in file names MUST be dropped. (This is nowadays standard behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or ``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "Tool authors are encouraged to consider how *hints for further verification* in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "November 2020: The original version of this specification was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "September 2022: The filename of a source distribution was standardized through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "August 2023: Source distribution archive features were standardized through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "December 2024: License files inclusion into source distribution was standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "This specification describes a scheme for identifying versions of Python software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +msgid "Definitions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "\"Index servers\" are active distribution registries which publish version and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "\"Publication tools\" are automated tools intended to run on development systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "\"Automated tools\" is a collective term covering build tools, index servers, publication tools, integration tools and any other software that produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +msgid "Version scheme" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "Distributions are identified by a public version identifier which supports all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "The canonical public version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "Installation tools SHOULD ignore any public versions which do not comply with this scheme but MUST also include the normalizations specified below. Installation tools MAY warn the user when non-compliant or ambiguous versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "See also :ref:`version-specifiers-regex` which provides a regular expression to check strict conformance with the canonical format, as well as a more permissive regular expression accepting inputs that may require subsequent normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "Any given release will be a \"final release\", \"pre-release\", \"post-release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "All numeric components MUST be non-negative integers represented as sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "All numeric components MUST be interpreted and ordered according to their numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "All numeric components MAY be zero. Except as described below for the release segment, a numeric component of zero has no special significance aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "Some hard to read version identifiers are permitted by this scheme in order to better accommodate the wide range of versioning practices across existing public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "Source distributions using a local version identifier SHOULD provide the ``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "A version identifier that consists solely of a release segment and optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "The release segment consists of one or more non-negative integer values, separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "Final releases within a project MUST be numbered in a consistently increasing fashion, otherwise automated tools will not be able to upgrade them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "A release series is any set of final release numbers that start with a common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +msgid "Pre-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "If used as part of a project's development cycle, these pre-releases are indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "A version identifier that consists solely of a release segment and a pre-release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "Build tools, publication tools and index servers SHOULD disallow the creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "Some projects use post-releases to address minor errors in a final release that do not affect the distributed software (for example, correcting an error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "If used as part of a project's development cycle, these post-releases are indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "A version identifier that includes a post-release segment without a developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "A version identifier that includes a developmental release segment is termed a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "Developmental releases are also permitted for pre-releases and post-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "Do note that development releases are considered a type of pre-release when handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "Developmental releases of post-releases are also strongly discouraged, but they may be appropriate for projects which use the post-release notation for full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +msgid "Version epochs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "If included in a version identifier, the epoch appears before all other components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "However, by specifying an explicit epoch, the sort order can be changed appropriately, as all versions from a later epoch are sorted after versions from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "Use of nonzero epochs is discouraged. They are often not supported or discouraged by downstream packaging where Python packages may need to be consumed, and due to their scarce use they may also not be well supported by Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "When version scheme needs to be changed, it is preferable to continue with monotonically increasing numbers in epoch zero. For example, the version 2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +msgid "Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "All ascii letters should be interpreted case insensitively within a version and the normal form is lowercase. This allows versions such as ``1.1RC1`` which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +msgid "Integer Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "\"major.minor\" versioning with developmental releases, release candidates and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "Date based releases, using an incrementing serial within each year, skipping zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "This section is intended primarily for authors of tools that automatically process distribution metadata, rather than developers of Python distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "The epoch segment of version identifiers MUST be sorted according to the numeric value of the given epoch. If no epoch segment is present, the implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "The release segment of version identifiers MUST be sorted in the same order as Python's tuple sorting when the normalized release segment is parsed as follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "All release segments involved in the comparison MUST be converted to a consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate (``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "Within a post-release (``1.0.post1``), the following suffixes are permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when used immediately following a numeric version (e.g. ``1.0.dev456``, ``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "Within a pre-release, post-release or development release segment with a shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a standard version identification or ordering scheme. However metadata v1.2 (:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "Distribution users may wish to explicitly remove non-compliant versions from any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "This allows automated distribution tools to provide consistently correct ordering of published releases, while still allowing developers to use the internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "Semantic versions containing a hyphen (pre-releases - clause 10) or a plus sign (builds - clause 11) are *not* compatible with this specification and are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "One possible mechanism to translate such semantic versioning based source labels to compatible public versions is to use the ``.devN`` suffix to specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "The ``pytz`` project inherits its versioning scheme from the corresponding Olson timezone database versioning scheme: the year followed by a lowercase character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "As with other translated version identifiers, the corresponding Olson database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "A version specifier consists of a series of version clauses, separated by commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "The comma (\",\") is equivalent to a logical **and** operator: a candidate version must match all given version clauses in order to match the specifier as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "Whitespace between a conditional operator and the following version identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "Except where specifically noted below, local version identifiers MUST NOT be permitted in version specifiers, and local version labels MUST be ignored entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "A compatible release clause consists of the compatible release operator ``~=`` and a version identifier. It matches any candidate version that is expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "The specified version identifier must be in the standard format described in `Version scheme`_. Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "For a given release identifier ``V.N``, the compatible release clause is approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "This operator MUST NOT be used with a single segment version number such as ``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "If a pre-release, post-release or developmental release is named in a compatible release clause as ``V.N.suffix``, then the suffix is ignored when determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "The padding rules for release segment comparisons means that the assumed degree of forward compatibility in a compatible release clause can be controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "A version matching clause includes the version matching operator ``==`` and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "For example, given the version ``1.1.post1``, the following clauses would match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +msgid "Version exclusion" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "A version exclusion clause includes the version exclusion operator ``!=`` and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "The exclusive ordered comparison ``>V`` **MUST NOT** match a local version of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "The exclusive ordered comparison ``=`` entry as part of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "Note: this comparison is to ``pkg_resources.parse_version`` as it existed at the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "Local versions sort differently, this specification requires that they sort as greater than the same version without a local version, whereas ``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "This specification purposely restricts the syntax which constitutes a valid version while ``pkg_resources.parse_version`` attempts to provide some meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "``pkg_resources.parse_version`` allows arbitrarily deeply nested version signifiers like ``1.0.dev1.post1.dev5``. This specification however allows only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "To test whether a version identifier is in the canonical format, you can use the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "To extract the components of a version identifier, use the following regular expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "May 2025: Clarify that development releases are a form of pre-release when they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +msgid "Well-known Project URLs in Metadata" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "This document is primarily of interest to metadata *consumers*, who should use the normalization rules and well-known list below to make their presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "Metadata *producers* (such as build tools and individual package maintainers) may continue to use any labels they please, within the overall ``Project-URL`` length restrictions. However, when possible, users are *encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "See :ref:`Writing your pyproject.toml - urls ` for user-oriented guidance on choosing project URL labels in your package's metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid ":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-metadata-download-url` metadata fields in favor of :ref:`core-metadata-project-url`, and defines a normalization and lookup procedure for determining whether a ``Project-URL`` is \"well-known,\" i.e. has the semantics assigned to ``Home-page``, ``Download-URL``, or other common project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "This allows indices (such as the Python Package Index) and other downstream metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +msgid "Label normalization" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "Label normalization is performed by metadata *consumers*, not metadata producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "To determine whether a ``Project-URL`` label is \"well-known,\" metadata consumers should normalize the label before comparing it to the :ref:`list of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "The normalization procedure for ``Project-URL`` labels is defined by the following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "In plain language: a label is *normalized* by deleting all ASCII punctuation and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "The following table shows examples of labels before (raw) and after normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +msgid "Normalized" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "The list of well-known labels is a living standard, maintained as part of this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "The following table lists labels that are well-known for the purpose of specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "Package metadata consumers may choose to render aliased labels the same as their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "The following shows the flow of project URL metadata from ``pyproject.toml`` to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "Observe that the core metadata appears in the form provided by the user (since metadata *producers* do not perform normalization), but the metadata *consumer* normalizes and identifies appropriate human-readable equivalents based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "``DOCUMENTATION`` becomes ``documentation``, which is rendered as ``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` (as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "" + +#: ../source/support.rst:5 +msgid "For support related to a specific project, see the links on the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "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/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "This tutorial has been removed since it is not related to packaging and was unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "This section covers the basics of how to install Python :term:`packages `." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "This section describes the steps to follow before installing other Python packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "Additionally, you'll need to make sure you have :ref:`pip` available. You can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "If ``pip`` isn't already installed, then first try to bootstrap it from the standard library:" +msgstr "" + +#: ../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:136 +msgid "Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +msgid "Run ``python get-pip.py``. [2]_ This will install or upgrade pip. Additionally, it may install :ref:`setuptools` and :ref:`wheel` if they're not installed already." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip is up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +msgid "Make sure you have the latest features and fixes, and support for the latest Python packaging specifications." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:172 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:174 +msgid "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:191 +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:198 +msgid "Creating Virtual Environments" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:200 +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:206 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:212 +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/tutorials/installing-packages.rst:216 +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:219 +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/installing-packages.rst:223 +msgid "Currently, there are two common tools for creating Python virtual environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:225 +msgid ":doc:`venv ` is available by default in Python 3.3 and later, and installs :ref:`pip` into created virtual environments in Python 3.4 and later (Python versions prior to 3.12 also installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:228 +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 installed into created virtual environments by default. Note that ``setuptools`` is no longer included by default starting with Python 3.12 (and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:233 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:235 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:251 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:267 +msgid "For more information, see the :doc:`venv ` docs or the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:270 +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)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:275 +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/installing-packages.rst:285 +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:292 +msgid "Use pip for Installing" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:294 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:300 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:302 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:310 +msgid "To install the latest version of \"SomeProject\":" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:324 +msgid "To install a specific version:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:338 +msgid "To install greater than or equal to one version and less than another:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:353 +msgid "To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:368 +msgid "In this case, this means to install any version \"==1.4.*\" version that's also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:373 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:375 +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 "" + +#: ../source/tutorials/installing-packages.rst:381 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:386 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:394 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:411 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:413 +msgid "To install :term:`packages ` that are isolated to the current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:428 +msgid "For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:432 +msgid "Note that the ``--user`` flag has no effect when inside a virtual environment - all installation commands will affect the virtual environment." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:435 +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:443 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:449 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:465 +msgid "Install a list of requirements specified in a :ref:`Requirements File `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:481 +msgid "Installing from VCS" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:483 +msgid "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/installing-packages.rst:505 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:507 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:521 +msgid "Search an additional index during install, in addition to :term:`PyPI `" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:537 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:540 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:557 +msgid "You can also install normally from src" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:572 +msgid "Installing from local archives" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:574 +msgid "Install a particular source archive file." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:588 +msgid "Install from a local directory containing archives (and don't check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:608 +msgid "Installing from other sources" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:610 +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/installing-packages.rst:622 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:624 +msgid "Find pre-release and development versions, in addition to stable versions. By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:640 +msgid "Installing \"Extras\"" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:642 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:665 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:674 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:679 +msgid "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/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "`PDM `_ for a modern Python package management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "`uv `__ for a single tool that covers the entire project management workflow, including dependency management, packaging, and publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "Creating the file :file:`__init__.py` is recommended because the existence of an :file:`__init__.py` file allows users to import the directory as a regular package, even if (as is the case in this tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above code block is the one that introduced support for :ref:`the new license metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) of Python your package works on 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:222 +msgid "``license`` is the :term:`SPDX license expression ` of your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "``license-files`` is the list of glob paths to the license files, relative to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "Open :file:`README.md` and enter the following content. You can customize this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "It's important for every :term:`Distribution Archive` uploaded to the Python Package Index to include a license. This tells users who install your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "Most build backends automatically include license files in packages. See your backend's documentation for more details. If you include the path to license in the ``license-files`` key of :file:`pyproject.toml`, and your build backend supports :pep:`639`, the file will be automatically included in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "If you have trouble installing these, see the :doc:`installing-packages` tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "Now run this command from the same directory where :file:`pyproject.toml` is located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "This command should output a lot of text and once completed should generate two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "Now that you are registered, you can use :ref:`twine` to upload the distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "You will be prompted for an API token. Use the token value, including the ``pypi-`` prefix. Note that the input will be hidden, so be sure to paste correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "Once uploaded, your package should be viewable on TestPyPI; for example: ``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "pip should install the package from TestPyPI and the output should look something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 ✨" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "Install your package from the real PyPI using ``python3 -m pip install [your-package]``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "At this point if you want to read more on packaging Python libraries here are some things you can do:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "Read about advanced configuration for your chosen build backend: `Hatchling `_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "Look at the :doc:`guides ` on this site for more advanced practical information, or the :doc:`discussions ` for explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "Consider packaging tools that provide a single command-line interface for project management and packaging, such as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" diff --git a/locales/mk/LC_MESSAGES/messages.po b/locales/mk/LC_MESSAGES/messages.po new file mode 100644 index 000000000..811cbb95a --- /dev/null +++ b/locales/mk/LC_MESSAGES/messages.po @@ -0,0 +1,26806 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# Kristijan Fremen Velkovski , 2022. +# "Kristijan \"Fremen\" Velkovski" , 2023. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: 2023-10-21 04:04+0000\n" +"Last-Translator: \"Kristijan \\\"Fremen\\\" Velkovski\" \n" +"Language-Team: Macedonian \n" +"Language: mk\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=2; plural=n==1 || n%10==1 ? 0 : 1;\n" +"X-Generator: Weblate 5.1\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "Придонеси на овој водич" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "Читајќи го водичот и коментирање" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "Проверување на нови придонеси" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "Проверување на постоечка содржина" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "Пишување на нова содржина" + +#: ../source/contribute.rst:14 +#, fuzzy +#| msgid "Translate the guide" +msgid "Translating the guide" +msgstr "Преведување на водичот" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "" + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "" + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "" + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:51 +#, fuzzy +#| msgid "Binary Distribution" +msgid "Provide complete source distributions" +msgstr "Бинарна Дистрибуција" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "" + +#: ../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 "Binary Distribution" +msgid "What is a source distribution?" +msgstr "Бинарна Дистрибуција" + +#: ../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 +msgid "What about eggs?" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python setup.py install``" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python -m pip install --editable .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:104 +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr "" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +msgid "Complete" +msgstr "" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +msgid "Versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +msgid "Calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +msgid "Other schemes" +msgstr "" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 ../source/flow.rst:143 +msgid "" +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../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 :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +#, fuzzy +#| msgid "Binary Distribution" +msgid "Distribution Archive" +msgstr "Бинарна Дистрибуција" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "Jajce(Egg)" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +msgid "Installed Project" +msgstr "" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +msgid "Project Root Directory" +msgstr "" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "" + +#: ../source/glossary.rst:257 +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:260 +msgid "Pyproject Metadata" +msgstr "" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +msgid "Pyproject Metadata Key" +msgstr "" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "" + +#: ../source/glossary.rst:344 +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:348 +msgid "Root License Directory" +msgstr "" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +msgid "Wheel Project" +msgstr "" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "" +"https://files.pythonhosted.org/packages/eb/" +"45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" +"sampleproject-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "" +"https://files.pythonhosted.org/packages/56/0a/" +"178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" +"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +msgid "" +"https://files.pythonhosted.org/packages/" +"63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" +"sampleproject_nomura-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +msgid "Creating the package" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +msgid "``pyproject.toml``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +msgid "Installing the package with ``pipx``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +msgid "Conclusion" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +msgid "1. Install twine" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +msgid "Dropping a Python version" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:108 +msgid "openSUSE" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:118 +msgid "Debian/Ubuntu and derivatives" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +msgid "Install packages in a virtual environment using pip and venv" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +msgid "Install packages using pip" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +msgid "Install extras" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +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/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python -m build``" +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:126 +msgid "``python -m build --no-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:127 +msgid "``python -m pip install --no-build-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../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 "" +"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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +msgid "Installation" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:233 +msgid "``appveyor-sample/build.cmd``" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:5 +msgid "Tool recommendations" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +msgid "Installing packages" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +#, fuzzy +#| msgid "Binary Distribution" +msgid "Building distributions" +msgstr "Бинарна Дистрибуција" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:313 +msgid "setuptools" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:317 +msgid "uv-build" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +msgid "`Kivy `_" +msgstr "" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "Subdirectory name" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +msgid "``licenses``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*object*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Schema version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "examples" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "version\\_info" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*number*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**implementation**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**flags**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**headers**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +msgid "Package Building" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +msgid ":ref:`Version `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +msgid "``toml``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +msgid "``dependency_groups``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +msgid "Installers" +msgstr "" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +msgid "Reference implementation in Python" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +msgid "Names and normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +msgid "Name normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +msgid "Project Status Markers" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +msgid "Installer semantics: none." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +msgid "Installer semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +msgid "``deprecated``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +msgid "``pylock.toml`` Specification" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +msgid "``lock-version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +msgid "**Required?**: yes" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +msgid "``environments``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +msgid "``dependency-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +msgid "``[[packages]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +msgid "``packages.version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +msgid "The version of the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +msgid "``[[packages.dependencies]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +msgid "The time the file was uploaded." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +msgid "``packages.index``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +msgid "``import-names``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +msgid "Legacy specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +msgid "Examples:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +msgid "Example:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +msgid "PyPA schemas" +msgstr "" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +msgid "Python Description Formats" +msgstr "" + +#: ../source/specifications/section-reproducible-environments.rst:3 +msgid "Reproducible Environments" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +msgid "Normalized Names" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +msgid "HTML Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +msgid "Project List" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +msgid "Project Detail" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +msgid "JSON Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +msgid "Content-Types" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +msgid "Version + Format Selection" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +msgid "Definitions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +msgid "Version scheme" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +msgid "Pre-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +msgid "Version epochs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +msgid "Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +msgid "Integer Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +msgid "Version exclusion" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +msgid "Well-known Project URLs in Metadata" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +msgid "Label normalization" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +msgid "Normalized" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"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/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "" + +#: ../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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "" + +#: ../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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" + +#~ msgid "Read about :doc:`/guides/packaging-binary-extensions`." +#~ msgstr "Прочитајте за :doc:`/guides/packaging-binary-extensions`." diff --git a/locales/mr/LC_MESSAGES/messages.po b/locales/mr/LC_MESSAGES/messages.po new file mode 100644 index 000000000..629b6e69e --- /dev/null +++ b/locales/mr/LC_MESSAGES/messages.po @@ -0,0 +1,26792 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# Prachi Joshi , 2025. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: 2025-01-25 14:18+0000\n" +"Last-Translator: Prachi Joshi \n" +"Language-Team: Marathi \n" +"Language: mr\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=2; plural=n != 1;\n" +"X-Generator: Weblate 5.10-dev\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "" + +#: ../source/contribute.rst:14 +msgid "Translating the guide" +msgstr "" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "" + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "" + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "" + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "" + +#: ../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 +msgid "What is a source distribution?" +msgstr "" + +#: ../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 +msgid "What about eggs?" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python setup.py install``" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python -m pip install --editable .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:104 +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr "" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +msgid "Complete" +msgstr "" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +msgid "Versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +msgid "Calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +msgid "Other schemes" +msgstr "" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 ../source/flow.rst:143 +msgid "" +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../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 :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +msgid "Installed Project" +msgstr "" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +msgid "Project Root Directory" +msgstr "" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "" + +#: ../source/glossary.rst:257 +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:260 +msgid "Pyproject Metadata" +msgstr "" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +msgid "Pyproject Metadata Key" +msgstr "" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "" + +#: ../source/glossary.rst:344 +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:348 +msgid "Root License Directory" +msgstr "" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +msgid "Wheel Project" +msgstr "" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "" +"https://files.pythonhosted.org/packages/eb/" +"45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" +"sampleproject-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "" +"https://files.pythonhosted.org/packages/56/0a/" +"178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" +"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +msgid "" +"https://files.pythonhosted.org/packages/" +"63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" +"sampleproject_nomura-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +msgid "Creating the package" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +msgid "``pyproject.toml``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +msgid "Installing the package with ``pipx``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +msgid "Conclusion" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +msgid "1. Install twine" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +msgid "Dropping a Python version" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:108 +msgid "openSUSE" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:118 +msgid "Debian/Ubuntu and derivatives" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +msgid "Install packages in a virtual environment using pip and venv" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +msgid "Install packages using pip" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +msgid "Install extras" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +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/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python -m build``" +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:126 +msgid "``python -m build --no-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:127 +msgid "``python -m pip install --no-build-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../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 "" +"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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +msgid "Installation" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:233 +msgid "``appveyor-sample/build.cmd``" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:5 +msgid "Tool recommendations" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +msgid "Installing packages" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +msgid "Building distributions" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:313 +msgid "setuptools" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:317 +msgid "uv-build" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +msgid "`Kivy `_" +msgstr "" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "Subdirectory name" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +msgid "``licenses``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*object*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Schema version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "examples" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "version\\_info" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*number*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**implementation**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**flags**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**headers**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +msgid "Package Building" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +msgid ":ref:`Version `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +msgid "``toml``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +msgid "``dependency_groups``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +msgid "Installers" +msgstr "" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +msgid "Reference implementation in Python" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +msgid "Names and normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +msgid "Name normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +msgid "Project Status Markers" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +msgid "Installer semantics: none." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +msgid "Installer semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +msgid "``deprecated``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +msgid "``pylock.toml`` Specification" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +msgid "``lock-version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +msgid "**Required?**: yes" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +msgid "``environments``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +msgid "``dependency-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +msgid "``[[packages]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +msgid "``packages.version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +msgid "The version of the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +msgid "``[[packages.dependencies]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +msgid "The time the file was uploaded." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +msgid "``packages.index``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +msgid "``import-names``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +msgid "Legacy specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +msgid "Examples:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +msgid "Example:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +msgid "PyPA schemas" +msgstr "" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +msgid "Python Description Formats" +msgstr "" + +#: ../source/specifications/section-reproducible-environments.rst:3 +msgid "Reproducible Environments" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +msgid "Normalized Names" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +msgid "HTML Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +msgid "Project List" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +msgid "Project Detail" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +msgid "JSON Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +msgid "Content-Types" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +msgid "Version + Format Selection" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +msgid "Definitions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +msgid "Version scheme" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +msgid "Pre-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +msgid "Version epochs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +msgid "Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +msgid "Integer Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +msgid "Version exclusion" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +msgid "Well-known Project URLs in Metadata" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +msgid "Label normalization" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +msgid "Normalized" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"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/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "" + +#: ../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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "" + +#: ../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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" diff --git a/locales/pl/LC_MESSAGES/messages.po b/locales/pl/LC_MESSAGES/messages.po new file mode 100644 index 000000000..9d6464797 --- /dev/null +++ b/locales/pl/LC_MESSAGES/messages.po @@ -0,0 +1,26835 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# Maciej Olko , 2024, 2025, 2026. +# Stan Ulbrych , 2025. +# Michał p Biegluk python router , 2025, 2026. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: 2026-02-11 07:09+0000\n" +"Last-Translator: Maciej Olko \n" +"Language-Team: Polish \n" +"Language: pl\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=(n==1 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 " +"|| n%100>=20) ? 1 : 2);\n" +"X-Generator: Weblate 5.16-dev\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "Współtwórz ten przewodnik" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "|PyPUG| wita kontrybutorów! Istnieje wiele sposobów na pomoc, w tym:" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "Czytanie przewodnika i dawanie feedbacku" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "Review nowych zmian" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "Poprawianie istniejącej zawartości" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "Pisanie nowych treści" + +#: ../source/contribute.rst:14 +msgid "Translating the guide" +msgstr "Tłumaczenie przewodnika" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" +"Większość pracy nad |pypug| odbywa się w `repozytorium projektu na " +"GitHubie`__. Aby zacząć, sprawdź listę `otwartych zgłoszeń`__ i `pull " +"requestów`__. Jeśli planujesz napisać lub edytować ten przewodnik, " +"przeczytaj :ref:`przewodnik po stylach `." + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" +"Biorąc udział w projekcie |PyPUG|, zobowiązujesz się do przestrzegania " +"Kodeksu postępowania PSF__" + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "Typ dokumentacji" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" +"Projekt ten składa się z czterech różnych typów dokumentacji z konkretnymi " +"celami. Projekt jest inspirowany procesem `Diátaxis'_ dla stworzenia " +"dokumentacji jakości. Po założeniu nowych dodatków do projektu zadaje " +"odpowiedni typ dokumentacji." + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "Tutoriale" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" +"Tutoriale koncentrują się na uczeniu czytelnika nowych koncepcji poprzez " +"realizację celów. Nie zawierają zbędnych informacji i ostrzeżeń. `example " +"tutorial-style document`_." + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "Przewodniki" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" +"Przewodniki koncentrują się na wykonaniu konkretnego zadania i mogą zakładać " +"pewien poziom wiedzy wstępnej. Są podobne do samouczków, ale mają wąski i " +"jasny zakres tematyczny oraz mogą zawierać wiele ostrzeżeń i dodatkowych " +"informacji w razie potrzeby. Mogą również omawiać różne podejścia do " +"wykonania zadania. :doc:`example guide-style document `." + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "Dyskusje" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "" + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "" + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "" + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "" + +#: ../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 +msgid "What is a source distribution?" +msgstr "" + +#: ../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 +msgid "What about eggs?" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python setup.py install``" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python -m pip install --editable .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:104 +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr "" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +msgid "Complete" +msgstr "" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +msgid "Versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +msgid "Calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +msgid "Other schemes" +msgstr "" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 ../source/flow.rst:143 +msgid "" +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../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 :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +msgid "Installed Project" +msgstr "" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +msgid "Project Root Directory" +msgstr "" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "" + +#: ../source/glossary.rst:257 +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:260 +msgid "Pyproject Metadata" +msgstr "" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +msgid "Pyproject Metadata Key" +msgstr "" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "" + +#: ../source/glossary.rst:344 +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:348 +msgid "Root License Directory" +msgstr "" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +msgid "Wheel Project" +msgstr "" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "" +"https://files.pythonhosted.org/packages/eb/" +"45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" +"sampleproject-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "" +"https://files.pythonhosted.org/packages/56/0a/" +"178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" +"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +msgid "" +"https://files.pythonhosted.org/packages/" +"63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" +"sampleproject_nomura-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +msgid "Creating the package" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +msgid "``pyproject.toml``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +msgid "Installing the package with ``pipx``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +msgid "Conclusion" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +msgid "1. Install twine" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +msgid "Dropping a Python version" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:108 +msgid "openSUSE" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:118 +msgid "Debian/Ubuntu and derivatives" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +msgid "Install packages in a virtual environment using pip and venv" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +msgid "Install packages using pip" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +msgid "Install extras" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +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/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python -m build``" +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:126 +msgid "``python -m build --no-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:127 +msgid "``python -m pip install --no-build-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../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 "" +"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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +msgid "Installation" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" +"Aby użyć Appveyor do zbudowania kół Windows dla swojego projektu, musisz " +"posiadać konto w tej usłudze. Instrukcje dotyczące zakładania konta znajdują " +"się w dokumentacji Appveyor `__. Bezpłatny " +"poziom konta jest w pełni wystarczający dla projektów open source." + +#: ../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 umożliwia integrację z `GitHub`_ i `Bitbucket`_, więc jeśli Twój " +"projekt jest hostowany w jednej z tych dwóch usług, skonfigurowanie " +"integracji Appveyor jest proste." + +#: ../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 "" +"Po skonfigurowaniu konta Appveyor i dodaniu projektu, Appveyor automatycznie " +"zbuduje go po każdym zatwierdzeniu. To zachowanie będzie znane użytkownikom " +"Travisa." + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "Dodawanie obsługi Appveyor do projektu" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" +"Aby zdefiniować sposób, w jaki Appveyor powinien zbudować Twój projekt, " +"musisz dodać do niego plik :file:`appveyor.yml`. Szczegółowe informacje na " +"temat zawartości pliku znajdują się w dokumentacji Appveyor. Ten przewodnik " +"zawiera informacje niezbędne do skonfigurowania kompilacji Wheel." + +#: ../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 "" +"Appveyor domyślnie zawiera wszystkie zestawy narzędzi kompilatora potrzebne " +"do budowania rozszerzeń dla Pythona. W Pythonie 2.7, 3.5+ oraz 32-bitowych " +"wersjach 3.3 i 3.4 narzędzia te działają od razu. Jednak w przypadku 64-" +"bitowych wersji Pythona 3.3 i 3.4 wymagana jest niewielka dodatkowa " +"konfiguracja, aby distutils wiedział, gdzie znaleźć kompilatory 64-bitowe. " +"(Od wersji 3.5 używana wersja programu Visual Studio zawiera kompilatory 64-" +"bitowe bez konieczności dodatkowej konfiguracji)." + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "appveyor.yml" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:233 +msgid "``appveyor-sample/build.cmd``" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:5 +msgid "Tool recommendations" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +msgid "Installing packages" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +msgid "Building distributions" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:313 +msgid "setuptools" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:317 +msgid "uv-build" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +msgid "`Kivy `_" +msgstr "" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "Subdirectory name" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +msgid "``licenses``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*object*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Schema version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "examples" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "version\\_info" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*number*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**implementation**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**flags**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**headers**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +msgid "Package Building" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +msgid ":ref:`Version `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +msgid "``toml``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +msgid "``dependency_groups``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +msgid "Installers" +msgstr "" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +msgid "Reference implementation in Python" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +msgid "Names and normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +msgid "Name normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +msgid "Project Status Markers" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +msgid "Installer semantics: none." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +msgid "Installer semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +msgid "``deprecated``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +msgid "``pylock.toml`` Specification" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +msgid "``lock-version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +msgid "**Required?**: yes" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +msgid "``environments``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +msgid "``dependency-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +msgid "``[[packages]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +msgid "``packages.version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +msgid "The version of the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +msgid "``[[packages.dependencies]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +msgid "The time the file was uploaded." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +msgid "``packages.index``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +msgid "``import-names``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +msgid "Legacy specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +msgid "Examples:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +msgid "Example:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +msgid "PyPA schemas" +msgstr "" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +msgid "Python Description Formats" +msgstr "" + +#: ../source/specifications/section-reproducible-environments.rst:3 +msgid "Reproducible Environments" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +msgid "Normalized Names" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +msgid "HTML Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +msgid "Project List" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +msgid "Project Detail" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +msgid "JSON Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +msgid "Content-Types" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +msgid "Version + Format Selection" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +msgid "Definitions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +msgid "Version scheme" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +msgid "Pre-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +msgid "Version epochs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +msgid "Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +msgid "Integer Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +msgid "Version exclusion" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +msgid "Well-known Project URLs in Metadata" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +msgid "Label normalization" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +msgid "Normalized" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"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/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "" + +#: ../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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "" + +#: ../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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" diff --git a/locales/pt_BR/LC_MESSAGES/messages.po b/locales/pt_BR/LC_MESSAGES/messages.po new file mode 100644 index 000000000..45cf12757 --- /dev/null +++ b/locales/pt_BR/LC_MESSAGES/messages.po @@ -0,0 +1,37004 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# Rafael Fontenelle , 2021, 2022, 2023, 2024, 2025. +# meowmeowmeowcat , 2021. +# miiguel , 2022. +# Felipe Nogueira , 2023. +# Kalingth , 2024. +# Alefsander Ribeiro Nascimento , 2024. +# Beta 46 , 2025. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: 2025-08-07 00:01+0000\n" +"Last-Translator: Rafael Fontenelle \n" +"Language-Team: Portuguese (Brazil) \n" +"Language: pt_BR\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=2; plural=n > 1;\n" +"X-Generator: Weblate 5.13-dev\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "Contribua para este guia" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "" +"O |PyPUG| dá as boas-vindas aos(às) contribuidores(as)! Existem muitas " +"maneiras de ajudar, incluindo:" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "Lendo o guia e dando feedback" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "Revisando novas contribuições" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "Revisando conteúdo existente" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "Escrevendo novo conteúdo" + +#: ../source/contribute.rst:14 +msgid "Translating the guide" +msgstr "Traduzindo o guia" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" +"A maior parte do trabalho no |PyPUG| ocorre no `repositório GitHub do " +"projeto`__. Para começar, verifique a lista de `issues abertos`__ e `pull " +"requests`__. Se você está planejando escrever ou editar o guia, leia " +"o :ref:`guia de estilo `." + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" +"Ao contribuir para o |PyPUG|, espera-se que você siga o `Código de " +"Conduta`__ da PSF." + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "Tipos de documentação" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" +"Este projeto consiste em quatro tipos de documentação distintos com " +"finalidades específicas. O projeto aspira seguir a o `processo Diátaxis`_ " +"para criar documentação de qualidade. Ao propor novas adições ao projeto, " +"escolha o tipo de documentação apropriado." + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "Tutoriais" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" +"Os tutoriais são focados em ensinar ao leitor novos conceitos através da " +"realização de um objetivo. Eles são guias passo a passo opinativos. Eles não " +"incluem avisos ou informações estranhas. `Exemplo de documento no estilo " +"tutorial`_." + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "Guias" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" +"Os guias são focados em realizar uma tarefa específica e podem assumir algum " +"nível de conhecimento pré-requisito. Eles são semelhantes aos tutoriais, mas " +"têm um foco estreito e claro e podem fornecer muitas advertências e " +"informações adicionais, conforme necessário. Eles também podem discutir " +"várias abordagens para realizar a tarefa. :doc:`Exemplo de documento no " +"estilo guia `." + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "Discussões" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" +"As discussões são focadas em compreensão e informação. Eles exploram um " +"tópico específico sem um objetivo específico em mente. :doc:`Exemplo de " +"documento no estilo discussão `." + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "Especificações" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" +"As especificações são documentação de referência focada na documentação " +"abrangente de uma interface acordada para interoperabilidade entre " +"ferramentas de empacotamento. :doc:`Exemplo de documento no estilo " +"especificação `." + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "Traduções" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" +"Usamos `Weblate`_ para gerenciar as traduções deste projeto. Visite o " +"projeto `packaging.python.org`_ no Weblate para contribuir." + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" +"Se você está tendo problemas enquanto trabalha nas traduções, relate o " +"problema no `GitHub`_." + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" +"Qualquer tradução deste projeto deve seguir a `sintaxe reStructuredText`_." + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "Adicionando um idioma" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" +"Se o seu idioma não estiver listado em `packaging.python.org`_, clique no " +"botão :guilabel:`Iniciar nova tradução` na parte inferior da lista de " +"idiomas e adicione o idioma que deseja traduzir." + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "Seguindo a sintaxe reStructuredText" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" +"Se você não está familiarizado com a sintaxe reStructuredText (RST), leia " +"`este guia`_ antes de traduzir no Weblate." + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "**Não traduza o texto em referências diretamente**" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "Ao traduzir o texto em referências, não os traduza diretamente." + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "Errado: traduzir o texto a seguir diretamente:" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" +"Correto: traduzir o texto a seguir em seu próprio idioma e adicionar a " +"referência original:" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "Construindo o guia localmente" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" +"Embora não seja necessário contribuir, pode ser útil construir este guia " +"localmente para testar suas alterações. Para construir este guia localmente, " +"você precisará:" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" +":doc:`Nox `. Você pode instalar ou atualizar o nox usando o " +"``pip``:" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" +"Python 3.11. Nossos scripts de construção são geralmente testados com Python " +"3.11. Consulte o :doc:`Guia do mochileiro para as instruções de instalação " +"do Python ` para instalar o Python 3.11 " +"em seu sistema operacional." + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" +"Para construir o guia, execute o seguinte comando shell na pasta raiz do " +"projeto:" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" +"Após a conclusão do processo, você pode encontrar a saída HTML no diretório " +"``./build/html``. Você pode abrir o arquivo ``index.html`` para ver o guia " +"no navegador web, mas é recomendado servir o guia usando um servidor HTTP." + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" +"Você pode construir o guia e exibi-lo por meio de um servidor HTTP usando o " +"seguinte comando:" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "O guia poderá ser navegado em http://localhost:8000." + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "Onde o guia é disponibilizado" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" +"O guia é disponibilizado via ReadTheDocs e a configuração está em https://" +"readthedocs.org/projects/python-packaging-user-guide/.. É servido a partir " +"de um domínio personalizado e guardado por Fast.ly." + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "Guia de estilo" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" +"Este guia de estilo contém recomendações de como você deve escrever o |" +"PyPUG|. Antes de começar a escrever, revise-o. Seguindo o guia de estilo, " +"suas contribuições ajudarão a formar um todo coeso e tornar mais fácil para " +"que suas contribuições sejam aceitas no projeto." + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "Propósito" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" +"O objetivo do |PyPUG| é ser o recurso autorizado sobre como empacotar, " +"publicar e instalar projetos Python usando as ferramentas atuais." + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "Escopo" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" +"O guia destina-se a responder a perguntas e resolver problemas com " +"recomendações precisas e focadas." + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" +"O guia não pretende ser abrangente e não pretende substituir a documentação " +"de projetos individuais. Por exemplo, pip tem dezenas de comandos, opções e " +"configurações. A documentação do pip descreve cada um deles em detalhes, " +"enquanto este guia descreve apenas as partes do pip que são necessárias para " +"concluir as tarefas específicas descritas neste guia." + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "Público-alvo" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "" +"O público-alvo deste guia é qualquer pessoa que use Python com pacotes." + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" +"Não se esqueça de que a comunidade Python é grande e acolhedora. Os leitores " +"podem não compartilhar sua idade, sexo, educação, cultura e muito mais, mas " +"eles merecem aprender sobre empacotamento tanto quanto você." + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" +"Em particular, tenha em mente que nem todas as pessoas que usam Python se " +"consideram programadores. O público deste guia inclui astrônomos, pintores " +"ou estudantes, bem como desenvolvedores de software profissionais." + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "Voz e tom" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" +"Ao escrever este guia, esforce-se para escrever com uma voz que seja " +"acessível e humilde, mesmo que você tenha todas as respostas." + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" +"Imagine que você está trabalhando em um projeto Python com alguém que sabe " +"ser inteligente e habilidoso. Você gosta de trabalhar com eles e eles gostam " +"de trabalhar com você. Essa pessoa fez uma pergunta e você sabe a resposta. " +"Como você responde? *É assim* que você deve escrever este guia." + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" +"Aqui está uma verificação rápida: tente ler em voz alta para ter uma noção " +"da voz e do tom de sua escrita. Parece algo que você diria ou parece que " +"você está encenando um papel ou fazendo um discurso? Sinta-se à vontade para " +"usar contrações e não se preocupe em seguir regras gramaticais complicadas. " +"Você tem permissão para encerrar uma frase em uma preposição, se for assim " +"que deseja encerrá-la." + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" +"Ao escrever o guia, ajuste seu tom de acordo com a seriedade e a dificuldade " +"do tópico. Se você estiver escrevendo um tutorial introdutório, não há " +"problema em fazer uma piada, mas se estiver cobrindo uma recomendação de " +"segurança sensível, convém evitar piadas completamente." + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "Convenções e mecânicas" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "**Escreva para o leitor**" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" +"Ao dar recomendações ou etapas a serem seguidas, dirija-se ao leitor como " +"*você* ou use o humor imperativo." + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "Errado: Para instalá-lo, o usuário executa…" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "Certo: Você pode instalá-lo executando…" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "Certo: Para instalá-lo, execute…" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "**Presuma**" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" +"Evite fazer suposições não declaradas. Ler na web significa que qualquer " +"página do guia pode ser a primeira página do guia que o leitor vê. Se você " +"vai fazer suposições, diga quais suposições você vai fazer." + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "**Faça uso generoso de referência cruzada**" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" +"Na primeira vez que você mencionar uma ferramenta ou prática, coloque um " +"link para a parte do guia que a cobre ou para um documento relevante em " +"outro lugar. Economize uma pesquisa ao leitor." + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "**Respeite as práticas de nomenclatura**" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" +"Ao nomear ferramentas, sites, pessoas e outros nomes próprios, use a " +"capitalização de sua preferência." + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "Errado: Pip usa…" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "Certo: pip usa…" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "Errado: …hospedado no github." + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "Certo: …hospedado no GitHub." + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "**Use um estilo de gênero neutro**" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" +"Frequentemente, você se dirigirá ao leitor diretamente com *you*, *your* e " +"*yours*. Caso contrário, use pronomes de gênero neutro *they*, *their* e " +"*theirs* ou evite os pronomes completamente." + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "Errado: A maintainer uploads the file. Then he…" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "Certo: A maintainer uploads the file. Then they…" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "Certo: A maintainer uploads the file. Then the maintainer…" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "**Títulos**" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" +"Escreva títulos que usem palavras que o leitor esteja procurando. Uma boa " +"maneira de fazer isso é fazer com que o cabeçalho responda a uma pergunta " +"implícita. Por exemplo, um leitor pode querer saber *How do I install " +"MyLibrary?*, de forma que um bom título pode ser *Install MyLibrary*." + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" +"Nos cabeçalhos das seções, use letras maiúsculas e minúsculas. Em outras " +"palavras, escreva os cabeçalhos da mesma forma que escreveria uma frase " +"típica." + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "Errado: Things You Should Know About Python" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "Certo: Things you should know about Python" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "**Números**" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" +"No corpo do texto, escreva os números de um a nove como palavras. Para " +"outros números ou números nas tabelas, use numerais." + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "Fazendo deploy de aplicações Python" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "Status da página" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "Incompleta" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "Última revisão" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "2021-8-24" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "Visão geral" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "Oferecendo suporte a várias plataformas de hardware" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "Empacotamento de sistema operacional e instaladores" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "Windows" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "Pynsist" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" +"`Pynsist `__ é uma ferramenta que agrupa " +"programas Python junto com o interpretador Python em um único instalador " +"baseado em NSIS. Na maioria dos casos, o empacotamento requer apenas que o " +"usuário escolha uma versão do interpretador Python e declare as dependências " +"do programa. A ferramenta baixa o interpretador Python especificado para " +"Windows e o empacota com todas as dependências em um único instalador " +"executável do Windows." + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" +"O programa instalado pode ser iniciado a partir de um atalho que o " +"instalador adiciona ao menu iniciar. Ele usa um interpretador Python " +"instalado em seu diretório de aplicação, independente de qualquer outra " +"instalação Python no computador." + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" +"Uma grande vantagem do Pynsist é que os pacotes do Windows podem ser " +"construídos no Linux. Existem vários exemplos para diferentes tipos de " +"programas (console, GUI) na :any:`documentação `. A " +"ferramenta é lançada sob a licença do MIT." + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "Pacotes de aplicações" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "py2exe" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" +"`py2exe `__ é uma extensão do distutils " +"que permite construir programas executáveis autônomos Windows (32 bits e 64 " +"bits) a partir de scripts Python. Versões Python incluídas no ciclo de " +"desenvolvimento oficial são suportadas (consulte `Status dos ramos do " +"Python`__). py2exe pode construir executáveis de console e executáveis de " +"janelas (GUI). A construção de serviços do Windows e servidores DLL/EXE COM " +"podem funcionar, mas não são ativamente suportados. A extensão distutils é " +"lançada sob a licença MIT e Mozilla Public License 2.0." + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "macOS" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "py2app" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" +"`py2app `__ é um comando Python do " +"setuptools que permitirá que você crie pacotes e plug-ins de aplicações " +"autônomas para o macOS a partir de scripts Python. Observe que o py2app DEVE " +"ser usado no macOS para criar aplicações; ele não pode criar aplicação do " +"Mac em outras plataformas. py2app é lançado sob a licença MIT." + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "Unix (incluindo Linux e macOS)" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "pex" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" +"`pex `__ é uma biblioteca para gerar " +"arquivos .pex (Python EXecutáveis) que são ambientes Python executáveis no " +"espírito de virtualenvs. pex é uma expansão das ideias descritas " +"na :pep:`441` e torna a implantação de aplicações Python tão simples quanto " +"o cp. Os arquivos pex podem até incluir várias distribuições específicas da " +"plataforma Python, o que significa que um único arquivo pex pode ser " +"portátil entre Linux e macOS. pex é lançado sob a licença Apache 2.0." + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "Gerenciamento de configuração" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "Pacote de distribuição vs. pacote de importação" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" +"Alguns conceitos diferentes são comumente referidos pela palavra \"pacote\". " +"Esta página esclarece as diferenças entre dois significados distintos, mas " +"relacionados no empacotamento do Python , \"pacote de distribuição\" e " +"\"pacote de importação\"." + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "O que é um pacote de distribuição?" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" +"Um pacote de distribuição é um software que você pode instalar. Na maioria " +"das vezes, isso é sinônimo de \"projeto\". Quando você digita ``pip install " +"pkg``, ou quando você escreve ``dependencies = [\"pkg\"]`` em seu " +"``pyproject.toml``, ``pkg`` é o nome de um pacote de distribuição. Quando " +"você pesquisa ou navega no PyPI_, a fonte centralizada mais conhecida para " +"instalar Python bibliotecas e ferramentas, o que você vê é uma lista de " +"pacotes de distribuição. Alternativamente, o termo \"pacote de " +"distribuição\" pode ser usado para se referir a um arquivo específico que " +"contém uma determinada versão de um projeto." + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" +"Note que no mundo Linux, um \"pacote de distribuição\", mais comumente " +"abreviado como \"pacote de distro\" (em inglês, *distro package*) ou apenas " +"\"pacote\", é algo fornecido pelo gerenciador de pacotes do sistema da " +"\"distribuição Linux `_, que é um significado diferente." + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "O que é um pacote de importação?" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" +"Um pacote de importação é um módulo Python. Assim, quando você escreve " +"``import pkg`` ou ``from pkg import func`` em seu código Python, ``pkg`` é o " +"nome de um pacote de importação. Mais precisamente, os pacotes de importação " +"são módulos especiais Python que podem conter submódulos. Por exemplo, o " +"pacote ``numpy`` contém módulos como ``numpy.linalg`` e ``numpy.fft``. " +"Normalmente, um pacote de importação é um diretório no sistema de arquivos, " +"contendo módulos como arquivos ``.py`` e subpacotes como subdiretórios." + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" +"Você pode usar um pacote de importação assim que tiver instalado um pacote " +"de distribuição que o fornece." + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" +"Quais são as conexões entre pacotes de distribuição e pacotes de importação?" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" +"Na maioria das vezes, um pacote de distribuição fornece um único pacote de " +"importação (ou módulo de não embalagem), com um nome correspondente. Por " +"exemplo, ``pip install numpy`` permite que você importe usando ``import " +"numpy``." + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" +"No entanto, esta é apenas uma convenção. PyPI e outros índices de pacotes " +"*não impõe nenhuma relação* entre o nome de um pacote de distribuição e os " +"pacotes de importação que ele fornece. (Uma consequência disso é que você " +"não pode instalar cegamente o pacote PyPI ``foo`` se você vir ``import " +"foo``; isso pode instalar um pacote não intencional, e potencialmente até " +"mesmo malicioso.)" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" +"Um pacote de distribuição pode fornecer um pacote de importação com um nome " +"diferente. Um exemplo disso é a popular biblioteca Pillow_ para " +"processamento de imagens. Seu nome do pacote de distribuição é ``Pillow``, " +"mas fornece o pacote de importação ``PIL``. Isto é por razões históricas: " +"Pillow começou como um fork da biblioteca PIL, assim manteve o nome de " +"importação ``PIL`` para que os usuários PIL existentes pudessem mudar para o " +"Pillow com pouco esforço. Mais geralmente, um fork de uma biblioteca " +"existente é uma razão comum para diferentes nomes entre o pacote de " +"distribuição e o pacote de importação." + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" +"Em um determinado índice de pacotes (como PyPI), nomes de pacotes de " +"distribuição devem ser únicos. Por outro lado, os pacotes de importação não " +"têm tal exigência. Os pacotes de importação com o mesmo nome podem ser " +"fornecidos por vários pacotes de distribuição. Novamente, forks são uma " +"razão comum para isso." + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" +"Por outro lado, um pacote de distribuição pode fornecer vários pacotes de " +"importação, embora isso seja menos comum. Um exemplo é o pacote de " +"distribuição attrs_, que fornece um pacote de importação ``attrs`` com uma " +"API mais recente, e um pacote de importação ``attr`` com uma API mais " +"antiga, mas suportada." + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" +"Qual a comparação de nomes de pacotes de distribuição e de nomes de pacotes " +"de importação?" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" +"Os pacotes de importação devem ter identificadores válidos do Python como " +"seu nome (as :ref:`regras exatas ` são encontradas na " +"documentação do Python) [#non-identifier-mod-name]_. Em particular, eles " +"usam sublinhado ``_`` como separador de palavras e eles são sensíveis a " +"casos." + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" +"Por outro lado, os pacotes de distribuição podem usar hífenes ``-`` ou " +"sublinhados ``_``. Eles também podem conter pontos ``.``, que às vezes é " +"usado para empacotar um subpacote de um :ref:`pacote de espaço de nomes " +"`. Para a maioria dos fins, eles não " +"diferenciam letras maiúsculas de minúsculas nem ``-`` de ``_``. Por exemplo, " +"``pip install Awesome_Package`` é o mesmo que ``pip install awesome-" +"package`` (as regras precisas são dadas na :ref:`especificação de " +"normalização de nome `)." + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" +"Embora seja tecnicamente possível importar pacotes/módulos que não têm um " +"identificador válido Python como seu nome, usando :doc:`importlib " +"`, isso é extremamente raro e fortemente " +"desencorajado." + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "Oferecendo suporte para empacotamento em downstream" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "Esboço" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "2025-?" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" +"Embora o PyPI e as ferramentas de empacotamento Python, como :ref:`pip`, " +"sejam os principais meios de distribuição de pacotes Python, eles também são " +"frequentemente disponibilizados como parte de outros ecossistemas de " +"empacotamento. Esses esforços de reempacotamento são chamados coletivamente " +"de empacotamento *downstream* (seus próprios esforços são chamados de " +"empacotamento *upstream*) e incluem projetos como distribuições Linux, " +"Conda, Homebrew e MacPorts. Geralmente, eles visam fornecer suporte " +"aprimorado para casos de uso que não podem ser tratados apenas por " +"ferramentas de empacotamento Python, como integração nativa com um sistema " +"operacional específico ou compatibilidade garantida com versões específicas " +"de software não Python." + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" +"Esta discussão tenta explicar como o empacotamento downstream geralmente é " +"feito e quais desafios adicionais os empacotadores downstream normalmente " +"enfrentam. O objetivo é fornecer algumas diretrizes opcionais que os " +"mantenedores do projeto podem optar por seguir, o que ajuda a tornar o " +"empacotamento downstream *significativamente* mais fácil (sem impor grandes " +"problemas de manutenção ao projeto upstream). Observe que esta não é uma " +"proposta do tipo \"tudo ou nada\" — qualquer coisa que os mantenedores " +"upstream possam fazer é útil, mesmo que seja apenas uma pequena parte. Os " +"mantenedores downstream também estão dispostos a preparar patches para " +"resolver esses problemas. Mesclar esses patches pode ser muito útil, pois " +"elimina a necessidade de diferentes downstreams carregarem e continuarem " +"rebaseando os mesmos patches, além do risco de aplicar soluções " +"inconsistentes ao mesmo problema." + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" +"Estabelecer um bom relacionamento entre mantenedores de software e " +"empacotadores downstream pode trazer benefícios mútuos. Os downstreams " +"geralmente estão dispostos a compartilhar sua experiência, tempo e hardware " +"para aprimorar seu pacote. Às vezes, eles estão em melhor posição para ver " +"como seu pacote é usado na prática e fornecer informações sobre suas " +"relações com outros pacotes que, de outra forma, exigiriam um esforço " +"significativo para serem obtidas. Os empacotadores geralmente conseguem " +"encontrar bugs antes que seus usuários os encontrem em produção, fornecem " +"relatórios de bugs de boa qualidade e fornecem patches sempre que possível. " +"Por exemplo, eles são regularmente ativos para garantir que os pacotes que " +"redistribuem sejam atualizados para quaisquer problemas de compatibilidade " +"que surjam quando uma nova versão do Python é lançada." + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" +"Observe que as construções downstream incluem não apenas a redistribuição " +"binária, mas também construções de código-fonte feitas em sistemas de " +"usuários (em distribuições que priorizam o código-fonte, como o Gentoo " +"Linux, por exemplo)." + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "Forneça distribuições fonte completas" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "Por que?" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" +"A grande maioria dos empacotadores downstream prefere construir pacotes a " +"partir do código-fonte, em vez de usar os pacotes binários fornecidos pelo " +"upstream. Em alguns casos, o uso do código-fonte é realmente necessário para " +"que o pacote seja incluído na distribuição. Isso também se aplica a pacotes " +"Python puros que fornecem rodas universais. Os motivos para usar " +"distribuições de código-fonte podem incluir:" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "Ser possível auditar o código-fonte de todos os pacotes." + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "Ser capaz de executar o conjunto de testes e construir a documentação." + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" +"Ser capaz de aplicar patches facilmente, incluindo fazer backporting de " +"commits do repositório do projeto e enviar patches de volta ao projeto." + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" +"Ser capaz de construir em uma plataforma específica que não é coberta por " +"construções upstream." + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" +"Ser capaz de construir em versões específicas de bibliotecas do sistema." + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "Term um processo de construção consistente em todos os pacotes Python." + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" +"Enquanto é possível construir pacotes através do repositório Git, há razões " +"importantes pelas quais é incentivado prover um arquivo estático:" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" +"Obter um único arquivo costuma ser mais eficiente, confiável e com melhor " +"suporte do que, por exemplo, usar um clone do Git. Isso pode ajudar usuários " +"com baixa conectividade com a internet." + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" +"Os downstreams costumam usar hashes para verificar a autenticidade dos " +"arquivos fonte em construções subsequentes, o que exige que eles permaneçam " +"idênticos bit a bit ao longo do tempo. Por exemplo, arquivos Git gerados " +"automaticamente não garantem isso, pois os dados compactados podem mudar se " +"o gzip for atualizado no servidor." + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" +"Arquivos compactados podem ser espelhados, reduzindo o uso de largura de " +"banda tanto no upstream quanto no downstream. As construções podem ser " +"executadas posteriormente em ambientes com firewall ou offline, que só podem " +"acessar os arquivos fonte fornecidos pelo mirror local ou redistribuídos " +"anteriormente." + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" +"Publicar explicitamente arquivos compactados pode garantir que quaisquer " +"dependências nos metadados do sistema de controle de versão sejam resolvidas " +"ao criar o arquivo fonte. Por exemplo, arquivos Git gerados automaticamente " +"omitem todas as informações da tag de commit, o que pode resultar em " +"detalhes de versão incorretos nas compilações resultantes." + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "Como?" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" +"O ideal é que **um arquivo de distribuição de código-fonte publicado no PyPI " +"inclua todos os arquivos do repositório Git do pacote** que são necessários " +"para construir o pacote em si, executar seu conjunto de testes, construir e " +"instalar sua documentação e quaisquer outros arquivos que possam ser úteis " +"para usuários finais, como conclusões de shell, arquivos de suporte do " +"editor e assim por diante." + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" +"Este ponto se aplica apenas aos arquivos pertencentes ao próprio pacote. O " +"processo de empacotamento downstream, assim como os gerenciadores de pacotes " +"Python, provisionará as dependências Python, ferramentas de sistema e " +"bibliotecas externas necessárias para o seu pacote e seus scripts de " +"compilação. No entanto, os arquivos que listam essas dependências (por " +"exemplo, arquivos ``requirements*.txt``) também devem ser incluídos para " +"ajudar os downstreams a determinar as dependências necessárias e verificar " +"se há alterações nelas." + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" +"Alguns projetos apresentam preocupações relacionadas aos gerenciadores de " +"pacotes Python que utilizam distribuições de código-fonte do PyPI. Eles não " +"desejam aumentar seu tamanho com arquivos que não são usados por essas " +"ferramentas, ou não desejam publicar distribuições de código-fonte, pois " +"elas permitem um fallback problemático ou totalmente não funcional para a " +"construção do projeto específico a partir do código-fonte. Nesses casos, um " +"bom meio-termo pode ser publicar um arquivo de código-fonte separado para " +"uso posterior em outro lugar, por exemplo, anexando-o a uma versão do " +"GitHub. Como alternativa, arquivos grandes, como dados de teste, podem ser " +"divididos em arquivos separados." + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" +"Por outro lado, alguns projetos (NumPy_, por exemplo) decidem incluir testes " +"em seus pacotes instalados. Isso tem a vantagem adicional de permitir que os " +"usuários executem testes após a instalação, por exemplo, para verificar " +"regressões após a atualização de uma dependência. Outra abordagem é dividir " +"os testes ou os dados de teste em um pacote Python separado. Essa abordagem " +"foi adotada pelo projeto cryptography_, com os grandes vetores de teste " +"sendo divididos no pacote cryptography-vectors_." + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" +"Uma boa ideia é usar sua distribuição de código-fonte no fluxo de trabalho " +"de lançamento. Por exemplo, a ferramenta :ref:`build` faz exatamente isso — " +"primeiro cria uma distribuição de código-fonte e, em seguida, a utiliza para " +"criar uma wheel. Isso garante que a distribuição de código-fonte realmente " +"funcione e que ela não instale acidentalmente menos arquivos do que as " +"wheels oficiais." + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" +"O ideal é usar também a distribuição fonte para executar testes, compilar " +"documentação e assim por diante, ou adicionar testes específicos para " +"garantir que todos os arquivos necessários foram realmente incluídos. É " +"compreensível que isso exija mais esforço, então não há problema em não " +"fazer isso — os empacotadores posteriores reportarão imediatamente quaisquer " +"arquivos ausentes." + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "Não utilize a internet durante o processo de construção" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" +"As construções downstream são frequentemente realizadas em ambientes " +"isolados, sem acesso à internet. Os códigos-fonte dos pacotes são " +"descompactados nesse ambiente e todas as dependências necessárias são " +"instaladas." + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" +"Mesmo este não sendo o caso, e assumindo que você teve cuidado suficiente " +"para autenticar os downloads, usar a internet é desencorajado pelas " +"seguintes razões:" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" +"A conexão a internet pode ser instável (ex. devido a má recepção) or " +"apresentar problemas temporários que podem causar a falha ou atraso no " +"processo." + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" +"Os recursos remotos podem ficar indisponíveis temporariamente ou até " +"permanente, tornando a construção impossível. Isto é especialmente " +"problemático quando alguém precisa construir um pacote de versão antiga." + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" +"Os recursos remotos podem mudar, tornando a construção não reprodutível." + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" +"O acesso a servidores remotos representa um problema de privacidade e um " +"possível problema de segurança, pois expõe informações sobre o sistema que " +"cria o pacote." + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" +"O usuário pode estar usando um serviço com um plano de dados limitado, no " +"qual o acesso descontrolado à Internet pode resultar em cobranças adicionais " +"ou outros inconvenientes." + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" +"Se o pacote estiver implementando quaisquer ações de *backend* de construção " +"personalizadas que usem a Internet, por exemplo, baixando automaticamente " +"dependências fornecidas ou buscando submódulos do Git, sua distribuição " +"fonte deverá incluir todos esses arquivos ou permitir o provisionamento " +"externo, e a Internet não deverá ser usada se os arquivos já estiverem " +"presentes." + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" +"Observe que este ponto não se aplica às dependências do Python especificadas " +"nos metadados do pacote e obtidas durante o processo de construção e " +"instalação por *frontends* (como :ref:`build` ou :ref:`pip`). Os downstreams " +"utilizam frontends que utilizam provisionamento local para dependências do " +"Python." + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" +"O ideal é que scripts de construção personalizados nem tentem acessar a " +"internet, a menos que explicitamente solicitados. Se algum recurso estiver " +"faltando e precisar ser recuperado, eles devem primeiro solicitar a " +"permissão do usuário. Se isso não for viável, a melhor solução é fornecer " +"uma opção de desativação para desabilitar todo o acesso à internet. Isso " +"pode ser feito, por exemplo, verificando se uma variável de ambiente " +"``NO_NETWORK`` está definida com um valor não vazio." + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" +"Como os downstreams frequentemente também executam testes e criam " +"documentação, o ideal é que o exposto acima se estenda também a esses " +"processos." + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" +"Lembre-se também de que, se você estiver buscando recursos remotos, será " +"absolutamente necessário *verificar a autenticidade deles* (geralmente por " +"meio de um hash) para evitar que o arquivo seja substituído por uma parte " +"mal-intencionada." + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "Suporte à construção com dependências do sistema" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" +"Alguns projetos Python possuem dependências que não são Python, como " +"bibliotecas escritas em C ou C++. Tentar usar as versões de sistema dessas " +"dependências em pacotes upstream pode causar uma série de problemas para os " +"usuários finais:" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" +"As wheels publicadas exigem que uma versão binária compatível da biblioteca " +"utilizada esteja presente no sistema do usuário. Se a biblioteca estiver " +"ausente ou uma versão incompatível estiver instalada, o pacote Python poderá " +"falhar com erros que não são claros para usuários inexperientes, ou até " +"mesmo apresentar mau funcionamento em tempo de execução." + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" +"Construir a partir de uma distribuição fonte requer que uma versão " +"compatível com a origem da dependência esteja presente, juntamente com seus " +"cabeçalhos de desenvolvimento e outros arquivos auxiliares que alguns " +"sistemas empacotam separadamente da própria biblioteca." + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" +"Mesmo para um usuário experiente, instalar uma versão de dependência " +"compatível pode ser difícil. Por exemplo, a distribuição Linux utilizada " +"pode não prover a versão necessária, ou um pacote diferente pode exigir uma " +"versão incompatível." + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" +"A ligação entre o pacote Python e sua dependência do sistema não é " +"registrada pelo sistema de empacotamento. A próxima atualização do sistema " +"pode atualizar a biblioteca para uma versão mais recente, o que quebra a " +"compatibilidade binária com o pacote Python e requer intervenção do usuário " +"para correção." + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" +"Por esses motivos, você pode decidir, com razão, vincular suas dependências " +"estaticamente ou fornecer cópias locais no pacote instalado. Você também " +"pode vender a dependência na sua distribuição fonte. Às vezes, essas " +"dependências também são reempacotadas no PyPI e podem ser declaradas como " +"dependências de projeto, como qualquer outro pacote Python." + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" +"No entanto, nenhuma dessas questões se aplica ao empacotamento downstream, e " +"os downstreams têm bons motivos para preferir vincular dinamicamente às " +"dependências do sistema. Em particular:" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" +"Em muitos casos, o compartilhamento confiável de dependências dinâmicas " +"entre componentes é uma grande parte do *propósito* de um ecossistema de " +"empacotamento downstream. Ajudar a dar suporte a isso facilita o acesso dos " +"usuários desses sistemas a projetos upstream em seu formato preferido." + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" +"A vinculação estática e a venda obscurecem o uso de dependências externas, " +"dificultando a auditoria da fonte." + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" +"A vinculação dinâmica possibilita a substituição rápida e sistemática das " +"bibliotecas usadas em todo um ecossistema de empacotamento downstream, o que " +"pode ser particularmente importante quando elas contêm uma vulnerabilidade " +"de segurança ou um bug crítico." + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" +"O uso de dependências do sistema faz com que o pacote se beneficie da " +"personalização posterior, o que pode melhorar a experiência do usuário em " +"uma plataforma específica, sem que os mantenedores posteriores precisem " +"aplicar patches constantemente nas dependências fornecidas em diferentes " +"pacotes. Isso pode incluir melhorias de compatibilidade e reforço da " +"segurança." + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" +"A vinculação estática e a venda de versões podem resultar no carregamento de " +"várias versões diferentes da mesma biblioteca no mesmo processo (por " +"exemplo, ao tentar importar dois pacotes Python vinculados a versões " +"diferentes da mesma biblioteca). Isso às vezes funciona sem incidentes, mas " +"também pode levar a erros de carregamento de bibliotecas, bugs sutis de " +"tempo de execução e falhas catastróficas (como travamentos repentinos e " +"perda de dados)." + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" +"Por último, mas não menos importante, a ligação estática e o fornecimento " +"resulta em duplicação, e pode aumentar o uso de espaço e memória de disco." + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" +"Um bom meio-termo entre as necessidades de ambas as partes é fornecer uma " +"alternância entre o uso de dependências do fornecedor e do sistema. " +"Idealmente, se o pacote tiver várias dependências do fornecedor, ele deve " +"fornecer alternâncias individuais para cada dependência e uma alternância " +"geral para controlar o padrão para elas, por exemplo, por meio de uma " +"variável de ambiente ``USE_SYSTEM_DEPS``." + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" +"Se o usuário solicitar usando dependências do sistema e uma dependência " +"específica estiver ausente ou for incompatível, a construção deverá falhar " +"com uma mensagem explicativa, em vez de retornar a uma versão do fornecedor. " +"Isso dá ao empacotador a oportunidade de perceber o erro e decidir " +"conscientemente como resolvê-lo." + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" +"É razoável que projetos upstream deixem os *testes* de construção com " +"dependências do sistema para seus reempacotadores downstream. O objetivo " +"destas diretrizes é facilitar uma colaboração mais eficaz entre projetos " +"upstream e reempacotadores downstream, e não sugerir que projetos upstream " +"assumam tarefas que os reempacotadores downstream estão mais bem equipados " +"para lidar." + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "Ofereça suporte a testes no downstream" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" +"Diversos projetos downstream realizam algum grau de teste nos projetos " +"Python empacotados. Dependendo do caso específico, isso pode variar de " +"testes de fumaça mínimos a execuções abrangentes do conjunto de testes " +"completo. Pode haver vários motivos para isso, por exemplo:" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "Verificar se o empacotamento posterior não introduziu nenhum bug." + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" +"Testar em plataformas adicionais que não estão cobertas por testes upstream." + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" +"Encontrando bugs sutis que só podem ser reproduzidos com hardware " +"específico, certas versões de pacotes de sistemas, e assim por diante." + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" +"Testar o pacote lançado em relação a versões de dependência mais recentes " +"(ou mais antigas) do que as presentes durante os testes de versão upstream." + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" +"Testar o pacote em um ambiente muito semelhante à configuração de produção. " +"Isso pode detectar problemas causados por interações não triviais entre " +"diferentes pacotes instalados, incluindo pacotes que não são dependências do " +"seu pacote, mas que, mesmo assim, podem causar problemas." + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" +"Testar o pacote lançado em novas versões do Python (incluindo os pontos mais " +"recentes), ou implementações menos testadas do Python, como o PyPy." + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" +"É verdade que, às vezes, testes downstream podem gerar falsos positivos ou " +"relatórios de bugs sobre cenários que o projeto upstream não tem interesse " +"em suportar. No entanto, talvez com ainda mais frequência, eles notificam " +"problemas com antecedência ou encontram bugs não triviais que, de outra " +"forma, causariam problemas para os usuários do projeto upstream. Embora " +"erros aconteçam, a maioria dos empacotadores downstream faz o possível para " +"verificar seus resultados e ajudar os mantenedores upstream a triar e " +"corrigir os bugs relatados." + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" +"Há uma série de medidas que os projetos upstream podem tomar para ajudar os " +"reempacotadores downstream a testar seus pacotes de forma eficiente e " +"eficaz, incluindo algumas das sugestões já mencionadas. Essas são, em geral, " +"melhorias que tornam o conjunto de testes mais confiável e fácil de usar " +"para todos, não apenas para os empacotadores downstream. Algumas sugestões " +"específicas são:" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" +"Inclua os arquivos de teste e acessórios na distribuição fonte ou torne " +"possível baixá-los facilmente separadamente." + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" +"Não escreva nos diretórios de pacotes durante os testes. Às vezes, as " +"configurações de teste posteriores executam testes sobre o pacote instalado, " +"e modificações realizadas durante os testes e arquivos de teste temporários " +"podem acabar fazendo parte do pacote instalado!" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +#, fuzzy +msgid "Aim for stable releases" +msgstr "Publicando lançamentos" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +#, fuzzy +msgid "adding patches to the version currently published," +msgstr "adicionando patches à versão atualmente publicada," + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "ou até retornando o canal estável a uma versão anterior ao lançamento." + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" +"Cada opção envolve certos riscos e certo trabalho, e os empacotadoes devem " +"ponderar suas opções para determinar seu curso de ação ." + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" +"Considere fazer pré-lançamentos após grandes mudanças, provendo assim mais " +"oportunidade de teste para usuários e pessoas interessadas." + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" +"**Discussões** têm como objetivo fornecer informações abrangentes sobre um " +"tópico específico. Se você está apenas tentando fazer as coisas, veja :doc:`/" +"guides/index`." + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "install_requires vs arquivos requirements" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "install_requires" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" +"``install_requires`` é uma palavra-chave de :file:`setup.py` " +"do :ref:`setuptools` que deve ser usada para especificar o que um projeto " +"**minimamente** precisa para executar corretamente. Quando o projeto é " +"instalado por :ref:`pip`, esta é a especificação que é usada para instalar " +"suas dependências." + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" +"Por exemplo, se o projeto requer A e B, seu ``install_requires`` seria assim:" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" +"Além disso, é uma prática recomendada indicar qualquer limite inferior ou " +"superior conhecido." + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" +"Por exemplo, pode-se saber que seu projeto requer pelo menos v1 de \"A\" e " +"v2 de \"B\", então seria assim:" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" +"Também pode ser sabido que o projeto 'A' introduziu uma alteração em sua v2 " +"que quebra a compatibilidade do seu projeto com a v2 de 'A' e posteriores, " +"portanto, faz sentido não permitir a v2:" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" +"Não é considerada a melhor prática usar ``install_requires`` para fixar " +"dependências em versões específicas, ou para especificar subdependências (ou " +"seja, dependências de suas dependências). Isso é excessivamente restritivo e " +"evita que o usuário obtenha o benefício de atualizações de dependência." + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" +"Por último, é importante entender que ``install_requires`` é uma lista de " +"requisitos \"abstratos\", ou seja, apenas nomes e restrições de versão que " +"não determinam de onde as dependências serão preenchidas (ou seja, de qual " +"índice ou fonte). O local (ou seja, como eles devem ser feitos de " +"\"concreto\") deve ser determinado no momento da instalação usando as " +"opções :ref:`pip`. [1]_" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "Arquivos de requisitos" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" +":ref:`Arquivos de requisitos ` descritos de forma " +"mais simples, são apenas uma lista de argumentos :ref:`pip:pip install` " +"colocados em um arquivo." + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" +"Considerando que ``install_requires`` define as dependências para um único " +"projeto, :ref:`arquivos de requisitos ` são " +"frequentemente usados para definir os requisitos para um ambiente Python " +"completo." + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" +"Considerando que os requisitos de ``install_requires`` são mínimos, os " +"arquivos de requisitos frequentemente contêm uma lista exaustiva de versões " +"fixadas com o propósito de alcançar :ref:`instalações repetíveis " +"` de um ambiente completo." + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" +"Considerando que os requisitos de ``install_requires`` são \"abstratos\", ou " +"seja, não estão associados a nenhum índice em particular, os arquivos de " +"requisitos geralmente contêm opções de pip como ``--index-url`` ou ``--find-" +"links`` para fazer requisitos \"concreto \", isto é, associado a um " +"determinado índice ou diretório de pacotes. [1]_" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" +"Enquanto os metadados ``install_requires`` são automaticamente analisados " +"pelo pip durante uma instalação, os arquivos de requisitos não são, e são " +"usados apenas quando um usuário os instala especificamente usando ``python " +"-m pip install -r``." + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" +"Para obter mais informações sobre os requisitos \"abstratos\" vs " +"\"concretos\", consulte https://caremad.io/posts/2013/07/setup-vs-" +"requirement/." + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "Formatos de Pacotes" + +#: ../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 "" +"Esta página discute os formatos de arquivo usados para distribuir pacotes " +"Python e as diferenças entre eles." + +#: ../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 "" +"Você encontrará arquivos em dois formatos em índices de pacotes como PyPI_: " +"**distribuições fonte**, ou a abreviação **sdists**, e **distribuições " +"binárias**, comumente chamadas de **wheels**. Por exemplo, a `página PyPI " +"para pip 23.3.1 `_ permite baixar dois arquivos, " +"``pip-23.3.1.tar.gz`` e ``pip-23.3.1-py3-none-any.whl``. O primeiro é um " +"sdist, o último é uma wheel. Conforme explicado abaixo, eles têm finalidades " +"diferentes. Ao publicar um pacote no PyPI (ou em outro lugar), você deve " +"sempre enviar um sdist e um ou mais wheel." + +#: ../source/discussions/package-formats.rst:21 +msgid "What is a source distribution?" +msgstr "O que é uma distribuição fonte?" + +#: ../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 "" +"Conceitualmente, uma distribuição fonte é um arquivo do código-fonte em " +"formato bruto. Concretamente, um sdist é um arquivo ``.tar.gz`` contendo o " +"código-fonte mais um arquivo especial adicional chamado ``PKG-INFO``, que " +"contém os metadados do projeto. A presença desse arquivo ajuda as " +"ferramentas de empacotamento a serem mais eficientes, pois não precisam " +"calcular os próprios metadados. O arquivo ``PKG-INFO`` segue o formato " +"especificado em :ref:`core-metadata` e não se destina a ser escrito à mão " +"[#core-metadata-format]_." + +#: ../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 "" +"Você pode, portanto, operar o conteúdo de um sdist descompactando-o usando " +"ferramentas padrão para trabalhar com arquivos tar, como ``tar -xvf`` em " +"plataformas UNIX (como Linux e macOS), ou :ref:`a interface de linha de " +"comando do módulo tarfile do Python ` em " +"qualquer plataforma." + +#: ../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 "" +"Os sdists servem a vários propósitos no ecossistema de embalagens. " +"Quando :ref:`pip`, o instalador padrão do pacote Python, não consegue " +"encontrar um wheel para instalar, ele recorrerá ao download de uma " +"distribuição fonte, compilando um wheel a partir dela e instalando o wheel. " +"Além disso, os sdists são frequentemente usados como fonte de pacote por " +"empacotadores downstream (como distribuições Linux, Conda, Homebrew e " +"MacPorts no macOS, ...), que, por vários motivos, podem preferi-los, por " +"exemplo, extraindo de um repositório Git." + +#: ../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 "" +"Uma distribuição fonte é reconhecida pelo seu nome de arquivo, que tem o " +"formato :samp:`{nome_do_pacote}-{versão}.tar.gz`, por exemplo, " +"``pip-23.3.1.tar.gz``." + +#: ../source/discussions/package-formats.rst:50 +msgid "" +"If you want technical details on the sdist format, read the :ref:`sdist " +"specification `." +msgstr "" +"Se você quiser detalhes técnicos sobre o formato sdist, leia " +"a :ref:`especificação de sdist `." + +#: ../source/discussions/package-formats.rst:55 +msgid "What is a wheel?" +msgstr "O que é um wheel?" + +#: ../source/discussions/package-formats.rst:57 +msgid "" +"Conceptually, a wheel contains exactly the files that need to be copied when " +"installing the package." +msgstr "" +"Conceitualmente, um wheel contém exatamente os arquivos que precisam ser " +"copiados durante a instalação do pacote." + +#: ../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 "" +"Há uma grande diferença entre sdists e wheels para pacotes " +"com :term:`módulos de extensão `, escritos em linguagens " +"compiladas como C, C++ e Rust, que precisam ser compilados em código de " +"máquina dependente de plataforma. Com esses pacotes, as rodas não contêm " +"código fonte (como arquivos fonte C), mas código executável compilado (como " +"arquivos ``.so`` no Linux ou DLLs no Windows)." + +#: ../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 "" +"Além disso, embora exista apenas um sdist por versão de um projeto, pode " +"haver muitos wheels. Novamente, isto é mais relevante no contexto dos " +"módulos de extensão. O código compilado de um módulo de extensão está " +"vinculado a um sistema operacional e arquitetura de processador, e muitas " +"vezes também à versão do interpretador Python (a menos que a :ref:`ABI " +"estável do Python ` seja usada)." + +#: ../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 "" +"Para pacotes Python puro, a diferença entre sdists e wheels é menos " +"acentuada. Normalmente existe um único wheel, para todas as plataformas e " +"versões do Python. Python é uma linguagem interpretada, que não precisa de " +"compilação antecipada, então wheels contêm arquivos ``.py`` assim como " +"sdists." + +#: ../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 "" +"Se você está se perguntando sobre os arquivos de bytecode ``.pyc``: eles não " +"estão incluídos nos wheels, pois são pouco custoso para gerar, e incluí-los " +"forçaria desnecessariamente um grande número de pacotes a distribuir um " +"wheel por versão do Python em vez de um único wheel. Em vez disso, " +"instaladores como :ref:`pip` os geram durante a instalação do pacote." + +#: ../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 "" +"Dito isto, ainda existem diferenças importantes entre sdists e wheels, mesmo " +"para projetos Python puros. Os wheels devem conter exatamente o que será " +"instalado e nada mais. Em particular, os wheels nunca devem incluir testes e " +"documentação, ao contrário dos sdists. Além disso, o formato do wheel é mais " +"complexo que o sdist. Por exemplo, inclui um arquivo especial -- chamado " +"``RECORD`` -- que lista todos os arquivos no wheel junto com um hash de seu " +"conteúdo, como uma verificação de segurança da integridade do download." + +#: ../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 "" +"À primeira vista, você pode se perguntar se wheels são realmente necessários " +"para projetos \"simples e básicos\" de Python puro. Tenha em mente que " +"devido à flexibilidade dos sdists, instaladores como o pip não podem " +"instalar diretamente a partir dos sdists -- eles precisam primeiro construir " +"um wheel, invocando o :term:`backend de construção` que o sdist especifica " +"(o backend de construção pode fazer todo tipo de transformações durante a " +"construção do wheel, como compilar extensões C). Por esse motivo, mesmo para " +"um projeto Python puro, você deve sempre enviar *ambos* sdist e wheel para o " +"PyPI ou outros índices de pacotes. Isso torna a instalação muito mais rápida " +"para seus usuários, já que um wheel pode ser instalado diretamente. Ao " +"incluir apenas os arquivos que devem ser instalados, os wheels também " +"permitem downloads menores." + +#: ../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 "" +"No nível técnico, um wheel é um arquivo ZIP (ao contrário dos sdists que são " +"arquivos TAR). Você pode inspecionar seu conteúdo descompactando-o como um " +"arquivo ZIP normal, por exemplo, usando ``unzip`` em plataformas UNIX como " +"Linux e macOS, ``Expand-Archive`` no PowerShell no Windows, ou :ref:`a linha " +"de comando interface do módulo zipfile do Python `. Isso pode ser muito útil para verificar se o wheel inclui " +"todos os arquivos necessários." + +#: ../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 "" +"Dentro de um wheel, você encontrará os arquivos do pacote, além de um " +"diretório adicional chamado :samp:`{nome_do_pacote}-{versão}.dist-info`. " +"Este diretório contém vários arquivos, incluindo um arquivo ``METADATA`` que " +"é equivalente a ``PKG-INFO`` em sdists, bem como ``RECORD``. Isso pode ser " +"útil para garantir que nenhum arquivo esteja faltando em suas rodas." + +#: ../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 "" +"O nome do arquivo de um wheel (ignorando alguns recursos raramente usados) é " +"assim: :samp:`{nome_do_pacote}-{versão}-{tag_python}-{tag_abi}-" +"{tag_plataforma}.whl`. Esta convenção de nomenclatura identifica com quais " +"plataformas e versões do Python a roda é compatível. Por exemplo, o nome " +"``pip-23.3.1-py3-none-any.whl`` significa que:" + +#: ../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 "" +"(``py3``) Este wheel pode ser instalado em qualquer implementação do Python " +"3, seja CPython, a implementação Python mais usada, ou uma implementação " +"alternativa como PyPy_;" + +#: ../source/discussions/package-formats.rst:124 +msgid "(``none``) It does not depend on the Python version;" +msgstr "(``none``) Não depende da versão do Python;" + +#: ../source/discussions/package-formats.rst:125 +msgid "(``any``) It does not depend on the platform." +msgstr "(``qualquer``) Não depende da plataforma." + +#: ../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 "" +"O padrão ``py3-none-any`` é comum para projetos Python puros. Pacotes com " +"módulos de extensão normalmente enviam vários wheels com tags mais complexas." + +#: ../source/discussions/package-formats.rst:130 +msgid "" +"All technical details on the wheel format can be found in the :ref:`wheel " +"specification `." +msgstr "" +"Todos os detalhes técnicos sobre o formato do wheel podem ser encontrados " +"na :ref:`especificação de wheels `." + +#: ../source/discussions/package-formats.rst:138 +msgid "What about eggs?" +msgstr "E quanto a eggs?" + +#: ../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 "" +"\"Egg\" é um formato de pacote antigo que foi substituído pelo formato de " +"wheels. Não deve mais ser usado. Desde agosto de 2023, o PyPI `rejeita " +"envios de eggs `_." + +#: ../source/discussions/package-formats.rst:144 +msgid "Here's a breakdown of the important differences between wheel and egg." +msgstr "Aqui está uma análise das diferenças importantes entre wheel e egg." + +#: ../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 "" +"O formato egg foi introduzido pelo :ref:`setuptools` em 2004, enquanto o " +"formato wheel foi introduzido pela :pep:`427` em 2012." + +#: ../source/discussions/package-formats.rst:149 +msgid "" +"Wheel has an :doc:`official standard specification `. Egg did not." +msgstr "" +"Wheel tem uma :doc:`especificação de padrão oficial `. Egg não tinha." + +#: ../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 "" +"Wheel é um formato de :term:`distribuição `, ou seja, " +"um formato de empacotamento. [#wheel-importable]_ Egg era um formato de " +"distribuição e um formato de instalação em tempo de execução (se deixado " +"compactado), e foi projetado para ser importável." + +#: ../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 "" +"Os arquivos wheel não incluem arquivos ``.pyc``. Portanto, quando a " +"distribuição contém apenas arquivos Python (ou seja, sem extensões " +"compiladas) e é compatível com Python 2 e 3, é possível que um wheel seja " +"\"universal\", semelhante a um :term:`sdist `." + +#: ../source/discussions/package-formats.rst:161 +msgid "" +"Wheel uses standard :ref:`.dist-info directories `. Egg used ``.egg-info``." +msgstr "" +"Wheel usa :ref:`diretórios .dist-info ` " +"padrões. Egg usava ``.egg-info``." + +#: ../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 "" +"Wheel tem uma :ref:`convenção de nomenclatura de arquivo mais rica `. Um único arquivo de wheel pode indicar sua compatibilidade " +"com várias versões e implementações da linguagem Python, ABIs e arquiteturas " +"de sistema." + +#: ../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 "" +"Wheel é versionado. Cada arquivo wheel contém a versão da especificação " +"wheel e a implementação que a empacotou." + +#: ../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 "" +"Wheel é internamente organizado pelo `tipo de caminho sysconfig `_, portanto " +"tornando mais fácil converter para outros formatos." + +#: ../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 "" +"Este formato é baseado em e-mail. Embora seja improvável que isso seja " +"escolhido hoje, considerações de compatibilidade com versões anteriores " +"levam a que ele seja mantido como formato canônico. Do ponto de vista do " +"usuário, isso é praticamente invisível, já que os metadados são " +"especificados pelo usuário de uma forma compreendida pelo backend de " +"construção, normalmente ``[project]`` em ``pyproject.toml``, e traduzidos " +"pelo backend de construção em ``PKG-INFO``." + +#: ../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 "" +"Circunstancialmente, em alguns casos, wheels podem ser usados como um " +"formato de tempo de execução importável, embora :ref:`não haja suporte " +"oficial a isso no momento `." + +#: ../source/discussions/pip-vs-easy-install.rst:6 +msgid "pip vs easy_install" +msgstr "pip vs easy_install" + +#: ../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 `, agora `descontinuado`_, foi lançado em " +"2004 como parte do :ref:`setuptools`. Era notável na época para " +"instalar :term:`pacotes ` do :term:`PyPI ` usando especificadores de requisitos e instalando " +"dependências automaticamente." + +#: ../source/discussions/pip-vs-easy-install.rst:14 +#, fuzzy +#| 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." +msgid "" +":ref:`pip` came later in 2008, as an 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 "" +"O :ref:`pip` veio mais tarde em 2008, como alternativa ao :ref:`easy_install " +"`, embora ainda amplamente construído sobre os " +"componentes :ref:`setuptools`. Era notável na época por *não* instalar " +"pacotes como :term:`Eggs ` ou de :term:`Eggs ` (mas simplesmente " +"como pacotes \"planos\" de :term:`sdists `), e introduzindo a ideia de :ref:`Arquivos de Requisitos " +"`, que deu aos usuários o poder de replicar " +"ambientes facilmente." + +#: ../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 "" +"Aqui está uma análise das diferenças importantes entre o pip e o " +"descontinuado easy_install:" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "**pip**" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "**easy_install**" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "Instala de :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 "Sim" + +#: ../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 "Não" + +#: ../source/discussions/pip-vs-easy-install.rst:30 +msgid "Uninstall Packages" +msgstr "Desinstala pacotes" + +#: ../source/discussions/pip-vs-easy-install.rst:30 +msgid "Yes (``python -m pip uninstall``)" +msgstr "Sim (``python -m pip uninstall``)" + +#: ../source/discussions/pip-vs-easy-install.rst:32 +msgid "Dependency Overrides" +msgstr "Substitui dependências" + +#: ../source/discussions/pip-vs-easy-install.rst:32 +msgid "Yes (:ref:`Requirements Files `)" +msgstr "Sim (:ref:`Arquivo de Requisitos `)" + +#: ../source/discussions/pip-vs-easy-install.rst:35 +msgid "List Installed Packages" +msgstr "Lista pacotes instalados" + +#: ../source/discussions/pip-vs-easy-install.rst:35 +msgid "Yes (``python -m pip list`` and ``python -m pip freeze``)" +msgstr "Sim (``python -m pip list`` e ``python -m pip freeze``)" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "Suporte a :pep:`438`" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Installation format" +msgstr "Formato de instalação" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "'Flat' packages with :file:`egg-info` metadata." +msgstr "Pacotes \"planos\" com metadados de :file:`egg-info`." + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "Formato Egg encapsulado" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "Modificação de sys.path" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "Instala de :term:`Eggs `" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "`suporte a pylauncher`_" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "Sim [1]_" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr ":ref:`Instalações multiversões `" + +#: ../source/discussions/pip-vs-easy-install.rst:57 +msgid "Exclude scripts during install" +msgstr "Exclui scripts durante a instalação" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "per project index" +msgstr "índice por projeto" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Only in virtualenv" +msgstr "Apenas em virtualenv" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "Sim, via setup.cfg" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "``setup.py`` foi descontinuado?" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "Não, :term:`setup.py` e :ref:`setuptools` não foram descontinuados." + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" +"Setuptools é perfeitamente utilizável como um :term:`backend de construção` " +"para empacotar projetos Python. E :file:`setup.py` é um arquivo de " +"configuração válido para :ref:`setuptools` que é escrito em Python, em vez " +"de em *TOML* por exemplo (uma prática semelhante é usada por outras " +"ferramentas como *nox* e seu arquivo de configuração :file:`noxfile.py`, ou " +"*pytest* e :file:`conftest.py`)." + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" +"No entanto, ``python setup.py`` e o uso de :file:`setup.py` como uma " +"ferramenta de linha de comando foram descontinuados." + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" +"Isso significa que comandos como os seguintes **NÃO DEVEM** ser mais " +"executados:" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +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 "Quais comandos devem ser usados?" + +#: ../source/discussions/setup-py-deprecated.rst:33 +#: ../source/guides/modernize-setup-py-project.rst:30 +msgid "Deprecated" +msgstr "Descontinuado" + +#: ../source/discussions/setup-py-deprecated.rst:33 +#: ../source/guides/modernize-setup-py-project.rst:30 +msgid "Recommendation" +msgstr "Recomendação" + +#: ../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]_" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" +"Isto requer a dependência de :ref:`build`. É recomendado sempre construir e " +"publicar tanto a distribuição fonte quanto a wheel de um projeto, que é o " +"que ``python -m build`` faz. Se necessário as opções ``--sdist`` e ``--" +"wheel`` podem ser usadas para gerar apenas uma ou outra." + +#: ../source/discussions/setup-py-deprecated.rst:52 +msgid "" +"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 "" +"Para instalar um projeto baseado no setuptools, era comum executar o comando " +"``install`` do arquivo :file:`setup.py`, como, por exemplo, ``python " +"setup.py install``. Atualmente, o método recomendado é utilizar o :ref:`pip` " +"diretamente com um comando como este: ``python -m pip install .``. O ponto " +"``.`` representa o caminho do sistema de arquivos, sendo a notação para o " +"diretório atual. De fato, o *pip* aceita um caminho para o diretório da " +"árvore de fontes do projeto no sistema de arquivos local como argumento para " +"o seu subcomando ``install``. Portanto, este também seria um comando válido: " +"``python -m pip install caminho/para/projeto``." + +#: ../source/discussions/setup-py-deprecated.rst:65 +msgid "" +"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 "" +"Quanto à instalação no modo *develop*, também conhecido como modo " +"*editable*, em vez de ``python setup.py develop``, é possível utilizar a " +"opção ``--editable`` do subcomando *install* do *pip* da seguinte forma: " +"``python -m pip install --editable .``." + +#: ../source/discussions/setup-py-deprecated.rst:70 +msgid "" +"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 "" +"Um método recomendado, simples e direto para construir :term:`distribuições " +"fonte ` e :term:`wheels ` é usar " +"a ferramenta :ref:`build` com um comando como ``python -m build``, que " +"aciona a geração de ambos os formatos de distribuição. Se necessário, as " +"opções ``--sdist`` e ``--wheel`` podem ser usadas para gerar apenas um ou " +"outro. Observe que a ferramenta de construção precisa ser instalada " +"separadamente." + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" +"O comando ``python setup.py install`` foi descontinuado na versão *58.3.0* " +"do setuptools." + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "E quanto a outros comandos?" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" +"Quais são algumas substituições para os outros comandos ``python setup.py``?" + +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "``python setup.py test``" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "A recomendação é usar um executor de testes como pytest_." + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" +"``python setup.py check``, ``python setup.py register`` e ``python setup.py " +"upload``" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "Um substituto confiável é :ref:`twine`:" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "``python -m twine check --strict dist/*``" + +#: ../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/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "``python -m twine upload dist/*``" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" +"Não é necessário, nem suportado em :term:`PyPI `. Mas pode ser necessário em outros :term:`índices de pacotes " +"` (por exemplo, :ref:`devpi`)." + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "``python setup.py --version``" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" +"Uma possível solução de substituição (entre outras) é contar com setuptools-" +"scm_:" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "``python -m setuptools_scm``" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "Comandos restantes" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" +"Este guia não faz sugestões de soluções de substituição para esses comandos:" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "``alias``" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "``bdist``" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "``bdist_dumb``" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "``bdist_egg``" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "``bdist_rpm``" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "``build``" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "``build_clib``" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "``build_ext``" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "``build_py``" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "``build_scripts``" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "``clean``" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "``dist_info``" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "``easy_install``" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "``editable_wheel``" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "``egg_info``" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "``install_data``" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "``install_egg_info``" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "``install_headers``" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "``install_lib``" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "``install_scripts``" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "``rotate``" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "``saveopts``" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "``setopt``" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "``upload_docs``" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "E quanto aos comandos personalizados?" + +#: ../source/discussions/setup-py-deprecated.rst:158 +msgid "" +"Likewise, custom :file:`setup.py` commands are deprecated. The " +"recommendation is to migrate those custom commands to a task runner tool or " +"any other similar tool. Some examples of such tools are: chuy, make, nox or " +"tox, pydoit, pyinvoke, taskipy, and thx." +msgstr "" +"Da mesma forma, os comandos personalizados no :file:`setup.py` foram " +"descontinuados. A recomendação é migrar esses comandos personalizados para " +"uma ferramenta executora de tarefas ou qualquer outra ferramenta semelhante. " +"Alguns exemplos de tais ferramentas são: chuy, make, nox ou tox, pydoit, " +"pyinvoke, taskipy e thx." + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "E quanto às etapas personalizadas de construção?" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" +"Etapas personalizadas de construção que, por exemplo, sobrescrevem etapas " +"existentes como ``build_py``, ``build_ext`` e ``bdist_wheel`` ou adicionam " +"novas etapas de compilação não foram descontinuadas. Eles serão chamados " +"automaticamente conforme o esperado." + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "Deve o ``setup.py`` ser excluído?" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" +"Embora o uso de :file:`setup.py` como um script executável tenha sido " +"descontinuado, seu uso como um arquivo de configuração para setuptools é " +"absolutamente aceitável. Provavelmente não há necessidade de modificação " +"em :file:`setup.py`." + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "``pyproject.toml`` é obrigatório?" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" +"Embora ainda não seja tecnicamente necessário, é **FORTEMENTE RECOMENDADO** " +"que um projeto tenha um arquivo :file:`pyproject.toml` na raiz de sua árvore " +"de fontes com um conteúdo como este:" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "O guia :ref:`modernize-setup-py-project` tem mais detalhes sobre isso." + +#: ../source/discussions/setup-py-deprecated.rst:198 +msgid "" +"The standard fallback behavior for a :term:`build frontend ` " +"in the absence of a :file:`pyproject.toml` file and its ``[build-system]`` " +"table is to assume that the :term:`build backend ` is " +"setuptools." +msgstr "" +"O comportamento de fallback padrão para um :term:`frontend de construção " +"` na ausência de um arquivo :file:`pyproject.toml` e sua " +"tabela ``[build-system]`` é assumir que o :term:`backend de construção " +"` é o setuptools." + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "Por que? O que isso tudo quer dizer?" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" +"Uma maneira de ver isso é que o escopo do setuptools agora foi reduzido à " +"função de um backend de construção." + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "Onde posso ler mais sobre isso?" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" +"`Por que você não deveria invocar setup.py diretamemente `__ (inglês) por " +"Paul Ganssle" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr ":doc:`setuptools:deprecated/commands`" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "Mantendo uma única fonte da versão do pacote" + +#: ../source/discussions/single-source-version.rst:7 +msgid "Complete" +msgstr "Completa" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "2024-10-07" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" +"Muitos :term:`pacotes de distribuição ` Python " +"publicam um único :term:`pacote de importação ` Python onde " +"é desejado que o atributo de tempo de execução ``__version__`` no pacote de " +"importação relate o mesmo especificador de versão " +"que :func:`importlib.metadata.version` relata para o pacote de distribuição " +"(conforme descrito em :ref:`runtime-version-access`)." + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +#, fuzzy +#| msgid "" +#| "There are many techniques to maintain a single source of truth for the " +#| "version number of your project:" +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" +"Existem muitas técnicas para manter uma única fonte para o número de versão " +"do seu projeto:" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +#, fuzzy +#| msgid "`Flatpak `_" +msgid "`Flit `_" +msgstr "`Flatpak `_" + +#: ../source/discussions/single-source-version.rst:56 +#, fuzzy +#| msgid "`Apache `_" +msgid "`Hatchling `_" +msgstr "`Apache `_" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +#, fuzzy +msgid "`setuptools_scm `_" +msgstr "`Flexx `_" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "layout src vs layout plano" + +#: ../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 "" +"O \"layout plano\" (em inglês, *flat layout*) refere-se à organização dos " +"arquivos de um projeto em uma pasta ou repositório, de forma que os vários " +"arquivos de configuração e :term:`pacotes de importação ` " +"estejam todos no diretório de nível superior." + +#: ../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 "" +"O \"layout src\" (em inglês, *layout src*)se desvia do layout plano movendo " +"o código que se destina a ser importável (ou seja, ``import " +"awesome_package``, também conhecido como :term:`pacotes de importação " +"`) para um subdiretório. Este subdiretório é normalmente " +"chamado de ``src/``, daí \"layout src\"." + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" +"Aqui está uma análise das diferenças de comportamento importantes entre o " +"layout src e o layout plano:" + +#: ../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 "" +"O layout src requer a instalação do projeto para poder executar seu código, " +"e o layout plano não." + +#: ../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 "" +"Isso significa que o layout src envolve uma etapa adicional no fluxo de " +"trabalho de desenvolvimento de um projeto (normalmente, uma :doc:`instalação " +"editável ` é usada para " +"desenvolvimento e uma instalação regular é usada para teste) ." + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" +"O layout src ajuda a evitar o uso acidental da cópia em desenvolvimento do " +"código." + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +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." +msgstr "" +"Isso é relevante, pois o interpretador Python inclui o diretório de trabalho " +"atual como o primeiro item no caminho de importação. Isso significa que se " +"existir um pacote de importação no diretório de trabalho atual com o mesmo " +"nome de um pacote de importação instalado, a variante do diretório de " +"trabalho atual será usada. Isso pode levar a uma configuração incorreta " +"sutil das ferramentas de empacotamento do projeto, o que pode resultar na " +"não inclusão de arquivos em uma distribuição." + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" +"O layout src ajuda a evitar isso mantendo os pacotes de importação em um " +"diretório separado do diretório raiz do projeto, garantindo que a cópia " +"instalada seja usada." + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" +"O layout src ajuda a reforçar que uma :doc:`instalação editável " +"` só é capaz de importar arquivos que " +"deveriam ser importados." + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" +"Isso é especialmente relevante quando a instalação editável é implementada " +"usando um `arquivo de configuração de caminho `_ que adiciona o diretório ao caminho de " +"importação." + +#: ../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 "" +"O layout plano adicionaria os outros arquivos de projeto (por exemplo: " +"``README.md``, ``tox.ini``) e arquivos de configuração de pacotes/" +"ferramentas (por exemplo: ``setup.py``, ``noxfile.py``) no caminho de " +"importação. Isso faria com que certas importações funcionassem em " +"instalações editáveis, mas não em instalações regulares." + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "Executando uma interface de linha de comando da fonte com src-layout" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +msgid "Versioning" +msgstr "Versionamento" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" +"Esta discussão cobre todos os aspectos do versionamento de pacotes Python." + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "Números de versão validos" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" +"Diferentes projetos Python podem usar diferentes esquemas de versionamento " +"com base nas necessidades daquele projeto específico, mas para serem " +"compatíveis com ferramentas como :ref:`pip`, todos eles são obrigados a " +"cumprir um formato flexível para identificadores de versão, para o qual a " +"referência oficial é a :ref:`especificação dos especificadores de versão " +"`. Aqui estão alguns exemplos de números de versão " +"[#version-examples]_:" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "Uma versão simples (versão final): ``1.2.0``" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "Uma versão de desenvolvimento: ``1.2.0.dev1``" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "Uma versão alfa: ``1.2.0a1``" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "Uma versão beta: ``1.2.0b1``" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "Um candidato a lançamento: ``1.2.0rc1``" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "Um pós-lançamento: ``1.2.0.post1``" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" +"Um pós-lançamento de uma versão alfa (possível, mas desencorajado): " +"``1.2.0a1.post1``" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "Uma versão simples com apenas dois componentes: ``23.12``" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "Uma versão simples com apenas um componente: ``42``" + +#: ../source/discussions/versioning.rst:30 +#, fuzzy +#| msgid "A version with an epoch: ``1!1.0``" +msgid "A version with an epoch (discouraged): ``1!1.0``" +msgstr "Uma versão com uma época: ``1!1.0``" + +#: ../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 "" +"Os projetos podem usar um ciclo de pré-lançamentos para dar suporte aos " +"testes de seus usuários antes do lançamento final. Em ordem, as etapas são: " +"versões alfa, versões beta, candidatos a lançamento, versão final. Pip e " +"outros instaladores modernos de pacotes Python ignoram pré-lançamentos por " +"padrão ao decidir quais versões de dependências instalar, a menos que " +"solicitado explicitamente (por exemplo, com ```pip install pkg==1.1a3`` ou " +"``pip install --pre pkg``)." + +#: ../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 "" +"O objetivo dos lançamentos de desenvolvimento é oferecer suporte aos " +"lançamentos feitos no início de um ciclo de desenvolvimento, por exemplo, " +"uma construção noturna ou uma construção a partir do código-fonte mais " +"recente em uma distribuição Linux." + +#: ../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 "" +"Os pós-lançamentos são usados para corrigir pequenos erros em uma versão " +"final que não afetam o software distribuído, como corrigir um erro nas notas " +"de versão. Eles não devem ser usados para correção de bugs; isso deve ser " +"feito com uma nova versão final (por exemplo, incrementando o terceiro " +"componente ao usar o versionamento semântico)." + +#: ../source/discussions/versioning.rst:49 +#, fuzzy +#| 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." +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" +"Por fim, as épocas, um recurso raramente usado, servem para corrigir a ordem " +"de classificação ao alterar o esquema de versionamento. Por exemplo, se um " +"projeto estiver usando versionamento de calendário, com versões como 23.12, " +"e mudar para versionamento semântico, com versões como 1.0, a comparação " +"entre 1.0 e 23.12 irá para o lado errado. Para corrigir isso, os novos " +"números de versão devem ter uma época explícita, como em \"1!1.0\", para " +"serem tratados como mais recentes que os números de versão antigos." + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "Versionamento semântico vs. versionamento de calendário" + +#: ../source/discussions/versioning.rst:62 +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 "" +"Um esquema de versionamento é uma forma formalizada de interpretar os " +"segmentos de um número de versão e de decidir qual deve ser o próximo número " +"de versão para um novo lançamento de um pacote. Dois esquemas de " +"versionamento são comumente usados para pacotes Python, versionamento " +"semântico e versionamento de calendário." + +#: ../source/discussions/versioning.rst:69 +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 "" +"A decisão de qual número de versão escolher cabe ao mantenedor do projeto. " +"Isso efetivamente significa que os incrementos de versão refletem a visão do " +"mantenedor. Essa visão pode diferir da percepção dos usuários finais sobre o " +"que o referido esquema de versionamento formalizado lhes promete." + +#: ../source/discussions/versioning.rst:75 +#, fuzzy +#| 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." +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" +"Existem exceções conhecidas para selecionar o próximo número de versão. Os " +"mantenedores podem escolher conscientemente quebrar a suposição de que o " +"segmento da última versão contém apenas alterações compatíveis com versões " +"anteriores. Um desses casos é quando a vulnerabilidade de segurança precisa " +"ser abordada. As versões de segurança geralmente vêm em versões de patch, " +"mas inevitavelmente contêm alterações importantes." + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "Versionamento semântico" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" +"A ideia do *versionamento semântico* (ou SemVer) é usar números de versão de " +"3 partes, *principal.menor.correção*, onde o autor do projeto incrementa:" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "*principal* quando são feitas alterações incompatíveis à API," + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" +"*menor* quando é adicionada funcionalidade de maneira compatível com versões " +"anteriores, e" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" +"*correção*, quando são feitas correções de bugs compatíveis com versões " +"anteriores." + +#: ../source/discussions/versioning.rst:94 +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 "" +"A maioria dos projetos Python usa um esquema que se assemelha ao " +"versionamento semântico. No entanto, a maioria dos projetos, especialmente " +"os maiores, não aderem estritamente ao versionamento semântico, uma vez que " +"muitas alterações são tecnicamente prejudiciais, mas afetam apenas uma " +"pequena fração dos usuários. Tais projetos tendem a aumentar o número maior " +"quando a incompatibilidade é alta, ou para sinalizar uma mudança no projeto, " +"ao invés de qualquer pequena incompatibilidade [#semver-strictness]_. Por " +"outro lado, um aumento no número da versão principal às vezes é usado para " +"sinalizar novos recursos significativos, mas compatíveis com versões " +"anteriores." + +#: ../source/discussions/versioning.rst:104 +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 "" +"Para aqueles projetos que usam controle de versão semântico estrito, esta " +"abordagem permite que os usuários façam uso de :ref:`especificadores de " +"versão de lançamento compatíveis `, " +"com o operador ``~=``. Por exemplo, ``name ~= X.Y`` é aproximadamente " +"equivalente a ``name >= X.Y, == X.*``, ou seja, requer pelo menos a versão " +"X.Y, e permite qualquer versão posterior com Y maior, desde que X é o mesmo. " +"Da mesma forma, ``name ~= X.Y.Z`` é aproximadamente equivalente a ``name >= " +"X.Y.Z, == X.Y.*``, ou seja, requer pelo menos X.Y.Z e permite uma versão " +"posterior com o mesmo X e Y, mas Z superior." + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" +"Projetos Python que adotam versões semânticas devem obedecer às cláusulas " +"1-8 da `especificação de Versionamento Semântico 2.0.0 `_." + +#: ../source/discussions/versioning.rst:116 +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 "" +"O popular gerador de documentação :doc:`Sphinx ` é um exemplo " +"de projeto que usa controle de versionamento semântico estrito " +"(:doc:`Política de versionamento do Sphinx `). O famoso pacote de computação científica :doc:`NumPy " +"` usa explicitamente versionamento semântico \"folgado\", onde " +"lançamentos incrementando a versão menor podem conter alterações de API " +"incompatíveis com versões anteriores (:doc:`Política de versionamento do " +"NumPy `)." + +#: ../source/discussions/versioning.rst:125 +msgid "Calendar versioning" +msgstr "Versionamento de calendário" + +#: ../source/discussions/versioning.rst:127 +#, fuzzy +#| 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." +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 "" +"O versionamento semântico não é uma escolha adequada para todos os projetos, " +"como aqueles com uma cadência de lançamento baseada em tempo regular e um " +"processo de descontinuação que fornece avisos para vários lançamentos antes " +"da remoção de um recurso." + +#: ../source/discussions/versioning.rst:131 +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 "" +"Uma vantagem principal do versionamento baseado em data, ou `versionamento " +"de calendário `_ (CalVer), é que é simples dizer quantos anos o " +"conjunto de recursos básicos de uma determinada versão recebe apenas o " +"número da versão." + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" +"Os números de versão do calendário normalmente assumem o formato *ano.mês* " +"(por exemplo, 23.12 para dezembro de 2023)." + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" +":doc:`Pip `, o instalador padrão do pacote Python, usa " +"versionamento de calendário." + +#: ../source/discussions/versioning.rst:143 +msgid "Other schemes" +msgstr "Outros esquemas" + +#: ../source/discussions/versioning.rst:145 +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 "" +"O versionamento serial refere-se ao esquema de versionamento mais simples " +"possível, que consiste em um único número incrementado a cada versão. Embora " +"o versionamento serial seja muito fácil de gerenciar como desenvolvedor, é o " +"mais difícil de rastrear como usuário final, pois os números de versão " +"serial transmitem pouca ou nenhuma informação sobre compatibilidade com " +"versões anteriores da API." + +#: ../source/discussions/versioning.rst:151 +#, fuzzy +#| 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." +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 "" +"Combinações dos esquemas acima são possíveis. Por exemplo, um projeto pode " +"combinar o versionamento baseado em data com o versionamento serial para " +"criar um esquema de numeração *ano.série* que transmite prontamente a idade " +"aproximada de um lançamento, mas não se compromete com uma cadência de " +"lançamento particular dentro do ano." + +#: ../source/discussions/versioning.rst:158 +#: ../source/specifications/version-specifiers.rst:114 +msgid "Local version identifiers" +msgstr "Identificadores de versão local" + +#: ../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 "" +"Identificadores de versão pública são projetados para suportar distribuição " +"via :term:`PyPI `. As ferramentas de " +"empacotamento do Python também oferecem suporte à noção de " +"um :ref:`identificador de versão local `, que " +"pode ser usado para identificar compilações de desenvolvimento local não " +"destinadas à publicação, ou variantes modificadas de uma versão mantida por " +"um redistribuidor." + +#: ../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 "" +"Um identificador de versão local assume a forma de um identificador de " +"versão pública, seguido por \"+\" e um rótulo de versão local. Por exemplo, " +"um pacote com patches específicos do Fedora aplicados poderia ter a versão " +"\"1.2.1+fedora.4\". Outro exemplo são as versões calculadas pelo setuptools-" +"scm_, um plugin do setuptools que lê a versão dos dados do Git. Em um " +"repositório Git com alguns commits desde a versão mais recente, setuptools-" +"scm gera uma versão como \"0.5.dev1+gd00980f\", ou se o repositório tiver " +"alterações não rastreadas, como \"0.5.dev1+gd00980f.d20231217\"." + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" +"Mais alguns exemplos de números de versão incomuns são fornecidos em uma " +"`postagem no blog `_ de Seth Larson." + +#: ../source/discussions/versioning.rst:229 +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 "" +"Para alguns pontos de vista pessoais sobre este assunto, consulte estas " +"postagens do blog: `de Hynek Schlawak `_, `de " +"Donald Stufft `_, `de Bernát Gábor `_, `de Brett Cannon `_. Para uma visão " +"humorística, leia sobre ZeroVer_." + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../source/flow.rst:3 +msgid "The Packaging Flow" +msgstr "O fluxo do empacotamento" + +#: ../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 "" +"O documento visa delinear o fluxo envolvido na publicação/distribuição de " +"um :term:`pacote de distribuição `, geralmente para o " +"`Python Package Index (PyPI)`_. Ele é escrito para editores de pacotes, que " +"são considerados os autores do pacote." + +#: ../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 "" +"Enquanto o :doc:`tutorial ` percorre o " +"processo de preparação de um pacote simples para lançamento, ele não enumera " +"completamente quais etapas e arquivos são necessários e para qual finalidade." + +#: ../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 "" +"A publicação de um pacote requer um fluxo do código-fonte do autor para o " +"ambiente Python de um usuário final. Os passos para conseguir isso são:" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" +"Tenha uma árvore de fontes contendo o pacote. Este é normalmente um checkout " +"de um sistema de controle de versão (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 "" +"Prepare um arquivo de configuração descrevendo os metadados do pacote (nome, " +"versão e assim por diante) e como criar os artefatos de construção. Para a " +"maioria dos pacotes, este será um arquivo :file:`pyproject.toml`, mantido " +"manualmente na árvore de fontes." + +#: ../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 "" +"Crie artefatos de construção para serem enviados ao serviço de distribuição " +"de pacotes (geralmente PyPI); normalmente serão uma :term:`distribuição " +"fonte (\"sdist\") ` e uma ou " +"mais :term:`distribuições construídas (\"wheels\") `. Eles são feitos por uma ferramenta de construção usando o " +"arquivo de configuração da etapa anterior. Muitas vezes, há apenas uma wheel " +"genérica para um pacote puro Python." + +#: ../source/flow.rst:35 +msgid "Upload the build artifacts to the package distribution service." +msgstr "" +"Envie os artefatos de construção para o serviço de distribuição de pacotes." + +#: ../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 "" +"Nesse ponto, o pacote está presente no serviço de distribuição de pacotes. " +"Para usar o pacote, os usuários finais devem:" + +#: ../source/flow.rst:40 +msgid "" +"Download one of the package's build artifacts from the package distribution " +"service." +msgstr "" +"Baixe um dos artefatos de construção do pacote do serviço de distribuição de " +"pacotes." + +#: ../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 "" +"Instale-o em seu ambiente Python, geralmente em seu diretório ``site-" +"packages``. Esta etapa pode envolver uma etapa de construção/compilação que, " +"se necessário, deve ser descrita pelos metadados do pacote." + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" +"Estes últimos 2 passos são normalmente executados por :ref:`pip` quando um " +"usuário final executa ``pip install``." + +#: ../source/flow.rst:50 +msgid "The steps above are described in more detail below." +msgstr "As etapas acima são descritas com mais detalhes abaixo." + +#: ../source/flow.rst:53 +msgid "The source tree" +msgstr "A árvore fonte" + +#: ../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 "" +"A árvore fonte contém o código-fonte do pacote, geralmente um checkout de um " +"VCS. A versão específica do código usado para criar os artefatos de " +"compilação normalmente será um checkout com base em uma tag associada à " +"versão." + +#: ../source/flow.rst:60 +msgid "The configuration file" +msgstr "O arquivo de configuração" + +#: ../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 "" +"O arquivo de configuração depende da ferramenta usada para criar os " +"artefatos de construção. A prática padrão é usar um " +"arquivo :file:`pyproject.toml` no `formato 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 "" +"No mínimo, o arquivo :file:`pyproject.toml` precisa de uma tabela ``[build-" +"system]`` especificando sua ferramenta de construção. Existem muitas " +"ferramentas de construção disponíveis, incluindo, mas não se limitando " +"a :ref:`flit`, :ref:`hatch`, :ref:`pdm`, :ref:`poetry`, :ref:`setuptools`, " +"`trampolim`_ e `whey`_. A documentação de cada ferramenta mostrará o que " +"colocar na tabela ``[build-system]``." + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "Por exemplo, aqui está uma tabela para usar :ref:`hatch`:" + +#: ../source/flow.rst:85 +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 "" +"Com tal tabela no arquivo :file:`pyproject.toml`, uma ferramenta " +"\":term:`frontend `\" como :ref:`build` pode executar o " +"\":term:`backend `\" da ferramenta de compilação escolhida " +"para criar os artefatos de compilação. Sua ferramenta de compilação também " +"pode fornecer seu próprio frontend. Uma ferramenta de instalação " +"como :ref:`pip` também atua como frontend quando executa o backend da sua " +"ferramenta de construção para instalar a partir de uma distribuição fonte." + +#: ../source/flow.rst:94 +msgid "" +"The particular build tool you choose dictates what additional information is " +"required in the :file:`pyproject.toml` file. For example, you might specify:" +msgstr "" +"A ferramenta de construção específica que você escolhe determina quais " +"informações adicionais são necessárias no arquivo :file:`pyproject.toml`. " +"Por exemplo, você pode especificar:" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" +"uma tabela ``[project]`` contendo os :doc:`Metadados Principais ` (nome, versão, autor e assim por diante)," + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" +"uma tabela ``[tool]`` contendo opções de configuração específicas da " +"ferramenta." + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" +"Consulte o :ref:`guia pyproject.toml ` para um guia " +"completo para a configuração de ``pyproject.toml``." + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "Artefatos de construção" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "A distribuição fonte (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 "" +"Uma distribuição fonte contém o suficiente para instalar o pacote fonte no " +"ambiente Python de um usuário final. Como tal, ele precisa da fonte do " +"pacote e também pode incluir testes e documentação. Eles são úteis para " +"usuários finais que desejam desenvolver suas fontes e para sistemas de " +"usuários finais onde alguma etapa de compilação local é necessária (como uma " +"extensão 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 "" +"O pacote :ref:`build` sabe como invocar sua ferramenta de construção para " +"criar uma destas:" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" +"Ou sua ferramenta de construção pode fornecer sua própria interface para " +"criar um sdist." + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "As distribuições de construídas (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 "" +"Uma distribuição construída contém apenas os arquivos necessários para o " +"ambiente Python de um usuário final. Nenhuma etapa de compilação é " +"necessária durante a instalação, e o arquivo wheel pode simplesmente ser " +"descompactado no diretório ``site-packages``. Isso torna a instalação mais " +"rápida e conveniente para os usuários finais." + +#: ../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 "" +"Um pacote puro Python normalmente precisa apenas de um wheel \"genérico\". " +"Um pacote com extensões binárias compiladas precisa de um wheel para cada " +"combinação suportada de interpretador Python, sistema operacional e " +"arquitetura de CPU que ele suporta. Se um arquivo wheel adequado não estiver " +"disponível, ferramentas como :ref:`pip` voltarão a instalar a distribuição " +"fonte." + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" +"Ou sua ferramenta de construção pode fornecer sua própria interface para " +"criar um wheel." + +#: ../source/flow.rst: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 "" +"O comportamento padrão do :ref:`build` é fazer tanto um sdist quanto um " +"wheel da fonte no diretório atual; os exemplos acima são deliberadamente " +"específicos." + +#: ../source/flow.rst:159 +msgid "Upload to the package distribution service" +msgstr "Enviando os arquivos de distribuição" + +#: ../source/flow.rst:161 +msgid "" +"The :ref:`twine` tool can upload build artifacts to PyPI for distribution, " +"using a command like:" +msgstr "" +"A ferramenta :ref:`twine` pode enviar artefatos de construção para PyPI para " +"distribuição, usando um comando como:" + +#: ../source/flow.rst:168 +msgid "Or, your build tool may provide its own interface for uploading." +msgstr "" +"Ou sua ferramenta de construção pode fornecer sua própria interface para " +"envio." + +#: ../source/flow.rst:171 +msgid "Download and install" +msgstr "Baixando e instalando" + +#: ../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 "" +"Agora que o pacote foi publicado, os usuários finais podem baixar e instalar " +"o pacote em seu ambiente Python. Normalmente isso é feito com :ref:`pip`, " +"usando um comando como:" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" +"Os usuários finais também podem usar outras ferramentas " +"como :ref:`pipenv`, :ref:`poetry` ou :ref:`pdm`." + +#: ../source/glossary.rst:3 +msgid "Glossary" +msgstr "Glossário" + +#: ../source/glossary.rst:8 +msgid "Binary Distribution" +msgstr "Distribuição Binária" + +#: ../source/glossary.rst:11 +msgid "" +"A specific kind of :term:`Built Distribution` that contains compiled " +"extensions." +msgstr "" +"Um tipo específico de :term:`Distribuição Construída` que contém extensões " +"compiladas." + +#: ../source/glossary.rst:14 +msgid "Build Backend" +msgstr "Backend de construção" + +#: ../source/glossary.rst:17 +#, fuzzy +msgid "" +"A library that takes a :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" +"Uma biblioteca que pega uma árvore de fontes ou :term:`distribuição fonte " +"` e constrói uma distribuição de código-" +"fonte ou :term:`wheel ` a partir dela. A construção é delegada ao " +"backend por um :term:`frontend `. Todos os backends oferecem " +"uma interface padronizada." + +#: ../source/glossary.rst:24 +msgid "" +"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 "" +"Exemplos de backends de construção são :ref:`flit-core do flit " +"`, :ref:`hatchling do hatch `, :ref:`maturin`, :ref:`meson-" +"python`, :ref:`scikit-build-core` e :ref:`setuptools`." + +#: ../source/glossary.rst:32 +msgid "Build Frontend" +msgstr "Frontend de construção" + +#: ../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 "" +"Uma ferramenta que os usuários podem executar que pega árvores de fontes " +"arbitrárias ou :term:`distribuições fonte ` e constrói distribuições fontes ou :term:`wheels ` a " +"partir delas. A construção real é delegada ao :term:`backend de construção " +"` de cada árvore de fontes." + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "Exemplos de frontends de construção são :ref:`pip` e :ref:`build`." + +#: ../source/glossary.rst:44 +msgid "Built Distribution" +msgstr "Distribuição Construída" + +#: ../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 :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 "" +"Um formato de :term:`Distribuição ` contendo arquivos " +"e metadados que só precisam ser movidos para o local correto no sistema de " +"destino, para serem instalados. :term:`Wheel` é esse formato, enquanto " +"o :term:`Distribuição Fonte ` não é, " +"pois requer uma etapa de construção antes de poder ser instalado. Este " +"formato não implica que os arquivos Python tenham que ser pré-compilados " +"(:term:`Wheel` intencionalmente não inclui arquivos Python compilados). " +"Veja :ref:`package-formats` para mais informações." + +#: ../source/glossary.rst:56 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +#, fuzzy +msgid "Core Metadata" +msgstr "Configurando metadados" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +#, fuzzy +msgid "Distribution Archive" +msgstr "Pacote de Distribuição" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "Pacote de Distribuição" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" +"Um arquivo com versão que contém :term:`pacotes ` " +"Python, :term:`módulos `, e outros arquivos de recursos que são " +"usados para distribuir um :term:`Release` (lançamento). O arquivo é o que um " +"usuário final irá baixar da Internet e instalar." + +#: ../source/glossary.rst:97 +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 "" +"Um pacote de distribuição é mais comumente referido com as palavras " +"\"pacote\" ou \"distribuição\", mas este guia pode usar o termo expandido " +"quando mais clareza for necessária para evitar confusão com um :term:`Pacote " +"de Importação` (que também é comumente chamado de \"pacote\") ou outro tipo " +"de distribuição (por exemplo, uma distribuição Linux ou a distribuição da " +"linguagem Python), que são frequentemente referidos com o único termo " +"\"distribuição\". Veja :ref:`distribution-package-vs-import-package` para " +"uma explicação das diferenças." + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "Egg" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" +"Um formato de :term:`Distribuição Construída` introduzido " +"pelo :ref:`setuptools`, que foi substituído pelo :term:`Wheel`. Para " +"detalhes, veja :ref:`egg-format`." + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "Módulo de Extensão" + +#: ../source/glossary.rst:114 +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 "" +"Um :term:`Módulo` escrito na linguagem de baixo nível da implementação " +"Python: C/C++ para Python, Java para Jython. Normalmente contido em um único " +"arquivo pré-compilado carregável dinamicamente, por exemplo, um arquivo de " +"objeto compartilhado (.so) para extensões Python no Unix, uma DLL (dada a " +"extensão .pyd) para extensões Python no Windows ou um arquivo de classe Java " +"para extensões Jython." + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "Pacote de Importação" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" +"Um módulo Python que pode conter outros módulos ou recursivamente, outros " +"pacotes." + +#: ../source/glossary.rst:127 +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 "" +"Um pacote de importação é mais comumente referido com a palavra \"pacote\", " +"mas este guia usará o termo expandido quando mais clareza for necessária " +"para evitar confusão com um :term:`Pacote de Distribuição` que também é " +"comumente chamado de \"pacote\" . Veja :ref:`distribution-package-vs-import-" +"package` para uma explicação das diferenças." + +#: ../source/glossary.rst:133 +#, fuzzy +msgid "Installed Project" +msgstr "Instalador" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "Known Good Set (KGS)" + +#: ../source/glossary.rst:143 +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 "" +"Um conjunto de distribuições em versões especificadas que são compatíveis " +"entre si. Normalmente, será executado um conjunto de testes que passa em " +"todos os testes antes que um conjunto específico de pacotes seja declarado " +"como um conjunto sabidamente bom (*known good set*). Este termo é comumente " +"usado por frameworks e kits de ferramentas que são compostos de várias " +"distribuições individuais." + +#: ../source/glossary.rst:149 +#, fuzzy +#| msgid "classifiers" +msgid "License Classifier" +msgstr "classifiers" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "Expressão de licença" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +#, fuzzy +#| msgid "Local version identifiers" +msgid "License Identifier" +msgstr "Identificadores de versão local" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "Módulo" + +#: ../source/glossary.rst:186 +msgid "" +"The basic unit of code reusability in Python, existing in one of two " +"types: :term:`Pure Module`, or :term:`Extension Module`." +msgstr "" +"A unidade básica de reutilização de código em Python, existindo em um dos " +"dois tipos: :term:`Módulo Puro` ou :term:`Módulo de Extensão`." + +#: ../source/glossary.rst:189 +msgid "Package Index" +msgstr "Índice de Pacotes" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" +"Um repositório de distribuições com uma interface web para automatizar " +"descoberta e consumo de :term:`pacotes `." + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "Índice Por Projeto" + +#: ../source/glossary.rst:198 +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 "" +"Um :term:`Índice de Pacotes` privado ou outro não canônico indicado por " +"um :term:`Projeto` específico como o índice preferido ou necessário para " +"resolver dependências desse projeto." + +#: ../source/glossary.rst:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "Projeto" + +#: ../source/glossary.rst:205 +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 "" +"Uma biblioteca, estrutura, script, plugin, aplicação ou coleção de dados ou " +"outros recursos, ou alguma combinação dos mesmos que se destina a ser " +"empacotado em uma :term:`Distribuição `." + +#: ../source/glossary.rst:209 +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 "" +"Como a maioria dos projetos cria :term:`Distribuições ` usando ``build-system`` da :pep:`518`, :ref:`distutils` " +"ou :ref:`setuptools`, outra maneira prática de definir projetos atualmente é " +"algo que contém um arquivo :term:`pyproject.toml`, :term:`setup.py` " +"ou :term:`setup.cfg` na raiz do diretório fonte do projeto." + +#: ../source/glossary.rst:215 +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 "" +"Projetos Python devem ter nomes únicos, que são registrados no :term:`PyPI " +"`. Cada projeto conterá então um ou " +"mais :term:`Lançamentos `, e cada lançamento pode incluir uma ou " +"mais :term:`distribuições `." + +#: ../source/glossary.rst:220 +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 "" +"Observe que há uma forte convenção para dar o nome do projeto ao pacote que " +"é importado para executar esse projeto. No entanto, isso não é obrigatório. " +"É possível instalar uma distribuição do projeto \"foo\" e fazer com que ele " +"forneça um pacote importável apenas como \"bar\"." + +#: ../source/glossary.rst:226 +#, fuzzy +msgid "Project Root Directory" +msgstr "Projetos em subdiretórios" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +#, fuzzy +msgid "Project Source Tree" +msgstr "Resumos de projetos" + +#: ../source/glossary.rst:235 +#, fuzzy +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" +"Um arquivo contendo o código-fonte bruto para um :term:`Lançamento " +"`, antes da criação de uma :term:`Distribuição Fonte ` ou :term:`Distribuição Construída `." + +#: ../source/glossary.rst:241 +#, fuzzy +msgid "Project Source Metadata" +msgstr "Resumos de projetos" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "Módulo Puro" + +#: ../source/glossary.rst:257 +msgid "" +"A :term:`Module` written in Python and contained in a single ``.py`` file " +"(and possibly associated ``.pyc`` and/or ``.pyo`` files)." +msgstr "" +"Um :term:`Módulo` escrito em Python e contido em um único arquivo ``.py`` (e " +"possivelmente arquivos ``.pyc`` e/ou ``.pyo`` associados)." + +#: ../source/glossary.rst:260 +#, fuzzy +msgid "Pyproject Metadata" +msgstr "Nome do projeto" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +#, fuzzy +msgid "Pyproject Metadata Key" +msgstr "Declarando os metadados do projeto" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "Python Packaging Authority (PyPA)" + +#: ../source/glossary.rst:287 +#, fuzzy +#| 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 `__." +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" +"PyPA é um grupo de trabalho que mantém muitos dos projetos relevantes em " +"pacotes Python. Eles mantêm um site em :doc:`pypa.io `, hospedam " +"projetos no `GitHub `_ e `Bitbucket `_, e discutem questões na `lista de discussão distutils-" +"sig `_ e " +"`o fórum Discourse do Python `__." + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "Python Package Index (PyPI)" + +#: ../source/glossary.rst:298 +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 `_ é o :term:`Índice de Pacotes` padrão para a " +"comunidade Python. Está aberto a todos os desenvolvedores Python para " +"consumir e distribuir suas distribuições." + +#: ../source/glossary.rst:301 +msgid "pypi.org" +msgstr "pypi.org" + +#: ../source/glossary.rst:304 +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 `_ é o nome de domínio do :term:`Python Package " +"Index (PyPI)`. Ele substituiu o nome de domínio do índice legado, " +"``pypi.python.org``, em 2017. Ele é tornado possível pelo :ref:`warehouse`." + +#: ../source/glossary.rst:308 +msgid "pyproject.toml" +msgstr "pyproject.toml" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" +"O arquivo de especificação agnóstica de ferramenta para :term:`Projetos " +"`. Definido na :pep:`518`." + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "Lançamento" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" +"Um snapshot de um :term:`Projeto` em um determinado ponto no tempo, denotado " +"por um identificador de versão." + +#: ../source/glossary.rst:319 +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 "" +"Fazer um lançamento pode implicar na publicação de " +"várias :term:`Distribuições `. Por exemplo, se a " +"versão 1.0 de um projeto foi lançada, ele pode estar disponível em um " +"formato de distribuição fonte e um formato de distribuição de instalador do " +"Windows." + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "Requisito" + +#: ../source/glossary.rst:327 +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 "" +"Uma especificação para um :term:`pacote ` a ser " +"instalado. :ref:`pip`, o instalador recomendado do :term:`PYPA `, permite várias formas de especificação que " +"podem ser consideradas um \"requisito\". Para obter mais informações, " +"consulte a referência de :ref:`pip:pip install`." + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "Especificador de Requisitos" + +#: ../source/glossary.rst:336 +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 "" +"Um formato usado por :ref:`pip` para instalar pacotes de um :term:`Índice de " +"Pacotes`. Para um diagrama EBNF do formato, veja :ref:`dependency-" +"specifiers`. Por exemplo, \"foo>=1.3\" é um especificador de requisitos, " +"onde \"foo\" é o nome do projeto e a parte \">=1.3\" é " +"o :term:`Especificador de Versão`" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "Arquivo de Requisitos" + +#: ../source/glossary.rst:344 +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 "" +"Um arquivo contendo uma lista de :term:`Requisitos ` que podem " +"ser instalados usando :ref:`pip`. Para mais informações, veja a " +"documentação :ref:`pip` em :ref:`pip:Requirements Files`." + +#: ../source/glossary.rst:348 +#, fuzzy +msgid "Root License Directory" +msgstr "Projetos em subdiretórios" + +#: ../source/glossary.rst:349 +#, fuzzy +#| msgid "Local directory:" +msgid "License Directory" +msgstr "Diretório local:" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "setup.py" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "setup.cfg" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" +"Os arquivos de especificação do projeto para :ref:`distutils` " +"e :ref:`setuptools`. Veja também :term:`pyproject.toml`." + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "Arquivo Fonte" + +#: ../source/glossary.rst:375 +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 "" +"Um arquivo contendo o código-fonte bruto para um :term:`Lançamento " +"`, antes da criação de uma :term:`Distribuição Fonte ` ou :term:`Distribuição Construída `." + +#: ../source/glossary.rst:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "Distribuição Fonte (ou \"sdist\")" + +#: ../source/glossary.rst:382 +#, fuzzy +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." +msgstr "" +"Um formato de :term:`distribuição ` (geralmente gerado " +"usando ``python -m build sdist``) que fornece metadados e os arquivos-fonte " +"essenciais necessários para a instalação por uma ferramenta como :ref:`pip`, " +"ou para gerar uma :term:`Distribuição Construída `. " +"Veja :ref:`package-formats` para mais informações." + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "Pacote de Sistemas" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" +"Um pacote fornecido em um formato nativo para o sistema operacional, por " +"exemplo, um arquivo rpm ou dpkg." + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "Especificador de Versão" + +#: ../source/glossary.rst:397 +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 "" +"O componente de versão de um :term:`Especificador de Requisitos `. Por exemplo, a parte \">=1.3\" de \"foo>=1.3\". Leia " +"a :ref:`especificação de especificador de versão ` para a " +"especificação completa dos especificadores que o empacotamento do Python " +"oferece suporte atualmente. O suporte para esta especificação foi " +"implementado no :ref:`setuptools` v8.0 e no :ref:`pip` v6.0." + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "Ambiente Virtual" + +#: ../source/glossary.rst:405 +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 "" +"Um ambiente Python isolado que permite que os pacotes sejam instalados para " +"uso por uma aplicação específica, em vez de serem instalados em todo o " +"sistema. Para obter mais informações, consulte a seção sobre :ref:`Creating " +"and using Virtual Environments`." + +#: ../source/glossary.rst:410 +#, fuzzy +msgid "Wheel Format" +msgstr "Formato de arquivos" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "Wheel" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +#, fuzzy +msgid "Wheel Project" +msgstr "Projeto" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "Conjunto de Trabalho" + +#: ../source/glossary.rst:429 +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 "" +"Uma coleção de :term:`distribuições ` disponíveis para " +"importação. Estas são as distribuições que estão na variável `sys.path`. No " +"máximo, uma :term:`Distribuição ` para um projeto é " +"possível em um conjunto de trabalho." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "Analisando downloads de pacotes PyPI" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" +"Esta seção cobre como usar o conjunto de dados de estatísticas de download " +"público do PyPI para saber mais sobre os downloads de um pacote (ou pacotes) " +"hospedado no PyPI. Por exemplo, você pode usá-lo para descobrir a " +"distribuição das versões do Python usadas para baixar um pacote." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "Contexto" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "O PyPI não exibe estatísticas de download por vários motivos: [#]_" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" +"**Ineficiente para fazer funcionar com uma Rede de Distribuição de Conteúdo " +"(CDN):** As estatísticas de download mudam constantemente. Incluí-las nas " +"páginas do projeto, que são altamente armazenadas em cache, exigiria a " +"invalidação do cache com mais frequência e reduziria a eficácia geral do " +"cache." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +msgid "" +"**Highly inaccurate:** A number of things prevent the download counts from " +"being accurate, some of which include:" +msgstr "" +"**Altamente imprecisa:** Várias coisas impedem que as contagens de download " +"sejam precisas, algumas das quais incluem:" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "Cache de download do ``pip`` (diminui a contagem de downloads)" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" +"Espelhos internos ou não oficiais (pode aumentar ou diminuir as contagens de " +"download)" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "Pacotes não hospedados no PyPI (para fins de comparação)" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" +"Scripts não oficiais ou tentativas de aumento da contagem de download " +"(aumenta a contagem de downloads)" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" +"Problemas conhecidos de qualidade de dados históricos (diminui a contagem de " +"downloads)" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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 "" +"**Não é particularmente útil:** Só porque um projeto foi muito baixado, não " +"significa que ele seja bom; Da mesma forma, só porque um projeto não foi " +"muito baixado, não significa que ele seja ruim!" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:37 +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 "" +"Resumindo, como seu valor é baixo por vários motivos e as compensações " +"necessárias para fazê-lo funcionar são altas, não tem sido um uso eficaz de " +"recursos limitados." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:42 +msgid "Public dataset" +msgstr "Conjunto de dados públicos" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" +"Como alternativa, o `projeto Linehaul `__ transmite registros de download do PyPI para o `Google " +"BigQuery`_ [#]_, onde são armazenados como um conjunto de dados público." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "Preparando-se" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" +"Para usar o `Google BigQuery`_ para consultar o `conjunto de dados público " +"de estatísticas de download do PyPI`_, você precisará de uma conta do Google " +"e habilitar a API do BigQuery em um projeto do Google Cloud Platform. Você " +"pode executar até 1 TB de consultas por mês `usando o free tier do BigQuery " +"sem um cartão de crédito `__" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "Acesse a `interface web do BigQuery`_." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "Crie um novo projeto." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" +"Habilite a `BigQuery API `__." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" +"Para obter instruções mais detalhadas sobre como começar a usar o BigQuery, " +"consulte o `guia de início rápido do BigQuery `__." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "Esquema de dados" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" +"Linehaul escreve uma entrada em uma tabela ``bigquery-public-" +"data.pypi.file_downloads`` para cada download. A tabela contém informações " +"sobre qual arquivo foi baixado e como foi baixado. Algumas colunas úteis do " +"`esquema da tabela `__ inclui:" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "Coluna" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "Descrição" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "Exemplos" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "timestamp" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "Data e hora" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "``2020-03-09 00:33:03 UTC``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "file.project" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "Nome do projeto" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "``pipenv``, ``nose``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "file.version" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "Versão do pacote" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "``0.1.6``, ``1.4.2``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "details.installer.name" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "Instalador" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "pip, :ref:`bandersnatch`" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "details.python" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "Versão do Python" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "``2.7.12``, ``3.6.4``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "Consultas úteis" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" +"Executa consultas na `interface web do BigQuery`_ clicando no botão " +"\"Compose query\"." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" +"Observe que as linhas são armazenadas em uma tabela particionada, o que " +"ajuda a limitar o custo das consultas. Essas consultas de exemplo analisam " +"downloads do histórico recente filtrando na coluna ``timestamp``." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "Contando downloads de pacotes" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" +"A consulta a seguir conta o número total de downloads do projeto \"pytest\"." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "num_downloads" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "26190085" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" +"Para contar apenas os downloads do pip, filtre na coluna " +"``details.installer.name``." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "24334215" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "Downloads de pacotes ao longo do tempo" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" +"Para agrupar por downloads mensais, use a função ``TIMESTAMP_TRUNC``. Além " +"disso, a filtragem por esta coluna reduz os custos correspondentes." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "mês" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "1956741" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "2018-01-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "2344692" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "2017-12-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "1730398" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "2017-11-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "2047310" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "2017-10-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "1744443" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "2017-09-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "1916952" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "2017-08-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "Versões Python ao longo do tempo" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" +"Extrai a versão Python da coluna ``details.python``. Aviso: esta consulta " +"processa mais de 500 GB de dados." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "python" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "3.7" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "18051328726" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "3.6" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "9635067203" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "3.8" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "7781904681" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "2.7" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "6381252241" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "null" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "2026630299" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "3.5" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "1894153540" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "Obtendo links absolutos para artefatos" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" +"Às vezes, é útil ser capaz de obter os links absolutos para baixar artefatos " +"de PyPI com base em seus hashes, por exemplo, se um determinado projeto ou " +"versão foi excluído de PyPI. A tabela de metadados inclui a coluna ``path``, " +"que inclui o hash e o nome do arquivo do artefato." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" +"Não é garantido que a URL gerada aqui seja estável, mas atualmente está " +"alinhada com a URL onde os artefatos PyPI estão hospedados." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "url" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +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/analyzing-pypi-package-downloads.rst:246 +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/analyzing-pypi-package-downloads.rst:248 +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/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "Ressalvas" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" +"Além das advertências listadas no histórico acima, Linehaul sofreu de um bug " +"que causou um subestimamento das estatísticas de download antes de 26 de " +"julho de 2018. Downloads antes dessa data são proporcionalmente precisos " +"(por exemplo, a porcentagem de Python 2 vs. Python 3 downloads), mas os " +"números totais são menores do que o real em uma ordem de magnitude." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "Ferramentas adicionais" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" +"Além de usar o console do BigQuery, existem algumas ferramentas adicionais " +"que podem ser úteis ao analisar estatísticas de download." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "``google-cloud-bigquery``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" +"Você também pode acessar o conjunto de dados público de estatísticas de " +"download PyPI de maneira programática por meio da API do BigQuery e do " +"projeto `google-cloud-bigquery`_, a biblioteca cliente oficial do Python " +"para BigQuery." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "``pypinfo``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" +"`pypinfo`_ é uma ferramenta de linha de comando que fornece acesso ao " +"conjunto de dados e pode gerar várias consultas úteis. Por exemplo, você " +"pode consultar o número total de downloads de um pacote com o comando " +"``pypinfo package_name``." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "Instale `pypinfo`_ usando o pip." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "Uso:" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "``pandas-gbq``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" +"O projeto `pandas-gbq`_ permite acessar resultados de pesquisa com `Pandas`_." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "Referências" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" +"`E-mail de descontinuação das contagens de download do PyPI `__" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" +"`E-mail de anúncio do conjunto de dados BigQuery do PyPI `__" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "Criando e descobrindo plug-ins" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" +"Frequentemente, ao criar uma aplicação ou biblioteca Python, você desejará " +"ter a capacidade de fornecer personalizações ou recursos extras por meio de " +"**plug-ins**. Como os pacotes Python podem ser distribuídos separadamente, " +"sua aplicação ou biblioteca pode querer **descobrir** automaticamente todos " +"os plugins disponíveis." + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" +"Existem três abordagens principais para fazer a descoberta automática de " +"plugins:" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "`Usando convenção de nomenclatura`_." + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "`Usando pacotes de espaço de nomes`_." + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "`Usando metadados de pacote`_." + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "Usando convenção de nomenclatura" + +#: ../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 "" +"Se todos os plugins para sua aplicação seguem a mesma convenção de " +"nomenclatura, você pode usar :func:`pkgutil.iter_modules` para descobrir " +"todos os módulos de nível superior que correspondem à convenção de " +"nomenclatura. Por exemplo, `Flask`_ usa a convenção de nomenclatura " +"``flask_{nome_plugin}``. Se você quiser descobrir automaticamente todos os " +"plugins Flask instalados:" + +#: ../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 "" +"Se você tivesse os plugins `Flask-SQLAlchemy`_ e `Flask-Talisman`_ " +"instalados, então ``discover_plugins`` seria:" + +#: ../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 "" +"Usar a convenção de nomenclatura para plugins também permite que você " +"consulte a :ref:`API de repositório simples ` do " +"Índice de Pacotes Python para todos os pacotes que estão em conformidade com " +"a sua convenção de nomenclatura." + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "Usando pacotes de espaço de nomes" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" +":doc:`Pacotes de espaços de nome ` podem ser " +"usados para fornecer uma convenção de onde colocar plugins e também fornece " +"uma maneira de realizar a descoberta. Por exemplo, se você fizer do " +"subpacote ``myapp.plugins`` um pacote de espaço de nomes, então " +"outras :term:`distribuições ` pode fornecer módulos e " +"pacotes para aquele espaço de nomes. Uma vez instalado, você pode " +"usar :func:`pkgutil.iter_modules` para descobrir todos os módulos e pacotes " +"instalados sob esse espaço de nomes:" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" +"Especificar ``myapp.plugins.__path__`` para :func:`~pkgutil.iter_modules` " +"faz com que ele procure apenas os módulos diretamente sob aquele espaço de " +"nomes. Por exemplo, se você instalou distribuições que fornecem os módulos " +"``myapp.plugins.a`` e ``myapp.plugins.b``, então ``found_plugins`` neste " +"caso seria:" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" +"Este exemplo usa um subpacote como o pacote de espaço de nomes " +"(``myapp.plugins``), mas também é possível usar um pacote de nível superior " +"para este propósito (como ``myapp_plugins``). Como escolher o espaço de " +"nomes a ser usado é uma questão de preferência, mas não é recomendado fazer " +"do pacote de nível superior principal do seu projeto (``myapp``, neste caso) " +"um pacote de espaço de nomes para fins de plugins, como um plugin ruim " +"poderia fazer com que todo o espaço de nomes seja interrompido, o que, por " +"sua vez, tornaria seu projeto não importável. Para que a abordagem de " +"\"subpacote de espaço de nomes\" funcione, os pacotes de plugin devem omitir " +"o :file:`__init__.py` para o diretório de pacote de nível superior " +"(``myapp``, neste caso) e incluir o estilo de pacote de espaço de " +"nomes :file:`__init__.py` no diretório do subpacote de espaço de nomes " +"(``myapp/plugins``). Isso também significa que os plugins precisarão passar " +"explicitamente uma lista de pacotes para o argumento ``packages`` " +"de :func:`setup` ao invés de usar :func:`setuptools.find_packages`." + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" +"Os pacotes de espaço de nomes são um recurso complexo e existem várias " +"maneiras diferentes de criá-los. É altamente recomendado ler a documentação " +"de :doc:`packaging-namespace-packages` e documentar claramente qual " +"abordagem é preferida para plugins em seu projeto." + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "Usando metadados de pacote" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" +"Os pacotes podem ter metadados para plugins descritos em :ref:`entry-" +"points`. Ao especificá-los, um pacote anuncia que contém um tipo específico " +"de plug-in. Outro pacote que suporta esse tipo de plug-in pode usar os " +"metadados para descobrir esse plug-in." + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" +"Por exemplo, se você tem um pacote chamado ``myapp-plugin-a`` e ele inclui o " +"seguinte em seu :file:`pyproject.toml`:" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" +"Então você pode descobrir e carregar todos os pontos de entrada registrados " +"usando :func:`importlib.metadata.entry_points` (ou o backport_ " +"``importlib_metadata >= 3.6`` para Python 3.6-3.9):" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" +"Neste exemplo, ``discover_plugins`` seria uma coleção do " +"tipo :class:`importlib.metadata.EntryPoint`:" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" +"Agora o módulo de sua escolha pode ser importado executando " +"``discovered_plugins['a'].Load()``." + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" +"A especificação ``entry_point`` em :file:`setup.py` é bastante flexível e " +"tem muitas opções. É recomendado ler toda a seção sobre :doc:`pontos de " +"entrada ` ." + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" +"Visto que esta especificação é parte da :doc:`biblioteca padrão " +"`, a maioria das ferramentas de " +"empacotamento, exceto setuptools, fornecem suporte para definir pontos de " +"entrada." + +#: ../source/guides/creating-command-line-tools.rst:5 +#, fuzzy +msgid "Creating and packaging command-line tools" +msgstr "Instalando ferramentas de linha de comando autônomas" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +#, fuzzy +msgid "Creating the package" +msgstr "Criando arquivos do pacote" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "Para fazer" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +#, fuzzy +msgid "``pyproject.toml``" +msgstr "pyproject.toml" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +#, fuzzy +msgid "Installing the package with ``pipx``" +msgstr "Instalar pacotes usando pip" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +#, fuzzy +msgid "Conclusion" +msgstr "Especificador de Versão" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "Empacotando e distribuindo projetos" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "Desatualizada" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "2023-12-14" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" +"Esta seção cobre alguns detalhes adicionais sobre configuração, " +"empacotamento e distribuição de projetos Python com ``setuptools`` que não " +"são cobertos pelo tutorial introdutório em :doc:`/tutorials/packaging-" +"projects`. Ele ainda assume que você já está familiarizado com o conteúdo da " +"página :doc:`/tutorials/installing-packages`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" +"A seção *não* visa cobrir as melhores práticas para o desenvolvimento de " +"projetos Python como um todo. Por exemplo, ele não fornece orientação ou " +"recomendações de ferramentas para controle de versão, documentação ou teste." + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" +"Para mais material de referência, veja :std:doc:`Construindo e Distribuindo " +"Pacotes ` na documentação :ref:`setuptools`, mas " +"note que alguns conteúdos de aviso podem estar desatualizados. No caso de " +"conflitos, dê preferência ao conselho do Guia de Usuário para Empacotamento " +"de Python." + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "Requisitos para empacotamento e distribuição" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" +"Primeiro, certifique-se de que você já cumpriu os :ref:`requisitos para " +"instalação de pacotes `." + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "Instale \"twine\" [1]_:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" +"Você precisará disso para enviar as :term:`distribuições ` do seu projeto para o :term:`PyPI ` " +"(veja :ref:`abaixo `)." + +#: ../source/guides/distributing-packages-using-setuptools.rst:52 +msgid "Configuring your project" +msgstr "Configurando seu projeto" + +#: ../source/guides/distributing-packages-using-setuptools.rst:56 +msgid "Initial files" +msgstr "Arquivos iniciais" + +#: ../source/guides/distributing-packages-using-setuptools.rst:61 +msgid "" +"The most important file is :file:`setup.py` which exists at the root of your " +"project directory. For an example, see the `setup.py `_ " +"in the `PyPA sample project `_." +msgstr "" +"O arquivo mais importante é :file:`setup.py` que existe na raiz do diretório " +"do seu projeto. Para obter um exemplo, consulte o `setup.py `_ no `projeto de exemplo PyPA `_." + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr ":file:`setup.py` tem duas funções principais:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" +"É o arquivo onde vários aspectos do seu projeto são configurados. A " +"principal característica do :file:`setup.py` é que ele contém uma função " +"global ``setup()``. Os argumentos nomeados para esta função são como os " +"detalhes específicos do seu projeto são definidos. Os argumentos mais " +"relevantes são explicados em :ref:`a seção abaixo de `." + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" +"É a interface de linha de comando para executar vários comandos relacionados " +"a tarefas de empacotamento. Para obter uma lista dos comandos disponíveis, " +"execute ``python3 setup.py --help-commands``." + +#: ../source/guides/distributing-packages-using-setuptools.rst: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` é um arquivo ini que contém opções padrão para os " +"comandos :file:`setup.py`. Para obter um exemplo, consulte o `setup.cfg " +"`_ no `projeto de exemplo " +"PyPA `_." + +#: ../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 "" +"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 "" +"Todos os projetos devem conter um arquivo leia-me que cubra o objetivo do " +"projeto. O formato mais comum é `reStructuredText `_ com uma extensão \"rst\", embora isso " +"não seja um requisito; múltiplas variantes do `Markdown `_ também são suportadas (veja o " +"argumento :ref:`long_description_content_type ` do ``setup()``)." + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" +"Para obter um exemplo, consulte o `README.md `_ do `projeto de exemplo PyPA `_." + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" +"Projetos usando :ref:`setuptools` 0.6.27+ têm arquivos leia-me padrão " +"(:file:`README.rst`, :file:`README.txt` ou :file:`README`) incluídos nas " +"distribuições de código-fonte por padrão. A biblioteca " +"interna :ref:`distutils` adota este comportamento a partir do Python 3.7. " +"Adicionalmente, :ref:`setuptools` 36.4.0+ incluirá um :file:`README.md` se " +"encontrado. Se você estiver usando setuptools, você não precisa listar seu " +"arquivo leia-me em :file:`MANIFEST.in`. Caso contrário, inclua para ser " +"explícito." + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "MANIFEST.in" + +#: ../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 "" +"Um :file:`MANIFEST.in` é necessário quando você precisa empacotar arquivos " +"adicionais que não são incluídos automaticamente em uma distribuição de " +"código-fonte. Para obter detalhes sobre como escrever um " +"arquivo :file:`MANIFEST.in`, incluindo uma lista do que é incluído por " +"padrão, consulte \":ref:`Using MANIFEST.in`\"." + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" +"No entanto, você pode não ter que usar um :file:`MANIFEST.in`. Por exemplo, " +"o `projeto de amostra PyPA `_ removeu " +"seu arquivo de manifesto, uma vez que todos os arquivos necessários foram " +"incluídos pelo :ref:`setuptools` 43.0.0 e mais recentes." + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr ":file:`MANIFEST.in` não afeta distribuições binárias como wheels." + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "LICENSE.txt" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" +"Cada pacote deve incluir um arquivo de licença detalhando os termos de " +"distribuição. Em muitas jurisdições, os pacotes sem uma licença explícita " +"não podem ser legalmente usados ou distribuídos por ninguém que não seja o " +"detentor dos direitos autorais. Se não tiver certeza de qual licença " +"escolher, você pode usar recursos como `Escolha uma licença do GitHub " +"`_ ou consultar um advogado." + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" +"Para obter um exemplo, consulte o `LICENSE.txt `_ do `projeto de exemplo PyPA `_." + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" +"Embora não seja obrigatório, a prática mais comum é incluir seus módulos e " +"pacotes Python em um único pacote de nível superior que tem o " +"mesmo :ref:`name ` do seu projeto, ou algo muito próximo." + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" +"Para obter um exemplo, consulte o pacote de `exemplo `_ que está incluído no `projeto de " +"exemplo PyPA `_." + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "Argumentos de setup()" + +#: ../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 "" +"Como mencionado acima, o principal recurso do :file:`setup.py` é que ele " +"contém uma função global ``setup()``. Os argumentos nomeados para esta " +"função são como os detalhes específicos do seu projeto são definidos." + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" +"Alguns são temporariamente explicados abaixo até que suas informações sejam " +"movidas em outros lugares. A lista completa pode ser encontrada :doc:`na " +"documentação setuptools `." + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" +"A maioria dos fragmentos fornecidos são retirados do `setup.py `_ contido no `projeto de exemplo do PyPA `_." + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" +"Veja :ref:`Escolhendo um esquema de versionamento ` para mais informações sobre maneiras de usar versões para " +"transmitir informações de compatibilidade para seus usuários." + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "``packages``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" +"Defina ``packages`` para uma lista de todos :term:`pacotes ` " +"em seu projeto, incluindo seus subpacotes, sub-subpacotes, etc. Embora os " +"pacotes possam ser listados manualmente, ``setuptools.find_packages()`` " +"encontra-os automaticamente. Use o argumento nomeado ``include`` para " +"encontrar apenas os pacotes fornecidos. Use o argumento nomeado ``exclude`` " +"para omitir pacotes que não devem ser lançados e instalados." + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +msgstr "``py_modules``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:198 +msgid "" +"If your project contains any single-file Python modules that aren't part of " +"a package, set ``py_modules`` to a list of the names of the modules (minus " +"the ``.py`` extension) in order to make :ref:`setuptools` aware of them." +msgstr "" +"Se o seu projeto contém qualquer módulo Python de arquivo único que não faz " +"parte de um pacote, defina ``py_modules`` para uma lista dos nomes dos " +"módulos (menos a extensão ``.py``) para fazer o :ref:`setuptools` ficar " +"ciente deles." + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +#, fuzzy +msgid "``install_requires``" +msgstr "install_requires" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" +"\"install_requires\" deve ser usado para especificar quais dependências um " +"projeto precisa minimamente para ser executado. Quando o projeto é instalado " +"pelo :ref:`pip`, esta é a especificação que é usada para instalar suas " +"dependências." + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" +"Para mais informações sobre como usar \"install_requires\", " +"veja :ref:`install_requires vs Arquivos de requisitos `." + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "``package_data``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"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 "" +"Frequentemente, arquivos adicionais precisam ser instalados em " +"um :term:`pacote `. Esses arquivos geralmente são dados " +"intimamente relacionados à implementação do pacote ou arquivos de texto " +"contendo documentação que pode ser do interesse dos programadores que usam o " +"pacote. Esses arquivos são chamados de \"dados do pacote\"." + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" +"O valor deve ser um mapeamento do nome do pacote para uma lista de nomes de " +"caminhos relativos que devem ser copiados para o pacote. Os caminhos são " +"interpretados como relativos ao diretório que contém o pacote." + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" +"Para mais informações, veja :std:doc:`Incluindo arquivos de dados " +"` da :std:doc:`documentação do setuptools " +"`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "``data_files``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" +"Embora configurar :ref:`Dados de pacote ` seja suficiente para " +"a maioria das necessidades, em alguns casos você pode precisar colocar " +"arquivos de dados *fora* de seus :term:`pacotes `. A " +"diretiva ``data_files`` permite que você faça isso. É mais útil se você " +"precisar instalar arquivos que são usados por outros programas, que podem " +"não ter conhecimento dos pacotes Python." + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"Cada par ``(directory, files)`` na sequência especifica o diretório de " +"instalação e os arquivos a serem instalados nele. O ``directory`` deve ser " +"um caminho relativo (embora isso possa mudar no futuro, consulte `relatório " +"de problema #92 do wheel `_) e é " +"interpretado em relação ao prefixo de instalação (``sys.prefix`` do Python " +"para uma instalação padrão; ``site.USER_BASE`` para uma instalação do " +"usuário). Cada nome de arquivo em ``files`` é interpretado em relação ao " +"script :file:`setup.py` no topo da distribuição do código-fonte do projeto." + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" +"Para obter mais informações, consulte a seção distutils em :ref:`Instalando " +"arquivos adicionais `." + +#: ../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 "" +"Ao instalar pacotes como ovo, ``data_files`` não é suportado. Então, se seu " +"projeto usa :ref:`setuptools`, você deve usar ``pip`` para instalá-lo. " +"Alternativamente, se você deve usar ``python setup.py``, então você precisa " +"passar a opção ``--old-and-unmanageable``." + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +#, fuzzy +msgid "``scripts``" +msgstr "scripts" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" +"Embora ``setup()`` tenha suporte a uma palavra-chave :ref:`scripts " +"` para apontar para scripts pré-" +"fabricados para instalar, o recomendado A abordagem para obter " +"compatibilidade entre plataformas é usar pontos de " +"entrada :ref:`console_scripts` (veja abaixo)." + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "Escolhendo um esquema de versionamento" + +#: ../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 "" +"Veja :ref:`versioning` para informações sobre esquemas de versões comuns e " +"como escolher entre eles." + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "Trabalhando em \"modo de desenvolvimento\"" + +#: ../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 "" +"Você pode instalar um projeto em modo \"editável\" ou \"desenvolvedor\" " +"enquanto trabalha nele. Quando instalado como editável, um projeto pode ser " +"editado no local sem reinstalação: alterações nos arquivos fonte Python em " +"projetos instalados como editáveis serão refletidas na próxima vez que um " +"processo de interpretador for iniciado." + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" +"Para instalar um pacote Python no modo \"editável\"/\"desenvolvedor\" mude o " +"diretório para a raiz do diretório do projeto e execute:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" +"O sinalizador de linha de comando do pip ``-e`` é abreviação de ``--" +"editable``, e ``.`` refere-se ao diretório de trabalho atual, então juntos, " +"isso significa instalar o diretório atual (ou seja, seu projeto) em modo " +"editável. Isso também instalará quaisquer dependências declaradas com " +"``install_requires`` e quaisquer scripts declarados com ``console_scripts``. " +"As dependências serão instaladas no modo usual e não editável." + +#: ../source/guides/distributing-packages-using-setuptools.rst: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::" +msgstr "" +"Você também pode querer instalar algumas de suas dependências no modo " +"editável. Por exemplo, supondo que seu projeto requer \"foo\" e \"bar\", mas " +"você deseja \"bar\" instalado do VCS no modo editável, então você poderia " +"construir um arquivo de requisitos como::" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"A primeira linha diz para instalar seu projeto e todas as dependências. A " +"segunda linha substitui a dependência \"bar\", de modo que seja preenchida a " +"partir do VCS, não PyPI." + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"Se, no entanto, você quiser \"bar\" instalado de um diretório local em modo " +"editável, o arquivo de requisitos deve ser semelhante a este, com os " +"caminhos locais no topo do arquivo::" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" +"Caso contrário, a dependência será resolvida pelo PyPI, devido à ordem de " +"instalação do arquivo de requisitos. Para mais informações sobre os arquivos " +"de requisitos, consulte a seção :ref:`Requirements File ` na documentação do pip. Para obter mais informações sobre as " +"instalações de VCS, consulte a seção :ref:`VCS Support ` da " +"documentação do pip." + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" +"Por último, se você não deseja instalar nenhuma dependência, pode executar:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" +"Para mais informações, veja a seção :doc:`Development Mode " +"` na documentação " +"do :ref:`setuptools`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "Empacotando seu projeto" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" +"Para ter seu projeto instalável de um :term:`Índice de Pacotes` como " +"o :term:`PyPI `, você precisará criar " +"uma :term:`Distribuição ` (também conhecida como " +"\":term:`Pacote `\") para seu projeto." + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" +"Antes de compilar wheels e sdists para seu projeto, você precisará instalar " +"o pacote ``build``:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "Distribuições fontes" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" +"Minimamente, você deve criar uma :term:`Distribuição Fonte `:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" +"Uma \"distribuição fonte\" é não construída (ou seja, não é " +"uma :term:`Distribuição Construída`) e requer uma etapa de construção quando " +"instalada pelo pip. Mesmo se a distribuição for puro Python (ou seja, não " +"contém extensões), ainda envolve uma etapa de construção para construir os " +"metadados de instalação de :file:`setup.py` e/ou :file:`setup.cfg`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "Wheels" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" +"Você também deve criar uma wheel para o seu projeto. Uma wheel é " +"um :term:`pacote construído ` que pode ser " +"instalado sem a necessidade de passar pelo processo de \"construção\". " +"Instalar wheel é substancialmente mais rápido para o usuário final do que " +"instalar a partir de uma distribuição original." + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" +"Se o seu projeto for puro Python, você criará uma :ref:`\"Wheel de Python " +"Puro\" (consulte a seção abaixo) `." + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" +"Se o seu projeto contém extensões compiladas, então você criará o que é " +"chamado de :ref:`*Wheel de Plataforma* (veja a seção abaixo) `." + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" +"Se o seu projeto também tiver suporte a Python 2 *e* não contiver extensões " +"C, você deve criar o que é chamado de *Wheel Universal* adicionando o " +"seguinte ao seu arquivo :file:`setup.cfg`:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" +"Use esta configuração apenas se o seu projeto não tiver extensões C *e* " +"tiver suporte ao Python 2 e 3." + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "Wheels de Puro Python" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" +"*Wheels de Python Puro* contêm nenhuma extensão compilada e, portanto, só " +"exigem um único wheel Python." + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "Para construir o wheel:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" +"O pacote ``wheel`` detectará que o código é puro Python, e construirá um " +"wheel cujo nome pode ser usado em qualquer instalação do Python 3. Para " +"obter detalhes sobre a nomenclatura de arquivos wheel, consulte :pep:`425`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" +"Se você executar ``build`` sem ``--wheel`` ou ``--sdist``, ele irá construir " +"os dois arquivos para você; isso é útil quando você não precisa de vários " +"wheels." + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "Wheels de Plataforma" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" +"*Wheels de Plataforma* são wheels que são específicos para uma certa " +"plataforma, como Linux, macOS ou Windows, geralmente em razão de conter " +"extensões compiladas." + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" +"O pacote ``wheel`` detectará que o código não é puro Python e construirá um " +"wheel cujo nome só pode ser usado na plataforma em que foi construído. Para " +"obter detalhes sobre a nomenclatura de arquivos wheel, consulte :pep:`425`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" +":term:`PyPI ` oferece suporte atualmente a " +"envios de wheels de plataforma do Windows, macOS e da ABI multidistro " +"``manylinux*``. Detalhes sobre o último estão definidos em :pep:`513`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "Enviando seu Projeto para PyPI" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" +"Quando você executou o comando para criar sua distribuição, um novo " +"diretório ``dist/`` foi criado no diretório raiz do seu projeto. É onde você " +"encontrará seus arquivos de distribuição para enviar." + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" +"Esses arquivos são criados apenas quando você executa o comando para criar " +"sua distribuição. Isso significa que a qualquer momento que você alterar a " +"fonte do seu projeto ou a configuração no arquivo :file:`setup.py`, você " +"precisará reconstruir esses arquivos novamente antes de distribuir as " +"alterações para PyPI." + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" +"Antes de lançar no repositório principal do PyPI, você pode preferir treinar " +"com o `site de teste do PyPI `_ que é redefinido em " +"uma base semirregular. Veja :ref:`using-test-pypi` sobre como definir sua " +"configuração para usá-lo." + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" +"Em outros recursos, você pode encontrar referências ao uso de ``python " +"setup.py register`` e ``python setup.py upload``. Esses métodos de registro " +"e envio de um pacote são **fortemente desencorajados**, pois podem usar uma " +"conexão HTTP de texto simples ou HTTPS não verificada em algumas versões " +"Python, permitindo que seu nome de usuário e senha sejam interceptados " +"durante a transmissão." + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" +"O analisador de reStructuredText usado no PyPI **não é** Sphinx! Além disso, " +"para garantir a segurança de todos os usuários, certos tipos de URLs e " +"diretivas são proibidos ou removidos (por exemplo, a diretiva ``.. raw::``). " +"**Antes** de tentar enviar sua distribuição, você deve verificar se suas " +"descrições breves/longas fornecidas no :file:`setup.py` são válidas. Você " +"pode fazer isso executando :std:doc:`twine check ` em todos arquivos " +"do seu pacote:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "Criar uma conta" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" +"Primeiro, você precisa de uma conta de usuário do :term:`PyPI `. Você pode criar uma conta `usando o formulário no " +"site do PyPI `_." + +#: ../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 "" +"Agora você criará um `token de API`_ do PyPI para que possa enviar o seu " +"projeto com segurança." + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" +"Acesse https://pypi.org/manage/account/#api-tokens e crie um novo `token de " +"API`_; não limite seu escopo a um projeto específico, já que você está " +"criando um novo projeto." + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" +"**Não feche a página antes de copiar e salvar o token -- você não verá o " +"token novamente.**" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" +"Para evitar ter que copiar e colar o token toda vez que você enviar, você " +"pode criar um arquivo :file:`$HOME/.pypirc`:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +msgstr "**Esteja ciente de que isso armazena seu token em texto simples.**" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" +"Para mais detalhes, veja a :ref:`especificação ` do :file:`.pypirc`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "Enviar suas distribuições" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" +"Assim que tiver uma conta, você pode enviar suas distribuições para " +"o :term:`PyPI ` usando :ref:`twine`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" +"O processo de envio de uma versão é o mesmo, independentemente de o projeto " +"já existir ou não no PyPI -- se ainda não existir, será criado " +"automaticamente quando a primeira versão for carregada." + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" +"Para a segunda versão e as subsequentes, PyPI requer apenas que o número da " +"versão da nova versão seja diferente de todas as versões anteriores." + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" +"Você pode ver se o seu pacote foi enviado com sucesso navegando para a URL " +"``https://pypi.org/project/`` onde ``projetoexemplo`` é o " +"nome do seu projeto que você enviou. O seu projeto pode demorar um ou dois " +"minutos para aparecer no site." + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" +"Dependendo da sua plataforma, isso pode exigir acesso de root ou de " +"administrador. :ref:`pip` está atualmente considerando mudar isso `tornando " +"as instalações de usuário o comportamento padrão `_." + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "Descartando suporte para versões mais antigas do Python" + +#: ../source/guides/dropping-older-python-versions.rst:7 +#, fuzzy +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" +"O descarte de suporte para versões mais antigas do Python é suportado pela " +"especificação padrão :ref:`core-metadata` 1.2 através de um atributo " +"\"Requires-Python\"." + +#: ../source/guides/dropping-older-python-versions.rst:9 +#, fuzzy +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" +"Clientes com Metadata 1.2+, como Pip 9.0+, irão aderir a esta especificação " +"combinando o tempo de execução Python atual e comparando-o com a versão " +"necessária nos metadados do pacote. Se eles não corresponderem, ele tentará " +"instalar a última distribuição de pacote que oferece suporte a esse tempo de " +"execução do Python." + +#: ../source/guides/dropping-older-python-versions.rst:12 +#, fuzzy +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" +"Este mecanismo pode ser usado para descartar o suporte para versões mais " +"antigas do Python, alterando o atributo \"Requires-Python\" nos metadados do " +"pacote." + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "Requisitos" + +#: ../source/guides/dropping-older-python-versions.rst:17 +#, fuzzy +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" +"O usuário que instala o pacote tenha pelo menos Pip 9.0 ou um cliente que " +"tenha suporte à especificação Metadata 1.2." + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "Lidando com os wheels universais" + +#: ../source/guides/dropping-older-python-versions.rst:22 +#, fuzzy +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" +"Tradicionalmente, os projetos que fornecem código Python que é " +"semanticamente compatível com Python 2 e Python 3, produzem :term:`wheels " +"` que têm uma tag ``py2.py3`` em seus nomes. Ao descartar o suporte " +"para Python 2, é importante não se esquecer de alterar essa tag para apenas " +"``py3``. Isso geralmente é configurado em :file:`setup.cfg` na seção " +"``[bdist_wheel]`` definindo ``universal = 1`` se eles usam setuptools." + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" +"Se você usar este método, remova esta opção ou seção, ou defina " +"explicitamente ``universal`` como ``0``:" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "Definindo a versão Python exigida" + +#: ../source/guides/dropping-older-python-versions.rst:48 +#, fuzzy +msgid "1. Install twine" +msgstr "Instalação" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" +"2. Especifique os intervalos de versão para distribuições Python suportadas" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +#, fuzzy +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" +"Você pode especificar intervalos de versão e regras de exclusão, como pelo " +"menos Python 3. Ou Python 2.7, 3.4 e superior." + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "3. Validando o Metadata antes de publicar" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" +"Dentro de um pacote fonte Python (o arquivo zip ou tar-gz que você baixou) " +"está um arquivo de texto chamado PKG-INFO." + +#: ../source/guides/dropping-older-python-versions.rst:100 +#, fuzzy +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" +"Este arquivo é gerado pelo :ref:`distutils` ou :ref:`setuptools` quando ele " +"gera o pacote fonte. O arquivo contém um conjunto de chaves e valores, a " +"lista de chaves faz parte do formato de metadados padrão do PyPa." + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "Você pode ver o conteúdo do arquivo gerado assim:" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "Valide que o seguinte está no lugar, antes de publicar o pacote:" + +#: ../source/guides/dropping-older-python-versions.rst:111 +#, fuzzy +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" +"Se você atualizou corretamente, o valor de Metadata-Version deve ser 1.2 ou " +"superior." + +#: ../source/guides/dropping-older-python-versions.rst:112 +#, fuzzy +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" +"O campo Requires-Python está definido e corresponde a sua especificação no " +"setup.py." + +#: ../source/guides/dropping-older-python-versions.rst:115 +#, fuzzy +msgid "4. Publishing the package" +msgstr "Publicando lançamentos" + +#: ../source/guides/dropping-older-python-versions.rst:117 +#, fuzzy +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "Enviando seu Projeto para PyPI" + +#: ../source/guides/dropping-older-python-versions.rst:120 +#, fuzzy +msgid "Dropping a Python version" +msgstr "Descartando uma versão Python" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "Hospedando seu próprio repositório simples" + +#: ../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 "" +"Se você deseja hospedar seu próprio repositório simples [1]_, você pode usar " +"um pacote de software como :doc:`devpi ` ou você pode " +"simplesmente criar a estrutura de diretório apropriada e usar qualquer " +"servidor web que pode servir arquivos estáticos e gerar um autoindex." + +#: ../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:" +msgstr "" +"Em ambos os casos, como você hospedará um repositório que provavelmente não " +"está nos repositórios padrão do usuário, você deve instruí-los na descrição " +"do seu projeto para configurar o instalador apropriadamente. Por exemplo, " +"com 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." +msgstr "" +"Além disso, é **altamente** recomendado que você sirva seu repositório com " +"HTTPS válido. Neste momento, a segurança das instalações do seu usuário " +"depende de todos os repositórios usando uma configuração válida do HTTPS." + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "Repositório \"manual\"" + +#: ../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 "" +"O layout do diretório é bastante simples, dentro de um diretório raiz você " +"precisa criar um diretório para cada projeto. Este diretório deve ser " +"o :ref:`nome normalizado ` do projeto. Em cada um desses " +"diretórios, basta colocar cada um dos arquivos para download. Se você tem os " +"projetos \"Foo\" (com as versões 1.0 e 2.0) e \"bar\" (com a versão 0.1), " +"você deve acabar com uma estrutura parecida com::" + +#: ../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 "" +"Assim que tiver esse layout, basta configurar seu servidor web para servir o " +"diretório raiz com o autoindex habilitado. Para um exemplo usando o servidor " +"Web embutido em `Twisted`_, você simplesmente executaria ``twistd -n web --" +"path .`` e então instruiria os usuários a adicionar a URL à configuração de " +"seu instalador." + +#: ../source/guides/hosting-your-own-index.rst:57 +#: ../source/guides/index-mirrors-and-caches.rst:47 +msgid "Existing projects" +msgstr "Projetos existentes" + +#: ../source/guides/hosting-your-own-index.rst:63 +msgid "Package upload" +msgstr "Envio de pacotes" + +#: ../source/guides/hosting-your-own-index.rst:64 +msgid "PyPI fall-through [2]_" +msgstr "Padrão do 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 "Notas adicionais" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" +"múltiplos índices com herança, com sincronização, replicação, tolerância a " +"falhas; espelhamento" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr ":ref:`simpleindex`" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr ":ref:`pypiserver`" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr ":ref:`pypiprivate`" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr ":ref:`pypicloud`" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "sem manutenção; também faz proxy de cache; autenticação, autorização" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr ":ref:`pywharf`" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "sem manutenção; serve arquivos no GitHub" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr ":ref:`pulppython`" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "também espelhamento, proxy; plugin para Pulp" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr ":ref:`pip2pi`" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "também espelhamento; sincronização manual" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr ":ref:`dumb-pypi`" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "não é um servidor, mas um gerador de site de arquivo estático" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr ":ref:`httpserver`" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "biblioteca padrão" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "`Apache `_" + +#: ../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 "" +"usando `mod_rewrite `_ e " +"`mod_cache_disk `_, você pode armazenar em cache as solicitações para " +"índices de pacotes por meio de um servidor Apache" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" +"Para a documentação completa do protocolo de repositório simples, " +"veja :ref:`API de repositório simples `.." + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" +"Pode ser configurado para recorrer ao PyPI (ou outro índice de pacote) se um " +"pacote solicitado estiver ausente." + +#: ../source/guides/index.rst:4 +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`." +msgstr "" +"**Guias** se concentram em realizar uma tarefa específica e presumem que " +"você já esteja familiarizado com os fundamentos do empacotamento do Python. " +"Se você está procurando uma introdução ao empacotamento, veja :doc:`/" +"tutorials/index`." + +#: ../source/guides/index-mirrors-and-caches.rst:5 +msgid "Package index mirrors and caches" +msgstr "Espelhos e caches de índice de pacotes" + +#: ../source/guides/index-mirrors-and-caches.rst:8 +msgid "2023-11-08" +msgstr "2023-11-08" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" +"O espelhamento ou cache do PyPI (e outros :term:`índices de pacotes <Índice " +"de Pacotes>`) pode ser usado para acelerar a instalação do pacote local, " +"permitir o trabalho offline, lidar com firewalls corporativos ou " +"simplesmente falhas na Internet." + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "Existem várias classes de opções nesta área:" + +#: ../source/guides/index-mirrors-and-caches.rst:17 +msgid "local/hosted caching of package indexes." +msgstr "fazer cache local/hospedado de índices de pacotes." + +#: ../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 "" +"fazer espelhamento local/hospedado de um índice de pacotes. Um espelho é uma " +"cópia (total ou parcial) de um índice de pacotes, que pode ser usado no " +"lugar do índice original." + +#: ../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 "" +"índice de pacotes privados com alternativa para os índices de pacotes " +"públicos (por exemplo, para mitigar ataques de confusão de dependência), " +"também conhecido como proxy." + +#: ../source/guides/index-mirrors-and-caches.rst:29 +msgid "Caching with pip" +msgstr "Fazendo cache com pip" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" +"pip fornece uma série de facilidades para acelerar a instalação usando " +"cópias locais em cache de :term:`pacotes `:" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" +":ref:`Instalações rápidas e locais ` " +"baixando todos os requisitos para um projeto e apontando pip para esses " +"arquivos baixados em vez de ir para PyPI." + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" +"Uma variação da acima, que pré-constrói os arquivos de instalação para os " +"requisitos usando :ref:`python3 -m pip wheel `:" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "Cache" + +#: ../source/guides/index-mirrors-and-caches.rst:54 +msgid "Mirror" +msgstr "Espelho" + +#: ../source/guides/index-mirrors-and-caches.rst:55 +msgid "Proxy" +msgstr "Proxy" + +#: ../source/guides/index-mirrors-and-caches.rst:62 +msgid "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" +"múltiplos índices com herança; sincronização, replicação, tolerância a " +"falhas; envio de pacote" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr ":ref:`bandersnatch`" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" +"plugin personalizado permite fazer cache; redirecionamento para outros " +"índices de pacotes" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "sem manutenção; autenticação, autorização" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "plugin para Pulp; vários índices proxy; envio de pacote" + +#: ../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 "múltiplos índices sob proxy" + +#: ../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 "sem manutenção" + +#: ../source/guides/installing-scientific-packages.rst:5 +msgid "Installing scientific packages" +msgstr "Instalando pacotes científicos" + +#: ../source/guides/installing-scientific-packages.rst:8 +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." +msgstr "" +"O software científico tende a ter dependências mais complexas do que a " +"maioria e, frequentemente, terá várias opções de construção para tirar " +"proveito de diferentes tipos de hardware ou para interoperar com diferentes " +"partes de software externo." + +#: ../source/guides/installing-scientific-packages.rst:13 +#, fuzzy +#| 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." +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 vectorized " +"instructions available in modern CPUs." +msgstr "" +"Em particular, `NumPy `__, que fornece a base para a " +"maioria do software na `pilha científica Python `_ pode ser configurado para interoperar com diferentes " +"bibliotecas FORTRAN e pode tirar proveito de diferentes níveis de instruções " +"vetorizadas disponíveis em CPUs modernas." + +#: ../source/guides/installing-scientific-packages.rst:19 +#, fuzzy +#| 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." +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." +msgstr "" +"A partir da versão 1.10.4 do NumPy e da versão 1.0.0 do SciPy, binários pré-" +"construídos de 32 e 64 bits no formato ``wheel`` estão disponíveis para " +"todos os principais sistemas operacionais (Windows, macOS e Linux) em PyPI. " +"Observe, no entanto, que no Windows, os binários do NumPy são vinculados à " +"biblioteca BLAS/LAPACK do `ATLAS `__, restrita " +"às instruções SSE2, portanto, podem não fornecer desempenho da álgebra " +"linear." + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" +"Existem várias opções alternativas para obter bibliotecas científicas Python " +"(ou quaisquer outras bibliotecas Python que requerem um ambiente de " +"compilação para instalar a partir do código-fonte e não fornecem arquivos de " +"wheel pré-construídos no PyPI)." + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "Construindo a partir do código-fonte" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" +"A mesma complexidade que torna difícil distribuir o NumPy (e muitos dos " +"projetos que dependem dele) como arquivos wheel também torna difícil " +"construí-los a partir do código-fonte. No entanto, para pessoas intrépidas " +"que estão dispostas a gastar o tempo discutindo compiladores e vinculadores " +"para C e FORTRAN, construir a partir do código-fonte é sempre uma opção." + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +msgstr "Pacotes de distribuição Linux" + +#: ../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 "" +"Para usuários Linux, o gerenciador de pacotes do sistema frequentemente terá " +"versões pré-compiladas de várias peças de software científico, incluindo " +"NumPy e outras partes da pilha científica Python." + +#: ../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 "" +"Se usar versões que podem ter vários meses é aceitável, então esta é " +"provavelmente uma boa opção (apenas certifique-se de permitir o acesso às " +"distribuições instaladas no sistema Python ao usar ambientes virtuais)." + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "Instaladores para Windows" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" +"Muitos projetos Python que não publicam (ou não podem) atualmente publicar " +"arquivos wheel, pelo menos publicam instaladores Windows, seja no PyPI ou na " +"página de download de seus projetos. O uso desses instaladores permite que " +"os usuários evitem a necessidade de configurar um ambiente adequado para " +"construir extensões localmente." + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" +"As extensões fornecidas nesses instaladores são normalmente compatíveis com " +"os instaladores do CPython para o Windows publicados em python.org." + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" +"Tal como acontece com os pacotes de sistema Linux, os instaladores Windows " +"irão apenas instalar em uma instalação de sistema Python -- eles não " +"oferecem suporte à instalação em ambientes virtuais. Permitir o acesso a " +"distribuições instaladas no sistema Python ao usar ambientes virtuais é uma " +"abordagem comum para contornar essa limitação." + +#: ../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 "" +"O projeto :term:`Wheel` também fornece um subcomando :command:`wheel " +"convert` que pode converter um instalador para " +"Windows :command:`bdist_wininst` em um wheel." + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +msgstr "Instaladores e gerenciadores de pacote para macOS" + +#: ../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 "" +"Semelhante à situação no Windows, muitos projetos (incluindo NumPy) publicam " +"instaladores para macOS que são compatíveis com os binários do CPython para " +"macOS publicados em python.org." + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" +"Os usuários do macOS também têm acesso aos gerenciadores de pacotes de " +"estilo de distribuição Linux, como ``Homebrew``. O site SciPy tem mais " +"detalhes sobre como usar Homebrew para `instalar SciPy no macOS `_." + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "Distribuições SciPy" + +#: ../source/guides/installing-scientific-packages.rst:91 +#, fuzzy +#| msgid "" +#| "The SciPy site lists `several distributions `_ that provide the full SciPy stack to end users in an " +#| "easy to use and update format." +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" +"O site SciPy lista `várias distribuições `_ que fornecem a pilha SciPy completa para usuários finais " +"em um formato fácil de usar e atualizar." + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" +"Algumas dessas distribuições podem não ser compatíveis com o conjunto de " +"ferramentas padrão ``pip`` e ``virtualenv``." + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "Spack" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" +"`Spack `_ é um gerenciador de pacotes " +"flexível projetado para oferecer suporte a múltiplas versões, configurações, " +"plataformas e compiladores. Ele foi construído para dar suporte às " +"necessidades de grandes centros de supercomputação e equipes de aplicações " +"científicas, que frequentemente precisam criar software de muitas maneiras " +"diferentes. O Spack não está limitado a Python; ele pode instalar pacotes " +"para ``C``, ``C++``, ``Fortran``, ``R`` e outras linguagens. É não " +"destrutivo; instalar uma nova versão de um pacote não interrompe as " +"instalações existentes, portanto, muitas configurações podem coexistir no " +"mesmo sistema." + +#: ../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 "" +"O Spack oferece uma sintaxe simples, mas poderosa, que permite aos usuários " +"especificar versões e opções de configuração de forma concisa. Os arquivos " +"de pacote são escritos em puro Python e são modelados para que seja fácil " +"trocar compiladores, implementações de dependência (como MPI), versões e " +"opções de construção com um único arquivo de pacote. O Spack também gera " +"arquivos de *módulo* para que os pacotes possam ser carregados e " +"descarregados do ambiente do usuário." + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "O gerenciador de pacotes multiplataforma conda" + +#: ../source/guides/installing-scientific-packages.rst:121 +#, fuzzy +#| 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)." +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" +"``conda`` é um sistema de gerenciamento de pacotes e de gerenciamento de " +"ambiente de código aberto (licenciado por BSD) incluído no Anaconda que " +"permite aos usuários instalar várias versões de pacotes de software binários " +"e suas dependências, e alternar facilmente entre eles. É uma ferramenta " +"multiplataforma que funciona no Windows, no macOS e no Linux. O Conda pode " +"ser usado para empacotar e distribuir todos os tipos de pacotes, não está " +"limitado apenas a pacotes Python. Possui suporte total para ambientes " +"virtuais nativos. Conda torna os ambientes cidadãos de primeira classe, " +"facilitando a criação de ambientes independentes até mesmo para bibliotecas " +"C. Está escrito em Python, mas é agnóstico ao Python. O Conda gerencia o " +"próprio Python como um pacote, de forma que :command:`conda update python` " +"seja possível, em contraste com o pip, que gerencia apenas os pacotes " +"Python. O Conda está disponível no Anaconda e no Miniconda (um download " +"fácil de instalar com apenas Python e conda)." + +#: ../source/guides/installing-scientific-packages.rst:133 +#, fuzzy +#| 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." +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" +"`Anaconda `_ é uma " +"distribuição Python publicada pela Anaconda, Inc. É uma coleção estável de " +"pacotes de código aberto para *big data* e uso científico. A partir da " +"versão 5.0 do Anaconda, cerca de 200 pacotes são instalados por padrão, e um " +"total de 400-500 podem ser instalados e atualizados a partir do repositório " +"Anaconda." + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "Instalando ferramentas de linha de comando autônomas" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" +"Muitos pacotes fornecem aplicações de linha de comando. Exemplos deste tipo " +"de aplicação são `mypy `_, `flake8 `_, `black `_ " +"e :ref:`pipenv`." + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" +"Normalmente você deseja acessar essas aplicações de qualquer lugar no " +"sistema, mas instalar pacotes e suas dependências no mesmo ambiente global " +"pode causar conflitos de versão e quebrar as dependências que o sistema " +"operacional tem nos pacotes Python." + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" +":ref:`pipx` resolve isso criando um ambiente virtual para cada pacote, " +"enquanto também garante que suas aplicações sejam acessíveis através de um " +"diretório que está em seu ``$PATH``. Isso permite que cada pacote seja " +"atualizado ou desinstalado sem causar conflitos com outros pacotes e permite " +"que você execute a aplicações com segurança de qualquer lugar." + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "pipx só funciona com Python 3.6+." + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "pipx é instalado com pip:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" +"``ensurepath`` garante que o diretório de aplicação está em seu ``$PATH``. " +"Você pode precisar reiniciar seu terminal para que as atualizações de " +"caminho tenham efeito." + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" +"Agora você pode instalar pacotes com ``pipx install`` e executar as " +"aplicações do pacote de qualquer lugar." + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "Por exemplo:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" +"Para ver uma lista de pacotes instalados com pipx e quais aplicações estão " +"disponíveis, use ``pipx list``:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "Para atualizar ou desinstalar um pacote:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "pipx pode ser atualizado ou desinstalado com pip:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" +"pipx também permite que você instale e execute a versão mais recente de uma " +"aplicação em um ambiente temporário e efêmero. Por exemplo:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "Para ver a lista completa de comandos pipx oferece, execute:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "Você pode aprender mais sobre pipx em https://pipx.pypa.io/." + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "Instalando pip/setuptools/wheel com gerenciadores de pacotes do Linux" + +#: ../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 section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" +"Esta seção cobre como instalar :ref:`pip`, :ref:`setuptools` e :ref:`wheel` " +"usando gerenciadores de pacotes do Linux." + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" +"Se você estiver usando um Python que foi baixado de `python.org `_, então esta seção não se aplica. Veja a " +"seção :ref:`installing_requirements`." + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +msgstr "" +"Observe que é comum que as versões de :ref:`pip`, :ref:`setuptools` " +"e :ref:`wheel` suportadas por uma distribuição Linux específica estejam " +"desatualizadas no momento em que é lançado para o público, e as atualizações " +"geralmente ocorrem apenas por motivos de segurança, não para atualizações de " +"recursos. Para certas distribuições, existem repositórios adicionais que " +"podem ser ativados para fornecer versões mais recentes. Os repositórios que " +"conhecemos são explicados abaixo." + +#: ../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 "" +"Observe também que é um tanto comum que as Distribuições apliquem patches " +"para fins de segurança e normalização de acordo com seus próprios padrões. " +"Em alguns casos, isso pode levar a bugs ou comportamentos inesperados que " +"variam em relação às versões originais sem patch. Quando isso for conhecido, " +"faremos anotações sobre isso a seguir." + +#: ../source/guides/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "Fedora" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" +"Para saber mais sobre Python no Fedora, visite os `documentos oficiais do " +"Fedora`_, `Python Classroom`_ ou `Fedora Loves Python`_." + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "CentOS/RHEL" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" +"CentOS e RHEL não oferecem :ref:`pip` ou :ref:`wheel` em seus repositórios " +"principais, embora :ref:`setuptools` seja instalado por padrão." + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "Para instalar pip e wheel para o sistema Python, existem duas opções:" + +#: ../source/guides/installing-using-linux-tools.rst:52 +#, fuzzy +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" +"Habilite o `repositório EPEL `_ usando " +"`estas instruções `__ . No EPEL 7, você pode instalar pip " +"assim:" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" +"Como a EPEL oferece apenas pacotes extras não conflitantes, a EPEL não " +"oferece setuptools, pois está no repositório central." + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" +"Habilite o `Copr Repo do PyPA `_ usando `estas instruções `__ [1]_. Você pode instalar pip e " +"wheel desta forma:" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "Para adicionalmente atualizar setuptools, execute:" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" +"Para instalar pip, wheel e setuptools, em um ambiente paralelo, sem sistema " +"(usando yum), existem duas opções:" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" +"Use o recurso \"Coleções de software\" para habilitar uma coleção paralela " +"que inclui pip, setuptools e wheel." + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" +"Para Redhat, veja aqui: https://developers.redhat.com/products/" +"softwarecollections/overview" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "Para CentOS, veja aqui: 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 "" +"Esteja ciente de que as coleções podem não conter as versões mais recentes." + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" +"Habilite o `repositório do IUS `_ e instale um dos " +"Pythons `pré-instaláveis `_, junto com pip, setuptools e wheel, que são mantidos " +"razoavelmente atualizados." + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "Por exemplo, para Python 3.4 no CentOS7/RHEL7:" + +#: ../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 e derivados" + +#: ../source/guides/installing-using-linux-tools.rst:120 +msgid "Firstly, update and refresh repository lists by running this command:" +msgstr "" +"Em primeiro lugar, atualize as listas de repositórios executando este " +"comando:" + +#: ../source/guides/installing-using-linux-tools.rst:129 +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." +msgstr "" +"Versões recentes do Debian/Ubuntu modificaram o pip para usar o `\"User " +"Scheme\" `_ " +"(Esquema de usuário) por padrão, que é um mudança significativa de " +"comportamento que pode surpreender alguns usuários." + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "Arch Linux" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" +"Atualmente, não há plug-in do yum para \"copr\" disponível para CentOS/RHEL, " +"então a única opção é colocar manualmente os arquivos de repositório " +"conforme descrito." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +msgid "Install packages in a virtual environment using pip and venv" +msgstr "Instalar pacotes em um ambiente virtual usando pip e venv" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" +"Este guia discute como criar e ativar um ambiente virtual usando a " +"ferramenta de ambiente virtual da biblioteca padrão :ref:`venv` e instalar " +"pacotes. O guia aborda como:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:8 +msgid "Create and activate a virtual environment" +msgstr "Criar e ativar um ambiente virtual" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:9 +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:153 +msgid "Prepare pip" +msgstr "Preparar o pip" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "Instalar pacotes em um ambinente virtual usando o comando ``pip``" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "Usar e criar o arquivo de requisitos" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" +"Este guia se aplica a versões suportadas do Python, atualmente 3.8 e " +"superior." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" +"Este guia usa o termo **pacote** para se referir a um :term:`Pacote de " +"Distribuição`, o qual é comumente instalado a partir de um host externo. Ele " +"é diferente do termo :term:`Pacote de Importação` que se refere a importar " +"módulos em seu código-fonte do Python." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +msgid "" +"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 "" +"Este guia tem como pré-requisito que você esteja usando uma versão oficial " +"do Python obtida em . Se você estiver " +"usando o gerenciador de pacotes do seu sistema operacional para instalar o " +"Python, certifique-se de que o Python esteja instalado antes de prosseguir " +"com estas etapas." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:32 +msgid "Create and Use Virtual Environments" +msgstr "Criar e usar ambientes virtuais" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:35 +msgid "Create a new virtual environment" +msgstr "Criar um novo ambiente virtual" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:37 +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." +msgstr "" +":ref:`venv` (para Python 3) permite gerenciar instalações de pacotes " +"separadas para projetos diferentes. Ele cria uma instalação Python " +"\"virtual\" e isolada. Ao alternar projetos, você pode criar um novo " +"ambiente virtual isolado de outros ambientes virtuais. Você se beneficia do " +"ambiente virtual, pois os pacotes podem ser instalados com segurança e não " +"interferirão no ambiente de outro projeto." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:45 +msgid "" +"It is recommended to use a virtual environment when working with third party " +"packages." +msgstr "" +"Recomenda-se usar um ambiente virtual ao trabalhar com pacotes de terceiros." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" +"Para criar um ambiente virtual, acesse o diretório do seu projeto e execute " +"o comando a seguir. Isso criará um novo ambiente virtual em uma pasta local " +"chamada ``.venv``:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" +"O segundo argumento é o local para criar o ambiente virtual. Geralmente, " +"você pode apenas criar isso em seu projeto e chamá-lo de ``.venv``." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "``venv`` irá criar uma instalação virtual Python na pasta ``.venv``." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" +"Você deve excluir seu diretório de ambiente virtual de seu sistema de " +"controle de versão usando ``.gitignore`` ou similar." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "Ativar um ambiente virtual" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" +"Antes de começar a instalar ou usar pacotes em seu ambiente virtual, você " +"precisará ativá-lo, com ``activate``. Ativar um ambiente virtual colocará os " +"executáveis ``python`` e ``pip`` específicos do ambiente virtual no ``PATH`` " +"de seu shell." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" +"Para confirmar o ambiente virtual está ativado, verifique o local do seu " +"interpretador Python:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" +"Enquanto o ambiente virtual estiver ativo, o comando acima irá gerar um " +"caminho de arquivo que inclui o diretório ``.venv``, terminando com o " +"seguinte:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" +"Enquanto um ambiente virtual estiver ativado, pip instalará pacotes naquele " +"ambiente específico. Isso permite que você importe e use pacotes em sua " +"aplicação Python." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "Desativar um ambiente virtual" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" +"Se você deseja trocar de projeto ou sair do seu ambiente virtual, desative o " +"ambiente com ``deactivate``:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" +"Fechar seu shell desativará o ambiente virtual. Se você abrir uma nova " +"janela do shell e quiser usar o ambiente virtual, reative-o." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "Reativar um ambiente virtual" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" +"Se você quiser reativar um ambiente virtual existente, siga as mesmas " +"instruções sobre como ativar um ambiente virtual. Não há necessidade de " +"criar um novo ambiente virtual." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" +":ref:`pip` é o gerenciador de pacotes de referência Python. É usado para " +"instalar e atualizar pacotes. Ele é usado para instalar e atualizar pacotes " +"em um ambiente virtual." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" +"Os instaladores de Python para macOS incluem pip. No Linux, você pode ter " +"que instalar um pacote adicional como ``python3-pip``. Você pode ter certeza " +"de que o pip está atualizado executando:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" +"Depois disso, você deve ter a versão mais recente do pip instalado em seu " +"site de usuário:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" +"Os instaladores do Python para Windows incluem pip. Você pode garantir que o " +"pip está atualizado usando:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "Depois disso, você deve ter a versão mais recente do pip:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +msgid "Install packages using pip" +msgstr "Instalar pacotes usando pip" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" +"Quando seu ambiente virtual estiver ativado, você poderá instalar pacotes. " +"Use o comando ``pip install`` para instalar pacotes." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "Instalar um pacote" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +#, fuzzy +#| msgid "" +#| "For example,let's install the `Requests`_ library from the :term:`Python " +#| "Package Index (PyPI)`:" +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" +"Por exemplo, vamos instalar a biblioteca `Requests`_ do :term:`Python " +"Package Index (PyPI)`:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" +"pip deve baixar solicitações e todas as suas dependências e instalá-los:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "Instalar uma versão específica do pacote" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" +"pip permite que você especifique qual versão de um pacote instalar " +"usando :term:`especificadores de versão `. Por " +"exemplo, para instalar uma versão específica do ``requests``:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "Para instalar a versão ``2.x`` mais recente do requests:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" +"Para instalar versões de pré-lançamento de pacotes, use o sinalizador ``--" +"pre``:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +msgid "Install extras" +msgstr "Instalar extras" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" +"Alguns pacotes possuem `extras`_ opcionais. Você pode dizer ao pip para " +"instalá-los especificando o extra entre colchetes:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "Instalar um pacote a partir do código-fonte" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" +"pip pode instalar um pacote diretamente de seu código-fonteseu. Por exemplo, " +"você pode instalar o código-fonte no diretório ``google-auth``:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" +"Além disso, pip pode instalar pacotes do código-fonte no :doc:`modo de " +"desenvolvimento `, o que significa " +"que as mudanças no diretório de código-fonte afetarão imediatamente o pacote " +"instalado sem a necessidade de reinstalar:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:347 +msgid "Install from version control systems" +msgstr "Instalar a partir de sistemas de controle de versão" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:349 +msgid "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" +"pip pode instalar pacotes diretamente de seu sistema de controle de versão. " +"Por exemplo, você pode instalar diretamente de um repositório git:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" +"Para mais informações sobre os sistemas de controle de versão suportados e " +"sintaxe, consulte a documentação do pip em :ref:`Suporte VCS `." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "Instalar a partir de arquivos locais" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" +"Se você tiver uma cópia local de um arquivo do :term:`Pacote de " +"Distribuição` (um arquivo zip, wheel ou tar), você pode instalá-lo " +"diretamente com pip:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" +"Se você tiver um diretório contendo arquivos de vários pacotes, você pode " +"dizer ao pip para procurar por pacotes lá e não usar o :term:`Python Package " +"Index (PyPI)` de forma alguma:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" +"Isso é útil se você estiver instalando pacotes em um sistema com " +"conectividade limitada ou se quiser controlar estritamente a origem dos " +"pacotes de distribuição." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "Instalar a partir de outros índices de pacote" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" +"Se você quiser baixar pacotes de um índice diferente do :term:`Python " +"Package Index (PyPI)`, você pode usar o sinalizador ``--index-url``:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" +"Se você deseja permitir pacotes do :term:`Python Package Index (PyPI)` e de " +"um índice separado, você pode usar a sinalização ``--extra-index-url`` em " +"seu lugar:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "Atualizando pacotes" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" +"pip pode atualizar pacotes no local usando o sinalizador ``--upgrade``. Por " +"exemplo, para instalar a versão mais recente de ``requests`` e todas as suas " +"dependências:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "Usando um arquivo de requisitos" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" +"Em vez de instalar pacotes individualmente, pip permite que você declare " +"todas as dependências em um :ref:`Arquivo de Requisitos `. Por exemplo, você pode criar um arquivo :file:`requirements.txt` " +"contendo:" + +#: ../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 "" +"E diga ao pip para instalar todos os pacotes neste arquivo usando o " +"sinalizador ``-r``:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +msgstr "Congelando dependências" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:480 +msgid "" +"Pip can export a list of all installed packages and their versions using the " +"``freeze`` command:" +msgstr "" +"Pip pode exportar uma lista de todos os pacotes instalados e suas versões " +"usando o comando ``freeze``:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 +msgid "Which will output a list of package specifiers such as:" +msgstr "O que resultará em uma lista de especificadores de pacote, como:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" +"O comando ``pip freeze`` útil para criar :ref:`pip:Requirements Files` que " +"podem recriar as versões exatas de todos os pacotes instalados em um " +"ambiente." + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "Instalando pacotes usando virtualenv" + +#: ../source/guides/installing-using-virtualenv.rst:4 +msgid "" +"This guide discusses how to install packages using :ref:`pip` " +"and :ref:`virtualenv`, a tool to create isolated Python environments." +msgstr "" +"Este guia discute como instalar pacotes usando :ref:`pip` " +"e :ref:`virtualenv`, uma ferramenta para criar ambientes Python isolados." + +#: ../source/guides/installing-using-virtualenv.rst:8 +msgid "" +"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 "" +"Este guia sobre como instalar pacotes e usar :ref:`virtualenv` está em " +"desenvolvimento. Consulte a documentação do :ref:`virtualenv` para detalhes " +"sobre instalação e uso." + +#: ../source/guides/installing-using-virtualenv.rst:13 +msgid "" +"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 "" +"Este documento usa o termo **pacote** para se referir a um :term:`Pacote de " +"Distribuição` que é diferente de um :term:`Pacote de Importação` que é usado " +"para importar módulos em seu código-fonte do Python." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +#, fuzzy +#| msgid "Examples" +msgid "Licensing Examples" +msgstr "Exemplos" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +#, fuzzy +msgid "Basic example" +msgstr "Um exemplo completo" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +#, fuzzy +msgid "Advanced example" +msgstr "Um exemplo completo" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +#, fuzzy +#| msgid "in favour of ``Requires-Dist``" +msgid "The appropriate license expressions are:" +msgstr "em favor de ``Requires-Dist``" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +#, fuzzy +msgid "Expression examples" +msgstr "Um exemplo completo" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +#, fuzzy +#| msgid "in favour of ``Requires-Dist``" +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "em favor de ``Requires-Dist``" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "Criando um README amigável para PyPI" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" +"Os arquivos README podem ajudar seus usuários a entender o seu projeto e " +"podem ser usados para definir a descrição do seu projeto no PyPI. Este guia " +"ajuda a criar um README em um formato amigável ao PyPI e inclui seu README " +"em seu pacote para que apareça no PyPI." + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "Criando um arquivo README" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" +"Arquivos README para projetos Python são frequentemente chamados de " +"``README``, ``README.txt``, ``README.rst`` ou ``README.md``." + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" +"Para que seu README seja exibido corretamente no PyPI, escolha uma linguagem " +"de marcação suportada pelo PyPI. Os formatos suportados pelo renderizador de " +"README do `PyPI `_ são:" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "texto simples" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" +"`reStructuredText `_ (sem " +"extensões do Sphinx)" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" +"Markdown (`GitHub Flavored Markdown `_ por " +"padrão ou `CommonMark `_)" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" +"É comum salvar seu arquivo README na raiz de seu projeto, no mesmo diretório " +"que seu arquivo :file:`setup.py`." + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "Incluindo seu README nos metadados do seu pacote" + +#: ../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 "" +"Para incluir o conteúdo do README como a descrição do pacote, defina os " +"metadados ``Description`` e ``Description-Content-Type`` do seu projeto, " +"normalmente no arquivo :file:`setup.py` do seu projeto." + +#: ../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/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" +"Por exemplo, para definir esses valores em um arquivo :file:`setup.py` do " +"pacote, use ``long_description`` e ``long_description_content_type`` do " +"``setup()``." + +#: ../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``." +msgstr "" +"Defina o valor de ``long_description`` para o conteúdo (não o caminho) do " +"próprio arquivo README. Defina o ``long_description_content_type`` para um " +"valor aceito no estilo ``Content-Type`` para a marcação do seu arquivo " +"README, como ``text/plain``, ``text/t-rst`` (para reStructuredText) ou " +"``text/markdown``." + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" +"Se você estiver usando o Markdown do GitHub para escrever a descrição de um " +"projeto, certifique-se de atualizar as seguintes ferramentas:" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "As versões mínimas exigidas das respectivas ferramentas são:" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" +"É recomendado que você use ``twine`` para enviar pacotes de distribuição do " +"projeto:" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" +"Por exemplo, veja este arquivo :file:`setup.py`, que lê o conteúdo " +"de :file:`README.md` como ``long_description`` e identifica a marcação como " +"Markdown do GitHub:" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "Validando a marcação reStructuredText" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" +"Se o seu README for escrito em reStructuredText, qualquer marcação inválida " +"irá impedi-lo de renderizar, fazendo com que o PyPI mostre apenas o código-" +"fonte não tratado do README." + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" +"Observe que as extensões Sphinx usadas em docstrings, como :doc:`diretivas " +"` e :doc:`funções ` (por exemplo, \"``:py:func:`getattr```\" ou " +"\"``:ref:`my-reference-label```\"), não são permitidas aqui e resultarão em " +"mensagens de erro como \"``Error: Unknown interpreted text role " +"\"py:func\".``\"." + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" +"Você pode verificar se há erros de marcação em seu README antes de enviar:" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +msgstr "" +"Instale a versão mais recente do `twine `_; " +"versão 1.12.0 ou superior é necessária:" + +#: ../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 "" +"Construa o sdist e o wheel para seu projeto conforme descrito " +"em :ref:`Empacotando seu projeto `." + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "Execute ``twine check`` no sdist e wheel:" + +#: ../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 "" +"Este comando relatará quaisquer problemas ao processar seu README. Se sua " +"marcação renderizar corretamente, o comando produzirá ``Checking " +"Distribution FILENAME: Passed``." + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "Migrando para 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 "Obsoleto" + +#: ../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` é a nova versão reescrita do PyPI que substituiu a base de " +"código legada do PyPI. É a versão padrão do PyPI que se espera que as " +"pessoas usem. Estas são as ferramentas e processos que as pessoas precisarão " +"para interagir com o ``PyPI .org``." + +#: ../source/guides/migrating-to-pypi-org.rst:16 +msgid "Publishing releases" +msgstr "Publicando lançamentos" + +#: ../source/guides/migrating-to-pypi-org.rst:18 +msgid "``pypi.org`` is the default upload platform as of September 2016." +msgstr "``pypi.org`` é a plataforma padrão para envio em setembro de 2016." + +#: ../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 "" +"Os envios por meio de ``pypi.python.org`` foram *desativados* em **3 de " +"julho de 2017**. Desde 13 de abril de 2018, ``pypi.org`` é a URL do PyPI." + +#: ../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 "" +"A maneira recomendada de migrar para PyPI.org para enviar é garantir que " +"você esteja usando uma versão nova o suficiente de sua ferramenta de envio." + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" +"As configurações de envio padrão mudaram para ``pypi.org`` nas seguintes " +"versões:" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "``setuptools`` 27.0.0" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "Python 2.7.13 (atualização de ``distutils``)" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "Python 3.4.6 (atualização de ``distutils``)" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "Python 3.5.3 (atualização de ``distutils``)" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "Python 3.6.0 (atualização de ``distutils``)" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" +"Além de garantir que você esteja em uma versão nova o suficiente da " +"ferramenta para que o padrão da ferramenta seja alterado, você também deve " +"se certificar de que não configurou a ferramenta para substituir sua URL de " +"envio padrão. Normalmente, isso é configurado em um arquivo localizado " +"em :file:`$HOME/.pypirc`. Se você vir um arquivo como:" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" +"Em seguida, simplesmente exclua a linha começando com ``repository`` e você " +"usará a URL padrão da sua ferramenta de envio." + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +msgstr "" +"Se por algum motivo você não puder atualizar a versão de sua ferramenta para " +"uma versão que usa o padrão PyPI.org, então você pode " +"editar :file:`$HOME/.pypirc` e incluir a linha ``repository:``, mas use o " +"valor ``https://upload.pypi.org/legacy/`` em vez disso:" + +#: ../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 "" +"(``legacy`` nesta URL refere-se ao fato de que esta é a emulação da " +"implementação do novo servidor para a API de envio da implementação do " +"servidor legado.)" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "Registrando nomes pacotes e metadados" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" +"O pré-registro explícito de nomes de pacotes com o comando ``setup.py " +"register`` antes do primeiro envio não é mais necessário e não é mais " +"suportado pela emulação de API de envio legado no PyPI.org." + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" +"Como resultado, a tentativa de registro explícito após alternar para o uso " +"de PyPI.org para envios gerará a seguinte mensagem de erro::" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" +"A solução é pular a etapa de registro e prosseguir diretamente para o envio " +"dos artefatos." + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "Usando TestPyPI" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" +"O TestPyPI legado (testpypi.python.org) não está mais disponível; use " +"`test.pypi.org `_ em vez disso. Se você usar o " +"TestPyPI, você deve atualizar seu :file:`$HOME/.pypirc` para lidar com o " +"novo local do TestPyPI, substituindo ``https://testpypi.python.org/pypi`` " +"por ``https://test.pypi.org/legacy/``, por exemplo:" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "Registrando novas contas de usuário" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" +"A fim de ajudar a mitigar ataques de spam contra PyPI, o registro de novo " +"usuário por meio de ``pypi.python.org`` foi *desativado* em **20 de " +"fevereiro de 2018**. Novos registros de usuários em ``pypi.org`` estão " +"abertos." + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "Navegando pelos pacotes" + +#: ../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." +msgstr "" +"Embora ``pypi.python.org`` ainda possa ser usado em links de outras " +"documentações do PyPA, etc, a interface padrão para navegar pelos pacotes é " +"``pypi.org``. O domínio pypi.python.org agora redireciona para pypi.org e " +"pode ser desativado em algum momento no futuro." + +#: ../source/guides/migrating-to-pypi-org.rst:134 +msgid "Downloading packages" +msgstr "Baixando pacotes" + +#: ../source/guides/migrating-to-pypi-org.rst:136 +msgid "``pypi.org`` is the default host for downloading packages." +msgstr "``pypi.org`` é o host padrão para download de pacotes." + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "Gerenciando pacotes e lançamentos publicados" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" +"``pypi.org`` fornece uma interface totalmente funcional para usuários " +"autenticados gerenciarem seus pacotes publicados e lançamentos." + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "Como modernizar um projeto baseado em ``setup.py``?" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "``pyproject.toml`` deve ser adicionado?" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" +"Um arquivo :term:`pyproject.toml` é fortemente recomendado. A presença de um " +"arquivo :file:`pyproject.toml` em si não traz muita coisa. [#]_ O que é " +"realmente recomendado é a tabela ``[build-system]`` " +"no :file:`pyproject.toml`." + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" +"Observe que isso tem influência no recurso de isolamento de construção do " +"pip, veja abaixo." + +#: ../source/guides/modernize-setup-py-project.rst:23 +msgid "" +"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 "" +"Não, :file:`setup.py` pode existir em um projeto moderno baseado " +"em :ref:`setuptools`. O arquivo :term:`setup.py` é um arquivo de " +"configuração válido para setuptools que foi escrito em Python. No entanto, " +"os seguintes comandos for descontinuados e **NÃO DEVEM** ser mais " +"executados, e seus comandos de substituição recomendados devem ser usados:" + +#: ../source/guides/modernize-setup-py-project.rst:36 +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 "Para mais detalhes:" + +#: ../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 "Onde começar?" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" +"O :term:`projeto` deve conter um arquivo :file:`pyproject.toml` na raiz de " +"sua árvore de fontes que contém uma tabela ``[build-system]`` como esta:" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" +"Este é o método padronizado para permitir que :term:`frontends de construção " +"` saibam que :ref:`setuptools` é o :term:`backend de " +"construção ` para este projeto." + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" +"Observe que a presença de um arquivo :file:`pyproject.toml` (mesmo que " +"vazio) aciona :ref:`pip` para alterar seu comportamento padrão para usar " +"*isolamento de construção*." + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr ":ref:`distributing-packages`" + +#: ../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/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +#, fuzzy +#| msgid ":doc:`pip:reference/build-system/pyproject-toml`" +msgid ":doc:`pip:reference/build-system`" +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 "Como lidar com dependências de tempo de construção adicionais?" + +#: ../source/guides/modernize-setup-py-project.rst:76 +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 " +"`." +msgstr "" +"Além do próprio setuptools, se :file:`setup.py` depende de outras " +"bibliotecas de terceiros (fora da biblioteca padrão do Python), elas devem " +"ser listadas na lista ``requires`` do ``[build-system ]`` tabela, para que o " +"frontend de construção saiba instalá-los ao construir " +"as :term:`distribuições `." + +#: ../source/guides/modernize-setup-py-project.rst:82 +#: ../source/guides/modernize-setup-py-project.rst:139 +#: ../source/guides/modernize-setup-py-project.rst:174 +msgid "For example, a :file:`setup.py` file such as this:" +msgstr "Por exemplo, um arquivo :file:`setup.py` como este:" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" +"requer um arquivo :file:`pyproject.toml` como este (:file:`setup.py` " +"permanece inalterado):" + +#: ../source/guides/modernize-setup-py-project.rst:117 +msgid "What is the build isolation feature?" +msgstr "Qual é o recurso de isolamento de compilação?" + +#: ../source/guides/modernize-setup-py-project.rst:119 +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." +msgstr "" +"Frontends de construção normalmente criam um ambiente virtual efêmero onde " +"instalam apenas as dependências de construção (e suas dependências) listadas " +"em ``build-system.requires`` e acionam a construção nesse ambiente." + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" +"Para alguns projetos este isolamento é indesejado e pode ser desativado da " +"seguinte forma:" + +#: ../source/guides/modernize-setup-py-project.rst:126 +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 "Como lidar com metadados de empacotamento?" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" +"Todos os metadados estáticos podem opcionalmente ser movidos para uma tabela " +"``[project]`` em :file:`pyproject.toml`." + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" +"pode ser totalmente substituído por um arquivo :file:`pyproject.toml` como " +"este:" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" +"Leia :ref:`pyproject-project-table` para a especificação completa do " +"conteúdo permitido na tabela ``[project]``." + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "Como lidar com metadados dinâmicos?" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" +"Se alguns campos de metadados de empacotamento não forem estáticos, eles " +"precisam ser listados como ``dynamic`` nesta tabela ``[project]``." + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "pode ser modernizado desta forma:" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr ":ref:`declaring-project-metadata-dynamic`" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" +"E se alguma coisa que não possa ser alterar esperar um arquivo ``setup.py``?" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" +"Por exemplo, existe um processo que não pode ser alterado facilmente e " +"precisa executar um comando como ``python setup.py --name``." + +#: ../source/guides/modernize-setup-py-project.rst:232 +msgid "" +"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 "" +"É perfeitamente normal deixar um arquivo :file:`setup.py` na árvore de " +"fontes do projeto mesmo depois de todo o seu conteúdo ter sido movido " +"para :file:`pyproject.toml`. Este arquivo pode ser tão minimalista quanto " +"este:" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr ":ref:`pyproject-toml-spec`" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr ":doc:`setuptools:build_meta`" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "Instalações de várias versões" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" +"easy_install permite a instalação simultânea de diferentes versões do mesmo " +"projeto em um único ambiente compartilhado por vários programas que devem " +"exigir (``require``) a versão apropriada do projeto em tempo de execução " +"(usando ``pkg_resources``)." + +#: ../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." +msgstr "" +"Para muitos casos de uso, ambientes virtuais atendem a essa necessidade sem " +"a complicação da diretiva ``require``. No entanto, a vantagem de instalações " +"paralelas dentro do mesmo ambiente é que funciona para um ambiente " +"compartilhado por várias aplicações, como o sistema Python em uma " +"distribuição Linux." + +#: ../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." +msgstr "" +"A principal limitação da instalação paralela baseada em ``pkg_resources`` é " +"que assim que você importa ``pkg_resources`` ele bloqueia a versão *padrão* " +"de tudo que já está disponível em sys.path. Isso pode causar problemas, já " +"que ``setuptools`` scripts de linha de comando criados usam " +"``pkg_resources`` para encontrar o ponto de entrada a ser executado. Isso " +"significa que, por exemplo, você não pode usar testes de ``require`` " +"invocados através do ``nose`` ou uma aplicação WSGI invocada através do " +"``gunicorn`` se sua aplicação precisa de uma versão não padrão de qualquer " +"coisa que está disponível no ``sys.path`` padrão -- o script wrapper para a " +"aplicação principal travará na versão que está disponível por padrão, então " +"a chamada subsequente de ``require`` em seu próprio código falhará com um " +"conflito de versão espúrio." + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" +"Isso pode ser contornado definindo todas as dependências em ``__main__.__ " +"require__`` antes de importar ``pkg_resources`` pela primeira vez, mas essa " +"abordagem significa que as invocações de linha de comando padrão das " +"ferramentas afetadas não podem ser usadas -- é necessário escrever um script " +"wrapper personalizado ou usar ``python3 -c ''`` para invocar o " +"ponto de entrada principal da aplicação diretamente." + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "Empacotando extensões binárias" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "2013-12-08" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" +"Uma das características do interpretador de referência CPython é que, além " +"de permitir a execução do código Python, também expõe uma API C rica para " +"uso por outro software. Um dos usos mais comuns dessa API C é criar " +"extensões C importáveis que permitem coisas que nem sempre são fáceis de " +"alcançar em código puro Python." + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "Uma visão geral de extensões binárias" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "Casos de uso" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" +"Os casos de uso típicos para extensões binárias se dividem em apenas três " +"categorias convencionais:" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" +"**Módulos aceleradores**: esses módulos são completamente autocontidos e são " +"criados exclusivamente para executar mais rápido do que o código puro Python " +"equivalente é executado em CPython. Idealmente, os módulos aceleradores " +"sempre terão um Python equivalente puro para usar como fallback se a versão " +"acelerada não estiver disponível em um determinado sistema. A biblioteca " +"padrão do CPython faz uso extensivo de módulos aceleradores. *Exemplo*: Ao " +"importar ``datetime``, Python recorre ao módulo `datetime.py `_ se a implementação C " +"( `_datetimemodule.c `_) não estiver disponível." + +#: ../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 `_." +msgstr "" +"**módulos wrapper**: esses módulos são criados para expor as interfaces C " +"existentes ao código Python. Eles podem expor a interface C subjacente " +"diretamente ou então expor uma API mais \"Pythônica\" que faz uso dos " +"recursos da linguagem Python para tornar a API mais fácil de usar. A " +"biblioteca padrão do CPython faz uso extensivo de módulos wrapper. " +"*Exemplo*: `functools.py `_ é um módulo Python wrapper para `_functoolsmodule.c `_." + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" +"**acesso de baixo nível ao sistema**: esses módulos são criados para acessar " +"os recursos de baixo nível do tempo de execução do CPython, do sistema " +"operacional ou do hardware subjacente. Por meio do código específico da " +"plataforma, os módulos de extensão podem alcançar coisas que não são " +"possíveis no código puro Python. Vários módulos de biblioteca padrão do " +"CPython são escritos em C para acessar as partes internas do interpretador " +"que não são expostas no nível da linguagem. *Exemplo*: ``sys``, que vem de " +"`sysmodule.c `_." + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" +"Um recurso particularmente notável das extensões C é que, quando não " +"precisam chamar de volta para o tempo de execução do interpretador, podem " +"liberar o bloqueio do interpretador global do CPython em torno de operações " +"de longa duração (independentemente de essas operações serem vinculados à " +"CPU ou à E/S)." + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" +"Nem todos os módulos de extensão se encaixam perfeitamente nas categorias " +"acima. Os módulos de extensão incluídos com NumPy, por exemplo, abrangem " +"todos os três casos de uso -- eles movem loops internos para C por motivos " +"de velocidade, agrupam bibliotecas externas escritas em C, FORTRAN e outras " +"linguagens e usam interfaces de sistema de baixo nível para CPython e o " +"sistema operacional subjacente para oferecer suporte à execução simultânea " +"de operações vetorizadas e para controlar rigidamente o layout de memória " +"exato dos objetos criados." + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "Desvantagens" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" +"A principal desvantagem de usar extensões binárias é o fato de tornar a " +"distribuição subsequente do software mais difícil. Uma das vantagens de usar " +"o Python é que ele é amplamente multiplataforma, e as linguagens usadas para " +"escrever módulos de extensão (normalmente C ou C++, mas na verdade qualquer " +"linguagem que possa se ligar à API C do CPython) normalmente exigem que " +"binários personalizados podem ser criados para plataformas diferentes." + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "Isso significa que extensões binárias:" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" +"exigem que os usuários finais sejam capazes de criá-las a partir do código-" +"fonte, ou então que alguém publique binários pré-construídos para " +"plataformas comuns" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" +"pode não ser compatível com diferentes compilações do interpretador de " +"referência do CPython" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" +"frequentemente não funciona corretamente com interpretadores alternativos " +"como PyPy, Iron Python ou Jython" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" +"se codificado manualmente, torna a manutenção mais difícil, exigindo que os " +"mantenedores estejam familiarizados não apenas com Python, mas também com a " +"linguagem usada para criar a extensão binária, bem como com os detalhes da " +"API C do CPython." + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" +"se uma implementação de fallback de puro Python for fornecida, torna a " +"manutenção mais difícil, exigindo que as alterações sejam implementadas em " +"dois lugares, e introduzindo complexidade adicional no conjunto de testes " +"para garantir que ambas as versões sejam sempre executadas." + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" +"Outra desvantagem de depender de extensões binárias é que mecanismos de " +"importação alternativos (como a capacidade de importar módulos diretamente " +"de arquivos zip) geralmente não funcionam para módulos de extensão (já que " +"os mecanismos de carregamento dinâmico na maioria das plataformas só podem " +"carregar bibliotecas do disco)." + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "Alternativas para módulos aceleradores codificados manualmente" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" +"Quando os módulos de extensão estão apenas sendo usados para tornar o código " +"executado mais rápido (após a criação de perfil ter identificado o código " +"onde o aumento de velocidade vale um esforço de manutenção adicional), uma " +"série de outras alternativas também devem ser consideradas:" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" +"procure alternativas otimizadas existentes. A biblioteca padrão do CPython " +"inclui uma série de estruturas de dados e algoritmos otimizados " +"(especialmente nos módulos embutidos e ``collections`` e ``itertools``). O " +"índice de Pacotes do Python também oferece alternativas adicionais. Às " +"vezes, a escolha apropriada de biblioteca padrão ou módulo de terceiros pode " +"evitar a necessidade de criar seu próprio módulo acelerador." + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" +"para aplicações de longa execução, o `interpretador PyPy `__ compilado por JIT pode oferecer uma alternativa adequada " +"ao tempo de execução padrão do CPython. A principal barreira para a adoção " +"do PyPy é normalmente a dependência de outros módulos de extensão binários " +"-- enquanto o PyPy emula a API C do CPython, os módulos que dependem disso " +"causam problemas para o PyPy de JIT e a camada de emulação pode " +"frequentemente expor defeitos latentes na extensão módulos que o CPython " +"atualmente tolera (frequentemente em torno de erros de contagem de " +"referências -- um objeto com uma referência ativa em vez de duas geralmente " +"não quebrará nada, mas nenhuma referência em vez de uma é um grande " +"problema)." + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" +"`Cython `__ é um compilador estático maduro que pode " +"compilar a maioria dos códigos Python para módulos de extensão C. A " +"compilação inicial fornece alguns aumentos de velocidade (contornando a " +"camada de interpretador do CPython) e os recursos opcionais de tipagem " +"estática do Cython podem oferecer oportunidades adicionais para aumentos de " +"velocidade. O uso do Cython ainda carrega as `desvantagens`_ associadas ao " +"uso de extensões binárias, mas tem o benefício de ter uma barreira de " +"entrada reduzida para programadores Python (em relação a outras linguagens " +"como C ou C++)." + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" +"`Numba `__ é uma ferramenta mais recente, criada " +"por membros da comunidade científica do Python, que visa alavancar o LLVM " +"para permitir a compilação seletiva de partes de uma aplicação Python para " +"código de máquina nativo em tempo de execução. Requer que o LLVM esteja " +"disponível no sistema onde o código está sendo executado, mas pode fornecer " +"aumentos de velocidade significativos, especialmente para operações que são " +"passíveis de vetorização." + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "Alternativas para módulos wrapper codificados manualmente" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" +"A ABI C (Interface Binária de Aplicação) é um padrão comum para " +"compartilhamento de funcionalidade entre várias aplicações. Um dos pontos " +"fortes da API C do CPython (Interface de Programação de Aplicação) é " +"permitir que os usuários do Python aproveitem essa funcionalidade. No " +"entanto, empacotar módulos manualmente é muito tedioso, portanto, várias " +"outras abordagens alternativas devem ser consideradas." + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" +"As abordagens descritas abaixo não simplificam o caso de distribuição, mas " +"*podem* reduzir significativamente a carga de manutenção de manter os " +"módulos wrapper atualizados." + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" +"Além de ser útil para a criação de módulos aceleradores, o `Cython `__ também é amplamente utilizado para criar módulos wrapper " +"para APIs C ou C++. Envolve o encapsulamento manual das interfaces, o que " +"oferece uma ampla gama de liberdade no design e otimização do código do " +"encapsulamento, mas pode não ser uma boa opção para encapsular APIs muito " +"grandes rapidamente. Veja a `lista de ferramentas de terceiros `_ para encapsulamento automático com " +"Cython. Ele também oferece suporte a implementações Python orientadas para o " +"desempenho que fornecem uma API C semelhante a CPython, como PyPy e Pyston." + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" +":doc:`pybind11 ` é uma biblioteca C++11 pura que fornece uma " +"interface C++ limpa para a API C do CPython (e PyPy). Não requer uma etapa " +"de pré-processamento; ele é escrito inteiramente em C++ modelado. Auxiliares " +"são incluídos para construções de Setuptools ou CMake. Foi baseado em " +"`Boost.Python `__, mas não requer as bibliotecas Boost ou BJam." + +#: ../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 "" +":doc:`cffi ` é um projeto criado por alguns dos desenvolvedores " +"PyPy para torná-lo simples para desenvolvedores que já conhecem Python e C " +"expor seus módulos C a aplicações Python. Também torna relativamente simples " +"fazer um wrapper de um módulo C com base em seus arquivos de cabeçalho, " +"mesmo que você não conheça C." + +#: ../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." +msgstr "" +"Uma das principais vantagens do ``cffi`` é que ele é compatível com o PyPy " +"de JIT, permitindo que os módulos wrapper de CFFI participem totalmente das " +"otimizações JIT de rastreamento do PyPy." + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" +"`SWIG `__ é um wrapper gerador de interface que " +"permite uma variedade de linguagens de programação, incluindo Python, para " +"fazer interface com código C e C++." + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" +"O módulo ``ctypes`` da biblioteca padrão, embora útil para obter acesso a " +"interfaces de nível C quando as informações do cabeçalho não estão " +"disponíveis, sofre do fato de operar exclusivamente no nível ABI do C e, " +"portanto, não tem verificação automática de consistência entre os interface " +"realmente sendo exportada pela biblioteca e aquela declarada no código " +"Python. Em contraste, as alternativas acima são todas capazes de operar no " +"nível *API* do C, usando arquivos de cabeçalho C para garantir consistência " +"entre a interface exportada pela biblioteca sendo empacotada e aquela " +"esperada pelo módulo empacotador Python. Enquanto ``cffi`` *pode* operar " +"diretamente no nível ABI do C, ele sofre dos mesmos problemas de " +"inconsistência de interface que ``ctypes`` quando é usado dessa forma." + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "Alternativas para acesso de baixo nível ao sistema" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" +"Para aplicações que precisam de acesso de baixo nível ao sistema " +"(independentemente do motivo), um módulo de extensão binária geralmente *é* " +"a melhor maneira de fazer isso. Isso é particularmente verdadeiro para o " +"acesso de baixo nível ao próprio tempo de execução do CPython, uma vez que " +"algumas operações (como liberar o Bloqueio Global do Interpretador) são " +"simplesmente inválidas quando o interpretador está executando o código, " +"mesmo se um módulo como ``ctypes`` ou ``cffi`` é usado para obter acesso às " +"interfaces API C relevantes." + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" +"Para casos em que o módulo de extensão está manipulando o sistema " +"operacional ou hardware subjacente (em vez do tempo de execução do CPython), " +"às vezes pode ser melhor apenas escrever uma biblioteca C comum (ou uma " +"biblioteca em outra linguagem de programação de sistemas como C++ ou Rust " +"que pode exportar uma ABI compatível com C) e, em seguida, usar uma das " +"técnicas de agrupamento descritas acima para tornar a interface disponível " +"como um módulo Python importável." + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "Implementando extensões binárias" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" +"O guia :doc:`Estendendo e Incorporando ` do CPython " +"inclui uma introdução a escrever um :doc:`módulo de extensão personalizado " +"no C `." + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" +"CORRIGIR: Elaborar que tudo isso é uma das razões pelas quais você " +"provavelmente *não* deseja codificar manualmente seus módulos de extensão :)" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "Ciclo de vida dos módulos de extensão" + +#: ../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 "CORRIGIR: Esta seção precisa ser mais detalhada." + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "Implicações do estado estático compartilhado e subinterpretadores" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "Implicações do GIL" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "APIs de alocação de memória" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "Compatibilidade da ABI" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" +"A API C do CPython não garante a estabilidade da ABI entre versões " +"secundárias (3.2, 3.3, 3.4, etc.). Isso significa que, normalmente, se você " +"construir um módulo de extensão em uma versão do Python, é garantido que ele " +"funcionará apenas com a mesma versão secundária do Python e não com " +"quaisquer outras versões secundárias." + +#: ../source/guides/packaging-binary-extensions.rst:270 +msgid "" +"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 "" +"Python 3.2 introduziu a API Limitada (\"Limited API\"), que é um subconjunto " +"bem definido da API C do Python. Os símbolos necessários para a API Limitada " +"formam a \"ABI estável\", que é garantidamente compatível com todas as " +"versões do Python 3.x. Wheels contendo extensões construídas na ABI estável " +"usam a tag de ABI ``abi3``, para refletir que são compatíveis com todas as " +"versões do Python 3.x." + +#: ../source/guides/packaging-binary-extensions.rst:277 +msgid "" +"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 "" +"A página :doc:`Estabilidade da API C ` do CPython " +"fornece informações detalhadas sobre as garantias de estabilidade da API/" +"ABI, como usar a API Limitada e o conteúdo exato da \"API Limitada\"." + +#: ../source/guides/packaging-binary-extensions.rst:283 +msgid "Building binary extensions" +msgstr "Construindo extensões binárias" + +#: ../source/guides/packaging-binary-extensions.rst:285 +msgid "FIXME: Cover the build-backends available for building extensions." +msgstr "" +"CORRIGIR: Cobrir os backends de construção disponíveis para construir " +"extensões." + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "Construindo extensões para várias plataformas" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" +"Se você planeja distribuir sua extensão, você deve fornecer :term:`wheels " +"` para todas as plataformas que pretende oferecer suporte. Geralmente " +"são construídos em sistemas de integração contínua (CI). Existem ferramentas " +"para lhe ajudar a construir binários altamente redistribuíveis de CI; estes " +"incluem :ref:`cibuildwheel` e :ref:`multibuild`." + +#: ../source/guides/packaging-binary-extensions.rst:296 +msgid "" +"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 "" +"Para a maioria das extensões, você precisará construir wheels para todas as " +"plataformas que pretende suportar. Isso significa que o número de wheels que " +"você precisa construir é o produto de::" + +#: ../source/guides/packaging-binary-extensions.rst:302 +msgid "" +"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 "" +"Usar a :ref:`ABI Estável ` do CPython pode ajudar a " +"reduzir significativamente o número de wheels que você precisa fornecer, já " +"que um único wheel em uma plataforma pode ser usada com todas as versões " +"secundárias do Python; eliminando uma dimensão da matriz. Também elimina a " +"necessidade de gerar novos wheels para cada nova versão secundária do Python." + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "Extensões binárias para Windows" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" +"Antes que seja possível construir uma extensão binária, é necessário " +"garantir que você tenha um compilador adequado disponível. No Windows, o " +"Visual C é usado para construir o interpretador oficial do CPython e deve " +"ser usado para construir extensões binárias compatíveis. Para configurar um " +"ambiente de construção para extensões binárias, instale o `Visual Studio " +"Community Edition `__ -- " +"qualquer versão recente já serve." + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" +"Uma ressalva: se você usar o Visual Studio 2019 ou posterior, sua extensão " +"dependerá de um arquivo \"extra\", ``VCRUNTIME140_1.dll``, além do " +"``VCRUNTIME140.dll`` que todas as versões anteriores de 2015 dependem sobre. " +"Isso adicionará um requisito extra ao uso de sua extensão em versões do " +"CPython que não incluem este arquivo extra. Para evitar isso, você pode " +"adicionar o argumento de tempo de compilação ``/d2FH4-``. Versões recentes " +"do Python podem incluir este arquivo." + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" +"Não é recomendável construir para Python antes de 3.5, porque as versões " +"anteriores do Visual Studio não estão mais disponíveis na Microsoft. Se você " +"precisa construir para versões mais antigas, você pode definir " +"``DISTUTILS_USE_SDK=1`` and ``MSSdk=1`` para forçar uma versão atualmente " +"ativada do MSVC a ser encontrada, e você deve ter cuidado ao projetar sua " +"extensão não alocar/liberar memória em bibliotecas diferentes, evitar " +"depender de estruturas de dados alteradas e assim por diante. Ferramentas " +"para gerar módulos de extensão geralmente evitam essas coisas para você." + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "Extensões binárias para Linux" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" +"Os binários do Linux devem usar uma glibc suficientemente antiga para serem " +"compatíveis com distribuições mais antigas. As imagens Docker do `manylinux " +"`_ fornecem um ambiente de construção com " +"uma glibc antiga o suficiente para oferecer suporte à maioria das " +"distribuições Linux atuais em arquiteturas comuns." + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "Extensões binárias para macOS" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" +"A compatibilidade binária no macOS é determinada pelo sistema mínimo alvo de " +"implantação, por exemplo, *10.9*, que geralmente é especificado com a " +"variável de ambiente ``MACOSX_DEPLOYMENT_TARGET`` ao construir binários no " +"macOS. Ao construir com setuptools / distutils, o alvo de implantação é " +"especificado com o sinalizador ``--plat-name``, por exemplo, ``macosx-10.9-" +"x86_64``. Para alvos de implantação comuns para distribuições do Python para " +"macOS, consulte a `Spinning Wheels na wiki do MacPython `_." + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "Publicando extensões binárias" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" +"A publicação de extensões binárias por meio do PyPI usa os mesmos mecanismos " +"de upload que a publicação de pacotes Python puros. Você constrói um arquivo " +"wheel para sua extensão usando o backend de construção e carrega-o no PyPI " +"usando :doc:`twine `." + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "Evite lançamentos somente binários" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" +"É altamente recomendável que você publique suas extensões binárias, bem como " +"o código-fonte usado para construí-las. Isso permite que os usuários criem a " +"extensão a partir do código-fonte, se necessário. Notavelmente, isso é " +"necessário para certas distribuições Linux que compilam a partir do código-" +"fonte em seus próprios sistemas de compilação para os repositórios de " +"pacotes de distribuição." + +#: ../source/guides/packaging-binary-extensions.rst:374 +msgid "Weak linking" +msgstr "Ligação fraca" + +#: ../source/guides/packaging-binary-extensions.rst:379 +msgid "Additional resources" +msgstr "Recursos adicionais" + +#: ../source/guides/packaging-binary-extensions.rst:381 +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." +msgstr "" +"O desenvolvimento e distribuição multiplataforma de módulos de extensão é um " +"tópico complexo, portanto, este guia se concentra principalmente em fornecer " +"indicadores para várias ferramentas que automatizam o tratamento dos " +"desafios técnicos subjacentes. Os recursos adicionais nesta seção são " +"destinados a desenvolvedores que procuram entender mais sobre as interfaces " +"binárias subjacentes das quais esses sistemas dependem em tempo de execução." + +#: ../source/guides/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "Geração de wheel multiplataforma com scikit-build" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" +"O pacote `scikit-build `_ " +"ajuda a abstrair as operações de construção multiplataforma e fornece " +"recursos adicionais ao criar pacotes de extensões binárias. Documentação " +"adicional também está disponível no `tempo de execução C, compilador e " +"gerador de sistema de construção `_ para módulos Python de extensão binária." + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "Introdução a módulos de extensão C/C++" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" +"Para uma explicação mais detalhada de como os módulos de extensão são usados " +"pelo CPython em um sistema Debian, consulte os seguintes artigos (todos em " +"inglês):" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" +"`O que são módulos de extensão (c)python? `_" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "`Liberando o gil `_" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" +"`Escrevendo módulos de extensão cpython usando C++ `_" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "Empacotando pacotes de espaço de nomes" + +#: ../source/guides/packaging-namespace-packages.rst: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 "" +"Os pacotes de espaço de nomes permitem que você divida os subpacotes e " +"módulos dentro de um único :term:`pacote ` em " +"vários :term:`pacotes de distribuição ` (referidos " +"como **distribuições** em este documento para evitar ambiguidade). Por " +"exemplo, se você tiver a seguinte estrutura de pacote:" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "E você usa este pacote em seu código assim::" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" +"Então você pode quebrar esses subpacotes em duas distribuições separadas:" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" +"Cada subpacote pode agora ser instalado, usado e versionado separadamente." + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" +"Os pacotes de espaço de nomes podem ser úteis para uma grande coleção de " +"pacotes vagamente relacionados (como um grande corpo de bibliotecas de " +"cliente para vários produtos de uma única empresa). No entanto, os pacotes " +"de espaço de nomes vêm com várias ressalvas e não são apropriados em todos " +"os casos. Uma alternativa simples é usar um prefixo em todas as suas " +"distribuições, como ``import mynamespace_subpackage_a`` (você pode até usar " +"``import mynamespace_subpackage_a as subpackage_a`` para manter o objeto de " +"importação curto)." + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "Criando um pacote de espaço de nomes" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" +"Atualmente, existem duas abordagens diferentes para a criação de pacotes de " +"espaço de nomes, das quais a última é desencorajado:" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" +"Usar `pacotes de espaço de nomes nativos`_. Este tipo de pacote de espaço de " +"nomes é definido na :pep:`420` e está disponível em Python 3.3 e posterior. " +"Isso é recomendado se os pacotes em seu espaço de nomes precisarem apenas " +"oferecer suporte ao Python 3 e à instalação via ``pip``." + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" +"Use `pacotes de espaço de nomes legados`_. Isso compreende `pacotes de " +"espaço de nomes no estilo pkgutil`_ e `pacotes de espaço de nomes no estilo " +"pkg_resources`_." + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "Pacotes se espaço de nomes nativos" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" +"Python 3.3 adicionou pacotes de espaço de nomes **implícitos** a partir " +"da :pep:`420`. Tudo o que é necessário para criar um pacote de espaço de " +"nomes nativo é omitir :file:`__init__.py` do diretório do pacote de espaço " +"de nomes. Um exemplo de estrutura de arquivo (seguindo :ref:`src-layout " +"`):" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" +"É extremamente importante que toda distribuição que usa o pacote de espaço " +"de nomes omita o :file:`__init__.py` ou use um :file:`__init__.py` no estilo " +"pkgutil. Se alguma distribuição não o fizer, isso fará com que a lógica do " +"espaço de nomes falhe e os outros subpacotes não serão importáveis." + +#: ../source/guides/packaging-namespace-packages.rst:99 +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`:" +msgstr "" +"A estrutura de diretórios ``src-layout`` permite a descoberta automática de " +"pacotes pela maioria dos :term:`backends de construção `. " +"Veja :ref:`src-layout-vs-flat-layout` para mais informações. Se, no entanto, " +"você mesmo deseja gerenciar exclusões ou inclusões de pacotes, isso é " +"possível de ser configurado no :file:`pyproject.toml` de nível superior:" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "O mesmo pode ser feito com um :file:`setup.cfg`:" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "Ou :file:`setup.py`:" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" +":ref:`setuptools` irá pesquisar na estrutura de diretórios por pacotes de " +"espaço de nomes implícitos por padrão." + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" +"Um exemplo de trabalho completo de dois pacotes de espaço de nomes nativos " +"pode ser encontrado no `projeto exemplo de pacote de espaço de nomes " +"nativo`_." + +#: ../source/guides/packaging-namespace-packages.rst:151 +msgid "" +"Because native and pkgutil-style namespace packages are largely compatible, " +"you can use native namespace packages in the distributions that only support " +"Python 3 and pkgutil-style namespace packages in the distributions that need " +"to support Python 2 and 3." +msgstr "" +"Como os pacotes de espaço de nomes nativos e no estilo pkgutil são " +"amplamente compatíveis, você pode usar pacotes de espaço de nomes nativos " +"nas distribuições que oferecem suporte apenas a Python 3 e pacotes de espaço " +"de nomes no estilo pkgutil nas distribuições que precisam oferecer suporte a " +"Python 2 e 3." + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +msgstr "Pacotes de espaço de nomes legados" + +#: ../source/guides/packaging-namespace-packages.rst:160 +#, fuzzy +#| 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." +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 one of these " +"methods." +msgstr "" +"Esses dois métodos, que eram usados para criar pacotes de espaço de nomes " +"antes de :pep:`420`, agora são considerados descontinuados e não devem ser " +"usados a menos que você precise de compatibilidade com pacotes que já usam " +"esse método. Além disso, :doc:`pkg_resources ` foi " +"descontinuado." + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" +"Para migrar um pacote existente, todos os pacotes que compartilham o espaço " +"de nomes devem ser migrados simultaneamente." + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" +"Embora os pacotes de espaço de nomes nativos e pacotes de espaço de nomes no " +"estilo pkgutil sejam amplamente compatíveis, os pacotes de espaço de nomes " +"no estilo pkg_resources não são compatíveis com os outros métodos. Não é " +"aconselhável usar métodos diferentes em distribuições diferentes que " +"fornecem pacotes para o mesmo espaço de nomes." + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "Pacotes de espaço de nomes no estilo pkgutil" + +#: ../source/guides/packaging-namespace-packages.rst:175 +#, fuzzy +#| 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." +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" +"Python 2.3 introduziu o módulo :doc:`pkgutil ` e a " +"função :py:func:`python:pkgutil.extend_path`. Isso pode ser usado para " +"declarar pacotes de espaço de nomes que precisam ser compatíveis com Python " +"2.3+ e Python 3. Esta é a abordagem recomendada para o nível mais alto de " +"compatibilidade." + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" +"Para criar um pacote de espaço de nomes no estilo pkgutil, você precisa " +"fornecer um arquivo :file:`__init__.py` para o pacote de espaço de nomes:" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" +"O arquivo :file:`__init__.py` para o pacote de espaço de nomes precisa " +"conter o seguinte:" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" +"**Cada** distribuição que usa o pacote de espaço de nomes deve incluir " +"um :file:`__init__.py`. Se alguma distribuição não o fizer, isso fará com " +"que a lógica do espaço de nomes falhe e os outros subpacotes não serão " +"importáveis. Qualquer código adicional no :file:`__init__.py` ficará " +"inacessível." + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" +"Um exemplo completamente funcional de dois pacotes de espaço de nomes no " +"estilo pkgutil pode ser encontrado no `projeto exemplo de espaço de nomes de " +"pkgutil`_." + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "Pacotes de espaço de nomes no estilo pkg_resources" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +#, fuzzy +#| 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." +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 ` fornece a função " +"`pkg_resources.declare_namespace`_ e o argumento ``namespace_packages`` " +"para :func:`~setuptools.setup`. Juntos, eles podem ser usados para declarar " +"pacotes de espaço de nomes. Embora essa abordagem não seja mais recomendada, " +"ela está amplamente presente na maioria dos pacotes de espaço de nomes " +"existentes. Se você estiver criando uma nova distribuição dentro de um " +"pacote de espaço de nomes existente que usa esse método, é recomendável " +"continuar usando-o, pois os diferentes métodos não são compatíveis entre si " +"e não é aconselhável tentar migrar um pacote existente." + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" +"Para criar um pacote de espaço de nomes no estilo pkg_resources, você " +"precisa fornecer um arquivo :file:`__init __. Py` para o pacote de espaço de " +"nomes:" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" +"Algumas recomendações mais antigas aconselham o seguinte " +"no :file:`__init__.py` de pacotes de espaço de nomes:" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" +"A ideia por trás disso era que, no caso raro de setuptools não estar " +"disponível, os pacotes recorreriam aos pacotes no estilo pkgutil. Isso não é " +"aconselhável porque os pacotes de espaço de nomes estilo pkgutil e " +"pkg_resources não são compatíveis entre si. Se a presença de setuptools é " +"uma preocupação, então o pacote deve depender explicitamente de setuptools " +"via ``install_requires``." + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" +"Finalmente, cada distribuição deve fornecer o argumento " +"``namespace_packages`` para :func:`~setuptools.setup` no :file:`setup.py`. " +"Por exemplo:" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" +"Publicando versões de distribuição de pacotes usando fluxos de trabalho de " +"CI/CD do GitHub Actions" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" +"O `CI/CD do GitHub Actions`_ permite que você execute uma série de comandos " +"sempre que ocorrer um evento na plataforma GitHub. Uma escolha popular é ter " +"um fluxo de trabalho que é disparado por um evento ``push``. Este guia " +"mostra como publicar uma distribuição Python sempre que um commit marcado é " +"enviado. Ele usará o `GitHub Action pypa/gh-action-pypi-publish`_ para " +"publicação. Ele também usa as actions `upload-artifact`_ e `download-" +"artifact`_ do GitHub para temporariamente armazenar e baixar os pacotes " +"fontes." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst: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." +msgstr "" +"Este guia *presume* que você já tem um projeto para o qual sabe como " +"construir distribuições e *ele reside no GitHub*. Este guia também evita " +"detalhes da construção de projetos específicos da plataforma. Se você tiver " +"componentes binários, confira os exemplos de GitHub Action " +"do :ref:`cibuildwheel`." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:25 +#, fuzzy +#| msgid "Configuring trusted publishing" +msgid "Configuring Trusted Publishing" +msgstr "Configurando publicação confiável" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:27 +#, fuzzy +#| 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." +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." +msgstr "" +"Este guia se baseia na implementação de `publicação confiável`_ do PyPI para " +"se conectar ao `CI/CD do GitHub Actions`_. Isso é recomendado por motivos de " +"segurança, pois os tokens gerados são criados para cada um dos seus projetos " +"individualmente e expiram automaticamente. Caso contrário, você precisará " +"gerar um `token de API`_ para PyPI e TestPyPI. No caso de publicação em " +"índices de terceiros como :doc:`devpi `, pode ser necessário " +"fornecer uma combinação de nome de usuário/senha." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +#, fuzzy +#| 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." +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." +msgstr "" +"Como este guia demonstrará o envio para PyPI e TestPyPI, precisaremos de " +"dois publicadores confiáveis configurados. As etapas a seguir guiarão você " +"na criação dos publicadores \"pendentes\" para seu novo :term:`Projeto PyPI " +"`. No entanto, também é possível adicionar `publicação confiável`_ " +"a qualquer projeto preexistente, se você for o proprietário." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" +"Se você seguiu versões anteriores deste guia, você criou os segredos " +"``PYPI_API_TOKEN`` e ``TEST_PYPI_API_TOKEN`` para acesso direto ao PyPI e " +"TestPyPI. Eles estão descontinuados agora e você deve removê-los de seu " +"repositório GitHub e revogá-los nas configurações de sua conta PyPI e " +"TestPyPI, caso esteja substituindo sua configuração antiga pela nova." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:51 +msgid "Let's begin! 🚀" +msgstr "Vamos começar! 🚀" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:53 +msgid "Go to https://pypi.org/manage/account/publishing/." +msgstr "Acesse https://pypi.org/manage/account/publishing/." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" +"Preencha o nome com o qual deseja publicar seu novo :term:`projeto PyPI " +"` em (o valor ``name`` em seu ``setup.cfg`` ou ``pyproject.toml``), " +"o nome do proprietário do repositório no GitHub (organização ou usuário), e " +"nome do repositório, e o nome do arquivo de fluxo de trabalho de lançamento " +"na pasta ``.github/``, consulte :ref:`workflow-definition`. Por fim, " +"adicione o nome do ambiente do GitHub (``pypi``) que iremos configurar em " +"seu repositório. Registre o publicador confiável." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" +"Agora, acesse https://test.pypi.org/manage/account/publishing/ e repita a " +"segunda etapa, mas desta vez, insira ``testpypi`` como o nome do ambiente do " +"GitHub." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" +"Seus publicadores \"pendentes\" agora estão prontos para o primeiro uso e " +"criarão seus projetos automaticamente assim que você usá-los pela primeira " +"vez." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" +"Se você não tiver uma conta TestPyPI, precisará criá-la. Não é o mesmo que " +"uma conta do PyPI comum." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:78 +#, fuzzy +#| msgid "" +#| "For security reasons, you must require `manual approval `_ on each " +#| "run for the ``pypi`` environment." +msgid "" +"For security reasons, you must require `manual approval `_ on each run for the ``pypi`` environment." +msgstr "" +"Por motivos de segurança, você deve exigir a `aprovação manual `_ em cada execução " +"para o ambiente ``pypi``." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "Criando uma definição de fluxo de trabalho" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" +"Os fluxos de trabalho de CI/CD do GitHub são declarados em arquivos YAML " +"armazenados no diretório ``.github/workflows/`` do seu repositório." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +#, fuzzy +#| msgid "Let's create a ``.github/workflows/publish-to-test-pypi.yml`` file." +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" +"Vamos criar um arquivo chamado ``.github/workflows/publish-to-test-" +"pypi.yml``." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" +"Comece com um nome significativo e defina o evento que deve fazer o GitHub " +"executar este fluxo de trabalho:" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:101 +msgid "Checking out the project and building distributions" +msgstr "Fazendo checkout do projeto e construindo as distribuições" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" +"Teremos que definir dois trabalhos (\"jobs\") para publicar em PyPI e " +"TestPyPI respectivamente, e um trabalho adicional para construir os pacotes " +"de distribuição." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" +"Primeiro, definiremos o trabalho para construir os pacotes dist do seu " +"projeto e armazená-los para uso posterior:" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" +"Isso fará o download do seu repositório no executor de CI e, em seguida, " +"instalará e ativará o lançamento mais recente disponível do Python 3." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" +"E agora podemos construir os dists a partir da fonte e armazená-los. Neste " +"exemplo, usaremos o pacote ``build``. Então, adicione isso à lista de etapas:" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "Definindo um ambiente de tarefa do fluxo de trabalho" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:130 +#, fuzzy +#| 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." +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 "" +"Agora, vamos adicionar a configuração inicial para nosso trabalho que será " +"publicado no PyPI. É um processo que executará comandos que definiremos mais " +"tarde. Neste guia, usaremos a versão estável mais recente do Ubuntu LTS " +"fornecida pelo GitHub Actions. Isso também define um ambiente GitHub para o " +"trabalho ser executado em seu contexto e uma URL a ser exibida na interface " +"do GitHub. Além disso, permite adquirir um token OpenID Connect que as ações " +"``pypi-publish`` precisam para implementar publicação confiável sem segredo " +"para PyPI." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:144 +msgid "" +"This will also ensure that the PyPI publishing workflow is only triggered if " +"the current commit is tagged." +msgstr "" +"Isso também garantirá que o fluxo de trabalho de publicação do PyPI só seja " +"acionado se o commit atual estiver marcado." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "Publicando a distribuição para PyPI" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:150 +msgid "Finally, add the following steps at the end:" +msgstr "Finalmente, adicione as seguintes etapas ao final:" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" +"Essa etapa usa a GitHub Action `pypa/gh-action-pypi-publish`_: após o " +"primeiro pacote de distribuição armazenado ter sido baixado pela ação " +"`download-artifact`_, ele envia o conteúdo da pasta ``dist /`` para PyPI " +"incondicionalmente." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "Fluxo de trabalho separado para publicação no TestPyPI" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" +"Agora, repita essas etapas e crie outro trabalho para publicação no índice " +"do pacote TestPyPI na seção ``jobs``:" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" +"Exigir aprovações manuais no ambiente GitHub ``testpypi`` normalmente é " +"desnecessário, pois ele é projetado para ser executado em cada commit no " +"branch principal e é frequentemente usado para indicar um pipeline de " +"publicação de lançamento íntegro." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "O fluxo de trabalho de CI/CD completo" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" +"Este parágrafo mostra todo o fluxo de trabalho após seguir o guia acima." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "Isso é tudo, pessoal!" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" +"Agora, sempre que você fizer um push de um commit com tag para seu " +"repositório Git remoto no GitHub, este fluxo de trabalho irá publicá-lo no " +"PyPI. E publicará qualquer push para TestPyPI que seja útil para fornecer " +"construções de teste para seus usuários alfa, bem como garantir que sua " +"versão pipeline permaneça saudável!" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" +"Se o seu repositório tiver atividade de commit frequente e cada push for " +"carregado no TestPyPI conforme descrito, o projeto poderá exceder o `limite " +"de tamanho do projeto PyPI `_. O " +"limite poderia ser aumentado, mas uma solução melhor pode consistir em usar " +"um servidor compatível com PyPI como :ref:`pypiserver` no CI para fins de " +"teste." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" +"Recomenda-se manter o GitHub Actions integrado em suas versões mais " +"recentes, atualizando-as frequentemente." + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "Construção e publicação" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "Hospedagem" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +msgid "Installation" +msgstr "Instalação" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +#, fuzzy +#| msgid "Single-sourcing the package version" +msgid "Redirecting stale single-source package version link..." +msgstr "Mantendo uma única fonte da versão do pacote" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "Fornecendo suporte a várias versões do 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 "" +"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 "" +"Além do trabalho necessário para criar um pacote Python, geralmente é " +"necessário que o pacote esteja disponível em diferentes versões do Python. " +"Diferentes versões Python podem conter diferentes (ou renomeados) pacotes de " +"biblioteca padrão, e as alterações entre Python versões 2.x e 3.x incluem " +"alterações na sintaxe da linguagem." + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" +"Executados manualmente, todos os testes necessários para garantir que o " +"pacote funcione corretamente em todas as versões alvo Python (e sistemas " +"operacionais!) podem consumir muito tempo. Felizmente, várias ferramentas " +"estão disponíveis para lidar com isso, e elas serão brevemente discutidas " +"aqui." + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "Testes automatizados e integração contínua" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" +"Vários serviços hospedados para testes automatizados estão disponíveis. " +"Esses serviços normalmente irão monitorar seu repositório de código-fonte " +"(por exemplo, no `GitHub `_ ou `Bitbucket `_) e executar um conjunto de testes do seu projeto toda vez " +"que um novo commit é feito." + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" +"Esses serviços também oferecem facilidades para executar o conjunto de " +"testes do seu projeto em *várias versões do Python*, fornecendo um feedback " +"rápido sobre se o código funcionará, sem que o desenvolvedor tenha que " +"realizar esses testes por conta própria." + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" +"A Wikipédia tem uma extensa `comparação `_ de muitos sistemas de " +"integração contínua. Existem dois serviços hospedados que, quando usados em " +"conjunto, fornecem testes automatizados no Linux, Mac e Windows:" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +#, fuzzy +#| 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." +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." +msgstr "" +"`Travis CI `_ fornece um ambiente Linux e macOS. O " +"ambiente Linux é Ubuntu 12.04 LTS Server Edition de 64 bits, enquanto o " +"macOS é 10.9.2 no momento da escrita." + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" +"`Appveyor `_ fornece um ambiente Windows (Windows " +"Server 2012)." + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" +"Tanto o `Travis CI`_ quanto o Appveyor_ exigem um arquivo formatado em `YAML " +"`_ como especificação para as instruções de teste. Se " +"algum teste falhar, o log de saída para essa configuração específica pode " +"ser inspecionado." + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" +"Para projetos Python que devem ser implantados em Python 2 e 3 com uma " +"estratégia de única fonte, há uma série de opções." + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "Ferramentas para pacotes Python de única fonte" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" +"`six `_ é uma ferramenta desenvolvida por " +"Benjamin Peterson para resolver as diferenças entre Python 2 e Python 3. O " +"pacote six_ desfrutou de uso generalizado e pode ser considerado como uma " +"maneira confiável de escrever um módulo Python de fonte única que pode ser " +"usado em Python 2 e 3. O módulo six_ pode ser usado a partir de Python 2.5. " +"Uma ferramenta chamada `modernize `_, " +"desenvolvida por Armin Ronacher, pode ser usada para aplicar automaticamente " +"as modificações de código fornecidas por six_." + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" +"Semelhante a six_, `python-future `_ " +"é um pacote que fornece uma camada de compatibilidade entre o código-fonte " +"de Python 2 e Python 3; no entanto, ao contrário do six_, este pacote visa " +"fornecer interoperabilidade entre Python 2 e Python 3 com uma sintaxe de " +"linguagem que corresponda a uma das duas versões Python: pode-se usar" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "um módulo Python 2 (por sintaxe) em um projeto Python 3." + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "um módulo Python 3 (por sintaxe) em um projeto *Python 3*." + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" +"Por causa da bidirecionalidade, python-future_ oferece um caminho para " +"converter um pacote Python 2 na sintaxe de Python 3, módulo por módulo. No " +"entanto, em contraste com six_, python-future_ é compatível apenas com " +"Python 2.6. Semelhante a modernize_ para six_, python-future_ vem com dois " +"scripts chamados ``futurize`` e ``pasteurize`` que podem ser aplicados a um " +"módulo Python 2 ou um módulo Python 3 respectivamente." + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" +"O uso de six_ ou python-future_ adiciona uma dependência adicional de tempo " +"de execução ao seu pacote: com python-future_, o script ``futurize`` pode " +"ser chamado com a opção ``--stage1`` para aplicar apenas as mudanças que " +"Python 2.6+ já fornece compatibilidade com versões futuras para Python 3. " +"Quaisquer problemas de compatibilidade remanescentes exigiriam alterações " +"manuais." + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "O que há em cada Python?" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" +"Ned Batchelder fornece uma lista de alterações em cada versão Python para " +"`Python 2 `__, `Python 3.0-3.3 `__ e `Python 3.4-3.6 `__. Essas " +"listas podem ser usadas para verificar se quaisquer mudanças entre as " +"versões Python podem afetar seu pacote." + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "Oferece suporte a Windows usando Appveyor" + +#: ../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 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 "" +"Esta seção cobre como usar o serviço gratuito de integração contínua " +"`Appveyor`_ para fornecer suporte a Windows para seu projeto. Isso inclui " +"testar o código no Windows e construir binários direcionados para Windows " +"para projetos que usam extensões C." + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" +"Muitos projetos são desenvolvidos em Unix por padrão, e fornecer suporte ao " +"Windows pode ser um desafio, porque configurar um ambiente de teste adequado " +"no Windows não é trivial e pode exigir a compra de licenças de software." + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" +"O serviço Appveyor é um serviço de integração contínua, muito parecido com o " +"serviço `Travis`_ mais conhecido que é comumente usado para testes por " +"projetos hospedados no `GitHub`_. No entanto, ao contrário do Travis, os " +"workers de construção no Appveyor são hosts Windows e têm os compiladores " +"necessários instalados para construir extensões Python." + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" +"Os usuários do Windows normalmente não têm acesso a um compilador C e, " +"portanto, dependem de projetos que usam extensões C distribuindo wheels " +"binárias no PyPI para que a distribuição seja instalável via ``python -m pip " +"install ``. Ao usar o Appveyor como um serviço de construção (mesmo " +"que não seja para teste), é possível para projetos sem um ambiente Windows " +"dedicado fornecer binários direcionados ao Windows." + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +msgstr "Configurando" + +#: ../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 "" +"Para usar o Appveyor para construir wheels de Windows para o seu projeto, " +"você deve ter uma conta no serviço. As instruções sobre como configurar uma " +"conta são fornecidas `na documentação do Appveyor `__. O nível de conta grátis é perfeitamente adequado para projetos de " +"código aberto." + +#: ../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 "" +"O Appveyor fornece integração com `GitHub`_ e `Bitbucket`_, portanto, desde " +"que seu projeto esteja hospedado em um desses dois serviços, configurar a " +"integração do Appveyor é simples." + +#: ../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 "" +"Depois de configurar sua conta do Appveyor e adicionar seu projeto, o " +"Appveyor construirá automaticamente seu projeto cada vez que ocorrer um " +"commit. Esse comportamento será familiar para os usuários do Travis." + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "Adicionando suporte a Appveyor ao seu projeto" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" +"Para definir como o Appveyor deve construir seu projeto, você precisa " +"adicionar um arquivo :file:`appveyor.yml` ao seu projeto. Os detalhes " +"completos do que pode ser incluído no arquivo são cobertos na documentação " +"do Appveyor. Este guia fornecerá os detalhes necessários para configurar a " +"configuração dos wheels." + +#: ../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 "" +"O Appveyor inclui por padrão todos os conjuntos de ferramentas do compilador " +"necessários para construir extensões para Python. Para Python 2.7, 3.5+ e " +"versões de 32 bits de 3.3 e 3.4, as ferramentas funcionam prontamente. Mas " +"para as versões de 64 bits do Python 3.3 e 3.4, há uma pequena quantidade de " +"configuração adicional necessária para permitir que os distutils saibam onde " +"encontrar os compiladores de 64 bits. (De 3.5 em diante, a versão do Visual " +"Studio usada inclui compiladores de 64 bits sem configuração adicional)." + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "appveyor.yml" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" +"Este arquivo pode ser baixado `daqui `__." + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" +"O arquivo :file:`appveyor.yml` deve estar localizado no diretório raiz do " +"seu projeto. Está no formato ``YAML`` e consiste em várias seções." + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" +"A seção ``environment`` é a chave para definir as versões Python para as " +"quais seus wheels serão criados. O Appveyor vem com Python 2.6, 2.7, 3.3, " +"3.4 e 3.5 instalados, em compilações de 32 e 64 bits. O arquivo de exemplo é " +"criado para todos esses ambientes, exceto Python 2.6. A instalação do Python " +"2.6 é mais complexa, pois não vem com o pip incluído. Não oferecemos suporte " +"ao 2.6 neste documento (já que os usuários do Windows que ainda usam o " +"Python 2 geralmente são capazes de migrar para o Python 2.7 sem muita " +"dificuldade)." + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" +"A seção ``install`` usa pip para instalar qualquer software adicional que o " +"projeto possa exigir. O único requisito para a construção de wheels é o " +"projeto ``wheel``, mas os projetos podem desejar personalizar este código em " +"certas circunstâncias (por exemplo, para instalar pacotes de construção " +"adicionais, como ``Cython``, ou ferramentas de teste como ``tox``)." + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" +"A seção ``build`` simplesmente desativa as construções -- não há etapa de " +"construção necessária para Python, ao contrário de linguagens como ``C#``." + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" +"As principais seções que precisarão ser adaptadas ao seu projeto são " +"``test_script`` e ``after_test``." + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" +"A seção ``test_script`` é onde você executará os testes do seu projeto. O " +"arquivo fornecido executa seu conjunto de testes usando ``setup.py test``. " +"Se você está interessado apenas em construir wheels, e não em executar seus " +"testes no Windows, você pode substituir esta seção por um comando fictício, " +"como ``echo Skipped Tests``. Você pode querer usar outra ferramenta de " +"teste, como ``nose`` ou :file:`py.test`. Ou você pode desejar usar um driver " +"de teste como o ``tox`` -- entretanto, se você estiver usando o ``tox``, " +"existem algumas alterações de configuração adicionais que você precisará " +"considerar, que são descritas abaixo." + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" +"O ``after_test`` é executado uma vez que seus testes foram concluídos, e " +"então é onde os wheels devem ser construídos. Presumindo que seu projeto usa " +"as ferramentas recomendadas (especificamente, ``setuptools``) então o " +"comando ``setup.py bdist_wheel`` irá construir seus wheels." + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" +"Observe que os wheels só serão construídos se seus testes forem bem-" +"sucedidos. Se você espera que seus testes falhem no Windows, você pode pulá-" +"los conforme descrito acima." + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "Script de suporte" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" +"O arquivo :file:`appveyor.yml` depende de um único script de suporte, que " +"configura o ambiente para usar o compilador SDK para compilações de 64 bits " +"no Python 3.3 e 3.4. Para projetos que não precisam de um compilador, ou que " +"não oferecem suporte a 3.3 ou 3.4 em Windows 64 bits, apenas o " +"arquivo :file:`appveyor.yml` é necessário." + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" +"`build.cmd `__ é um script em lote " +"do Windows que executa um único comando em um ambiente com o compilador " +"apropriado para a versão Python selecionada. Tudo que você precisa fazer é " +"definir a única variável de ambiente ``DISTUTILS_USE_SDK`` para um valor de " +"``1`` e o script faz o resto. Ele configura o SDK necessário para " +"compilações de 64 bits de Python 3.3 ou 3.4, portanto, não defina a variável " +"de ambiente para quaisquer outras compilações." + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" +"Você pode simplesmente baixar o arquivo em lote e incluí-lo em seu projeto " +"inalterado." + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "Acesso aos wheels construídos" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" +"Quando sua construção for concluída, os wheels construídos estarão " +"disponíveis no painel de controle do Appveyor para o seu projeto. Eles podem " +"ser encontrados acessando a página de status de construção de cada " +"construção por vez. No topo da saída de construção, há uma série de links, " +"um dos quais é \"Artifacts\" (Artefatos). Essa página incluirá uma lista de " +"links para os wheels dessa versão Python / arquitetura. Você pode baixar " +"esses wheels e enviá-los para PyPI como parte de seu processo de lançamento." + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "Testando com tox" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" +"Muitos projetos usam a ferramenta :doc:`Tox ` para executar seus " +"testes. Ele garante que os testes sejam executados em um ambiente isolado " +"usando os arquivos exatos que serão distribuídos pelo projeto." + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" +"Para usar o ``tox`` no Appveyor, há algumas considerações adicionais (na " +"verdade, esses problemas não são específicos do Appveyor e podem afetar " +"outros sistemas de CI)." + +#: ../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." +msgstr "" +"Por padrão, ``tox`` apenas passa um subconjunto escolhido de variáveis de " +"ambiente para os processos de teste. Como ``distutils`` usa variáveis de " +"ambiente para controlar o compilador, este recurso de \"isolamento de " +"teste\" fará com que os testes usem o compilador errado por padrão." + +#: ../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 "" +"Para forçar o ``tox`` passar as variáveis de ambiente necessárias para o " +"subprocesso, você precisa definir a opção de configuração ``passenv`` do " +"``tox`` para listar as variáveis de ambiente adicionais a serem passadas " +"para o subprocesso. Para os compiladores SDK, você precisa" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "``DISTUTILS_USE_SDK``" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "``MSSdk``" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "``INCLUDE``" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +msgstr "``LIB``" + +#: ../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." +msgstr "" +"A opção ``passenv`` pode ser definida em seu :file:`tox.ini`, ou se você " +"preferir evitar adicionar configurações específicas do Windows aos seus " +"arquivos de projeto gerais, pode ser definida configurando a variável de " +"ambiente ``TOX_TESTENV_PASSENV``. O script :file:`build.cmd` fornecido faz " +"isso por padrão sempre que ``DISTUTILS_USE_SDK`` é definida." + +#: ../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)." +msgstr "" +"Quando usado interativamente, ``tox`` permite que você execute seus testes " +"em vários ambientes (frequentemente, isso significa várias versões do " +"Python). Este recurso não é tão útil em um ambiente de CI como Travis ou " +"Appveyor, onde todos os testes são executados em ambientes isolados para " +"cada configuração. Como resultado, os projetos geralmente fornecem um " +"argumento ``-e NOMEENV`` para ``tox`` para especificar qual ambiente usar " +"(há ambientes padrão para a maioria das versões do Python)." + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" +"No entanto, isso *não* funciona bem com um sistema de CI no Windows como o " +"Appveyor, onde há (por exemplo) duas instalações de Python 3.4 (32 bits e 64 " +"bits) disponíveis, mas apenas um ambiente ``py34`` no ``tox``." + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" +"Para executar testes usando o ``tox``, portanto, os projetos provavelmente " +"devem usar o ambiente padrão ``py`` no ``tox``, que usa o interpretador " +"Python que foi usado para executar ``tox`` . Isso garantirá que, quando o " +"Appveyor executar os testes, eles serão executados com o interpretador " +"configurado." + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" +"Para oferecer suporte à execução no ambiente ``py``, é possível que projetos " +"com configurações complexas de ``tox`` precisem modificar seu " +"arquivo :file:`tox.ini`. Fazer isso está, no entanto, fora do escopo deste " +"documento." + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "Enviando automaticamente wheels" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" +"É possível solicitar que o Appveyor envie automaticamente os wheels. Há uma " +"etapa ``deployment`` disponível no :file:`appveyor.yml` que pode ser usada " +"para, por exemplo, copiar os artefatos construídos para um site FTP ou uma " +"instância do Amazon S3. A documentação sobre como fazer isso está incluída " +"nos guias do Appveyor." + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" +"Alternativamente, seria possível adicionar um passo ``twine upload`` à " +"construção. O :file:`appveyor.yml` fornecido não faz isso, pois não está " +"claro se é desejável enviar novos wheels após cada commit (embora alguns " +"projetos possam desejar fazer isso)." + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "Dependências externas" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" +"Os scripts fornecidos construirão com sucesso qualquer distribuição que não " +"dependa de bibliotecas externas de terceiros para a construção." + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" +"É possível adicionar etapas à configuração :file:`appveyor.yml` (normalmente " +"na seção \"install\") para baixar e/ou construir bibliotecas externas " +"necessárias para a distribuição. E se necessário, é possível adicionar " +"configuração extra para a construção para fornecer a localização dessas " +"bibliotecas para o compilador. No entanto, esse nível de configuração está " +"além do escopo deste documento." + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "Scripts de suporte" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" +"Para referência, o script de suporte de configuração do SDK está listado " +"aqui:" + +#: ../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 "Recomendações de ferramentas" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" +"O cenário de empacotamento do Python consiste em muitas ferramentas " +"diferentes. Para muitas tarefas, o :term:`Python Packaging Authority ` (PyPA, o grupo de trabalho que engloba muitas " +"ferramentas de empacotamento e mantém este guia) propositalmente não faz uma " +"recomendação geral; por exemplo, a razão pela qual existem muitos backends " +"de construção é que o cenário foi aberto para permitir o desenvolvimento de " +"novos backends que atendam melhor às necessidades de determinados usuários " +"do que o backend anteriormente exclusivo, setuptools. Este guia aponta " +"algumas ferramentas que são amplamente reconhecidas e também faz algumas " +"recomendações de ferramentas que você *não* deve usar porque estão " +"descontinuadas ou são inseguras." + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "Ambientes virtuais" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" +"As ferramentas padrão para criar e usar ambientes virtuais manualmente " +"são :ref:`virtualenv` (projeto PyPA) e :doc:`venv ` " +"(parte da biblioteca padrão Python, embora falte alguns recursos do " +"virtualenv) ." + +#: ../source/guides/tool-recommendations.rst:28 +msgid "Installing packages" +msgstr "Instalando pacotes" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" +":ref:`Pip` é a ferramenta padrão para instalar pacotes do :term:`PyPI " +"`. Você pode querer ler as recomendações do pip " +"para obter :doc:`instalações seguras `. Pip está " +"disponível por padrão na maioria das instalações do Python através do pacote " +"de biblioteca padrão :doc:`ensurepip `." + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" +"Alternativamente, considere :ref:`pipx` para o caso de uso específico de " +"instalação de aplicativos Python que são distribuídos por meio de PyPI e " +"executados a partir da linha de comando. Pipx é um wrapper em torno de pip e " +"venv que instala cada aplicativo em um ambiente virtual dedicado. Isso evita " +"conflitos entre as dependências de diferentes aplicações, e também com " +"aplicações de todo o sistema que utilizam o mesmo interpretador Python " +"(especialmente no Linux)." + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" +"Especificamente para software científico, considere :ref:`Conda` " +"ou :ref:`Spack`." + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" +"Escreva uma comparação \"pip vs. Conda\", aqui ou em uma nova discussão." + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" +"**Não** use ``easy_install`` (parte de :ref:`setuptools`), que foi " +"descontinuado em favor do pip (veja :ref:`pip vs easy_install` para " +"detalhes). Da mesma forma, **não** use ``python setup.py install`` ou " +"``python setup.py develop``, que também foram descontinuados " +"(veja :ref:`setup-py-deprecated` para aprofundamento e :ref:`modernize-setup-" +"py-project` para aconselhamento sobre migração)." + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "Arquivos de bloqueio" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" +":ref:`pip-tools` e :ref:`Pipenv` são duas ferramentas reconhecidas para " +"criar arquivos de bloqueio, que contêm as versões exatas de todos os pacotes " +"instalados em um ambiente, para fins de reprodutibilidade." + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "Backends de construção" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" +"Por favor, lembre-se: este documento não procura orientar o leitor para uma " +"ferramenta específica, apenas enumerar ferramentas comuns. Diferentes casos " +"de uso geralmente precisam de fluxos de trabalho especializados." + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +#, fuzzy +#| msgid "Building binary extensions" +msgid "Build backends for extension modules" +msgstr "Construindo extensões binárias" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +#, fuzzy +msgid "Building distributions" +msgstr "Distribuição Construída" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +#, fuzzy +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." +msgstr "" +"Se você tem extensões binárias e deseja distribuir wheels para várias " +"plataformas, use :ref:`cibuildwheel` como parte de sua configuração de CI " +"para construir wheels distribuíveis." + +#: ../source/guides/tool-recommendations.rst:145 +#, fuzzy +msgid "Uploading to PyPI" +msgstr "Enviando seu Projeto para PyPI" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +#, fuzzy +msgid ":ref:`Flit`," +msgstr ":ref:`pip`" + +#: ../source/guides/tool-recommendations.rst:180 +#, fuzzy +msgid ":ref:`Hatch`," +msgstr "pip, :ref:`bandersnatch`" + +#: ../source/guides/tool-recommendations.rst:181 +#, fuzzy +msgid ":doc:`nox `," +msgstr ":doc:`Documentação `" + +#: ../source/guides/tool-recommendations.rst:182 +#, fuzzy +msgid ":ref:`PDM`," +msgstr ":ref:`pip`" + +#: ../source/guides/tool-recommendations.rst:183 +#, fuzzy +msgid ":ref:`Pipenv`," +msgstr ":ref:`pip`" + +#: ../source/guides/tool-recommendations.rst:184 +#, fuzzy +msgid ":ref:`Poetry`," +msgstr ":ref:`pip`" + +#: ../source/guides/tool-recommendations.rst:185 +#, fuzzy +msgid ":doc:`tox `." +msgstr ":doc:`Documentação `" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" +"Incluindo arquivos em distribuições de código-fonte com ``MANIFEST.in``" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" +"As informações nesta página foram movidas para :doc:`setuptools:userguide/" +"miscellaneous` na documentação do setuptools." + +#: ../source/guides/using-testpypi.rst:7 +msgid "" +"``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 "" +"``Test PyPI`` é uma instância separada do :term:`Python Package Index " +"(PyPI)` que permite que você experimente as ferramentas de distribuição e o " +"processo sem se preocupar em afetar o índice real. O TestPyPI está hospedado " +"em `test.pypi.org `_" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "Registrando sua conta" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" +"Como o TestPyPI tem um banco de dados separado do PyPI real, você precisará " +"de uma conta de usuário separada especificamente para o TestPyPI. Vá para " +"https://test.pypi.org/account/register/ para registrar sua conta." + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" +"O banco de dados do TestPyPI pode ser apagado periodicamente, portanto, não " +"é incomum que contas de usuário sejam excluídas." + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "Usando TestPyPI com Twine" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" +"Você pode enviar suas distribuições para TestPyPI usando :ref:`twine` " +"especificando o sinalizador ``--repository``:" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" +"Você pode ver se o seu pacote foi enviado com sucesso navegando para a URL " +"``https://test.pypi.org/project/`` onde ``projetoexemplo`` é " +"o nome do seu projeto que você enviou. O seu projeto pode demorar um ou dois " +"minutos para aparecer no site." + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "Usando TestPyPI com pip" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" +"Você pode dizer ao :ref:`pip` para baixar pacotes do TestPyPI, em vez do " +"PyPI, especificando o sinalizador ``--index-url``:" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" +"Se você quiser permitir que pip também baixe outros pacotes do PyPI, você " +"pode especificar ``--extra-index-url`` para apontar para PyPI. Isso é útil " +"quando o pacote que você está testando tem dependências:" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "Configurando TestPyPI no :file:`.pypirc`" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" +"Se você quiser evitar ser solicitado a informar seu nome de usuário e senha " +"toda vez, você pode configurar o TestPyPI em seu :file:`$HOME/.pypirc`:" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "Escrevendo seu ``pyproject.toml``" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" +"``pyproject.toml`` é um arquivo de configuração usado por ferramentas de " +"empacotamento, bem como outras ferramentas como linters, verificadores de " +"tipo, etc. Existem três tabelas TOML possíveis neste arquivo." + +#: ../source/guides/writing-pyproject-toml.rst:11 +msgid "" +"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 "" +"A tabela ``[build-system]`` é **altamente recomendada**. Ela permite que " +"você declare qual :term:`backend de construção` você usa e quais outras " +"dependências são necessárias para construir seu projeto." + +#: ../source/guides/writing-pyproject-toml.rst:15 +msgid "" +"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 "" +"A tabela ``[project]`` é o formato que a maioria dos backends de construção " +"usa para especificar os metadados básicos do seu projeto, como as " +"dependências, seu nome, etc." + +#: ../source/guides/writing-pyproject-toml.rst:18 +msgid "" +"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 "" +"A tabela ``[tool]`` possui subtabelas específicas da ferramenta, por " +"exemplo, ``[tool.hatch]``, ``[tool.black]``, ``[tool.mypy]``. Tocamos aqui " +"apenas nesta tabela porque seu conteúdo é definido por cada ferramenta. " +"Consulte a documentação da ferramenta específica para saber o que ela pode " +"conter." + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +#, fuzzy +#| 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)." +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" +"No momento em que este artigo foi escrito (novembro de 2023), Poetry_ era um " +"backend de construção notável que não usava a tabela ``[project]`` (em vez " +"disso, ele usava a tabela ``[tool.poetry]``)." + +#: ../source/guides/writing-pyproject-toml.rst:38 +#, fuzzy +#| 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`." +msgid "" +"For new projects, 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 "" +"Além disso, o backend de construção do setuptools_ oferece suporte tanto à " +"tabela ``[project]``, quanto o formato antigo em ``setup.cfg`` ou " +"``setup.py``. Para novos projetos, é recomendado usar a tabela " +"``[project]``, e manter ``setup.py`` apenas se alguma configuração " +"programática for necessária (como construir extensões C), mas os formatos " +"``setup.cfg`` e ``setup.py`` ainda são válidos. Veja :ref:`setup-py-" +"deprecated`." + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "Declarando o backend de construção" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" +"A tabela ``[build-system]`` contém uma chave ``build-backend``, que " +"especifica o backend de construção a ser usado. Ele também contém uma chave " +"``requires``, que é uma lista de dependências necessárias para construir o " +"projeto -- normalmente é apenas o pacote backend de construção, mas também " +"pode conter dependências adicionais. Você também pode restringir as versões, " +"por exemplo, ``requires = [\"setuptools >= 61.0\"]``." + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" +"Normalmente, você apenas copiará o que a documentação do seu backend de " +"construção sugere (após :ref:`escolher seu backend de construção `). Aqui estão os valores para alguns backends de construção " +"comuns:" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "Metadados estáticos vs dinâmicos" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "O resto deste guia é dedicado à tabela ``[project]``." + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" +"Na maioria das vezes, você escreverá diretamente o valor de um campo " +"``[project]``. Por exemplo: ``requires-python = \">= 3.8\"``, ou ``version = " +"\"1.0\"``." + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" +"No entanto, em alguns casos, é útil permitir que o backend de construção " +"calcule os metadados para você. Por exemplo: muitos backend sde construção " +"podem ler a versão de um atributo ``__version__`` em seu código, uma tag Git " +"ou similar. Nesses casos, você deve marcar o campo como dinâmico usando, por " +"exemplo," + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" +"Quando um campo é dinâmico, é da responsabilidade do backend de construção " +"preenchê-lo. Consulte a documentação do seu backend de construção para saber " +"como ele faz." + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "Informações básicas" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "``name``" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" +"Coloque o nome do seu projeto em PyPI. Este campo é necessário e é o único " +"campo que não pode ser marcado como dinâmico." + +#: ../source/guides/writing-pyproject-toml.rst:103 +#, fuzzy +#| 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." +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" +"O nome do projeto deve consistir em letras ASCII, dígitos, sublinhado " +"\"``_``\", hífenes \"``-``\" e pontos \"``.``\". Não deve começar ou " +"terminar com um sublinhado, hífen ou ponto." + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" +"A comparação de nomes de projetos não diferencia maiúsculas de minúsculas e " +"trata sequências arbitrariamente longas de sublinhados, hífenes e/ou pontos " +"como iguais. Por exemplo, se você registrar um projeto chamado ``cool-" +"stuff``, os usuários poderão baixá-lo ou declarar uma dependência dele " +"usando qualquer uma das seguintes formas de escrever: ``Cool-Stuff``, " +"``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "Coloque a versão do seu projeto." + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" +"Alguns especificadores de versão mais complicados como ``2020.0.0a1`` (para " +"uma versão alfa) são possíveis; veja a :ref:`especificação ` para detalhes completos." + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" +"Este campo é necessário, embora muitas vezes seja marcado como dinâmico " +"usando" + +#: ../source/guides/writing-pyproject-toml.rst:135 +#, fuzzy +#| 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." +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" +"Isso permite usar casos como preencher a versão de um atributo " +"``__version__`` ou uma tag Git. Consulte :ref:`Single sourcing the version` " +"para obter mais detalhes." + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "Dependências e requisitos" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "``dependencies``/``optional-dependencies``" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "Se o seu projeto tiver dependências, liste-as assim:" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" +"Veja :ref:`Especificadores de dependências ` para a " +"sintaxe completa que você pode usar para restringir versões." + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" +"Você pode querer fazer algumas de suas dependências opcionais, se forem " +"necessárias apenas para um recurso específico do seu pacote. Nesse caso, " +"coloque-os em ``optional-dependencies``." + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" +"Cada uma das chaves define um \"extra de empacotamento\". No exemplo acima, " +"pode-se usar, por exemplo, ``pip install seu-projeto-de-nome[gui]`` para " +"instalar seu projeto com suporte GUI, adicionando a dependência PyQt5." + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "``requires-python``" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" +"Isso permite que você declare a versão mínima de Python que você suporta " +"[#requires-python-upper-bounds]_." + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "Criando scripts executáveis" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" +"Para instalar um comando como parte do seu pacote, declare-o na tabela " +"``[project.scripts]``." + +#: ../source/guides/writing-pyproject-toml.rst:207 +#, fuzzy +#| 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()``." +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" +"Neste exemplo, depois de instalar seu projeto, um comando ``spam-cli`` " +"estará disponível. Executar este comando fará o equivalente a ``from spam " +"import main_cli; main_cli()``." + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" +"No Windows, scripts empacotados desta forma precisam de um terminal, então " +"se você lançá-los de dentro de uma aplicação gráfica, eles vão fazer um pop " +"up de terminal. Para evitar que isso aconteça, use o ``[project.gui-" +"scripts]`` tabela em vez de ``[project.scripts]``." + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" +"Nesse caso, a inicialização do seu script a partir da linha de comando " +"devolve o controle imediatamente, deixando o script a ser executado em " +"segundo plano." + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" +"A diferença entre ``[project.scripts]`` e ``[project.gui-scripts]`` é apenas " +"relevante no Windows." + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "Sobre o seu projeto" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "``authors``/``maintainers``" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" +"Ambos os campos contêm listas de pessoas identificadas por um nome e/ou um " +"endereço de e-mail." + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "``description``" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" +"Esta deve ser uma descrição de uma linha do seu projeto, para mostrar como o " +"\"título\" da sua página do projeto no PyPI (`exemplo `_), e " +"outros lugares como listas de resultados de pesquisa (`exemplo `_)." + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "``readme``" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" +"Esta é uma descrição mais longa do seu projeto, para exibir em sua página do " +"projeto em PyPI. Tipicamente, seu projeto terá um arquivo ``README.md`` ou " +"``README.rst`` e você acabou de colocar seu nome de arquivo aqui." + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "O formato do README é detectado automaticamente a partir da extensão:" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "``README.md`` → `Markdown no estilo do GitHub `_," + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "``README.rst`` → reStructuredText `_ (sem extensões do Sphinx)." + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "Você também pode especificar o formato explicitamente assim:" + +#: ../source/guides/writing-pyproject-toml.rst:297 +#, fuzzy +#| msgid "``license``" +msgid "``license`` and ``license-files``" +msgstr "``license``" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +#, fuzzy +#| msgid "hatch" +msgid "hatchling" +msgstr "hatch" + +#: ../source/guides/writing-pyproject-toml.rst:313 +#, fuzzy +#| msgid "Setuptools" +msgid "setuptools" +msgstr "Setuptools" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +#, fuzzy +#| msgid "Build backends" +msgid "pdm-backend" +msgstr "Backends de construção" + +#: ../source/guides/writing-pyproject-toml.rst:316 +#, fuzzy +#| msgid "poetry" +msgid "poetry-core" +msgstr "poetry" + +#: ../source/guides/writing-pyproject-toml.rst:317 +#, fuzzy +#| msgid "build" +msgid "uv-build" +msgstr "construir" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "``license``" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +#, fuzzy +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" +"O argumento ``license`` é mais comumente usado para indicar diferenças de " +"licenças conhecidas ou para incluir sua própria licença exclusiva. Como " +"regra geral, é uma boa ideia usar uma licença padrão bem conhecida, tanto " +"para evitar confusão quanto porque algumas organizações evitam software cuja " +"licença não é aprovada." + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +#, fuzzy +#| msgid "``license``" +msgid "``license-files``" +msgstr "``license``" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "``keywords``" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" +"Isso ajudará a caixa de pesquisa do PyPI a sugerir o seu projeto quando as " +"pessoas procuram essas palavras-chave." + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "``classifiers``" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" +"Uma lista de classificadores do PyPI que se aplicam ao seu projeto. " +"Verifique a `lista completa de possibilidades `_." + +#: ../source/guides/writing-pyproject-toml.rst:436 +#, fuzzy +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" +"Embora a lista de classificadores seja frequentemente usada para declarar " +"quais versões do Python um projeto suporta, essas informações são usadas " +"apenas para pesquisar e navegar por projetos no PyPI, não para instalar " +"projetos. Para realmente restringir em quais versões do Python um projeto " +"pode ser instalado, use o argumento :ref:`python_requires`." + +#: ../source/guides/writing-pyproject-toml.rst:441 +#, fuzzy +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" +"Para evitar que um pacote seja enviado para PyPI, use o classificador " +"especial ``'Private :: Do Not Upload'``. PyPI sempre rejeitará pacotes com " +"classificadores começando com ``\"Private ::'``." + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "``urls``" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" +"Uma lista de URLs associadas ao seu projeto, exibida na barra lateral " +"esquerda da página do projeto PyPI." + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +#, fuzzy +#| 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\"``." +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" +"Note que se a chave contém espaços, ela precisa ser citada, por exemplo, " +"``Website = \"https://example.com\"``, mas ``\"Official Website\" = " +"\"https://example.com\"``." + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "Plugins avançados" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" +"Alguns pacotes podem ser estendidos através de plugins. Exemplos incluem " +"Pytest_ e Pygments_. Para criar tal plugin, você precisa declará-lo em uma " +"subtabela de ``[project.entry-points]`` assim:" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "Veja o :ref:`guia Plugin ` para mais informações." + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "Um exemplo completo" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" +"Pense duas vezes antes de aplicar um limite superior como ``requires-python " +"= \"<= 3.10\"`` aqui. `Este post de blog `_ " +"contém algumas informações sobre possíveis problemas." + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" +"O Guia de Usuário para Empacotamento de Python (PyPUG) é uma coleção de " +"tutoriais e guias para empacotar software Python." + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "python, packaging, guide, tutorial, empacotamento, guia" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "Guia de Usuário para Empacotamento de Python" + +#: ../source/index.rst:25 +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." +msgstr "" +"Seja bem-vindo(a) ao *Guia de Usuário para Empacotamento de Python*, uma " +"coleção de tutoriais e referências para lhe ajudar a distribuir e instalar " +"pacotes Python com ferramentas modernas." + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" +"Este guia é mantido no `GitHub`_ pela :doc:`Python Packaging Authority " +"`. Aceitamos :doc:`contribuição e feedback `. 😊" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "Visão geral e fluxo" + +#: ../source/index.rst:40 +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." +msgstr "" +"Construir sua compreensão de empacotamento do Python é uma jornada. " +"Paciência e aprimoramento contínua são fundamentais para o sucesso. As " +"seções de visão geral e fluxo fornecem um ponto de partida para entender o " +"ecossistema de empacotamentos do Python." + +#: ../source/index.rst:44 +msgid "" +"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 "" +"A :doc:`overview` explica empacotamento do Python e seu uso ao preparar e " +"distribuir projetos. Esta seção ajuda você a construir compreensão sobre a " +"seleção das ferramentas e processos que são mais adequados para o seu caso " +"de uso. Inclui o que é o empacotamento, os problemas que resolve e as " +"principais considerações." + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" +"Para obter uma visão geral do fluxo de trabalho usado para publicar seu " +"código, consulte :doc:`fluxo de empacotamento `." + +#: ../source/index.rst:57 +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:" +msgstr "" +"Os tutoriais passam pelas etapas necessárias para completar um projeto pela " +"primeira vez. Os tutoriais visam ajudá-lo a ter sucesso e fornecer um ponto " +"de partida para a exploração futura. A seção :doc:`tutorials/index` inclui:" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" +"Um :doc:`tutorial sobre como instalar pacotes `" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" +"Um :doc:`tutorial sobre como gerenciar dependências de aplicações ` em um projeto com controle de versão" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" +"Um :doc:`tutorial sobre como empacotar e distribuir ` seu projeto" + +#: ../source/index.rst:71 +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." +msgstr "" +"Guias fornecem etapas para executar uma tarefa específica. Guias são mais " +"focados em usuários que já estão familiarizados com a empacotamento do " +"Python e estão procurando informações específicas." + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" +"A seção :doc:`guides/index` fornece instruções de \"como fazer\" em três " +"áreas principais: instalação de pacotes; construção e distribuição de " +"pacotes; diversos tópicos." + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "Explicações e discussões" + +#: ../source/index.rst:82 +#, fuzzy +#| msgid "" +#| "The :doc:`discussions/index` section for in-depth explanations and " +#| "discussion about topics, such as:" +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" +"A seção :doc:`discussions/index` para explicações aprofundadas e discussão " +"sobre temas, tais como:" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr ":doc:`discussions/deploying-python-applications`" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr ":doc:`discussions/pip-vs-easy-install`" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "Referência" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" +"A seção :doc:`specifications/index` para especificações de " +"interoperabilidade de empacotamento." + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" +"A lista de :doc:`outros projetos ` mantidos por membros da " +"Python Packaging Authority." + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" +"O :doc:`glossary` para definições de termos usados em empacotamento do " +"Python." + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "Resumos de projetos" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" +"Resumos e links para os projetos mais relevantes no espaço de instalação e " +"empacotamento do Python." + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "Projetos do PyPA" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "bandersnatch" + +#: ../source/key_projects.rst:21 +#, fuzzy +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Issues `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:26 +#, fuzzy +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`` é um cliente de espelhamento do PyPI projetado para criar " +"de forma eficiente um espelho completo do conteúdo do PyPI. Assim, as " +"organizações economizam largura de banda e latência nos downloads de pacotes " +"(especialmente no contexto de testes automatizados) e evitam o carregamento " +"excessivo da Content Delivery Network (CDN) do PyPI." + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "construir" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +":any:`Documentação ` | `Issues `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" +"``build`` é um construtor de pacotes Python compatível com a :pep:`517`. Ele " +"fornece uma CLI para construir pacotes, bem como uma API Python." + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "cibuildwheel" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" +"`Documentação `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussões `__ | `Discord " +"#cibuildwheel `__" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" +"``cibuildwheel`` é um pacote Python que constrói :term:`wheels ` para " +"todas as plataformas comuns e versões Python na maioria dos sistemas CI. " +"Veja também :ref:`multibuild`." + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "distlib" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +":doc:`Documentação ` | `Issues `__ | `GitHub `__ | `PyPI " +"`__" + +#: ../source/key_projects.rst:73 +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." +msgstr "" +"``distlib`` é uma biblioteca que implementa funções de baixo nível " +"relacionadas ao empacotamento e distribuição de software Python. ``distlib`` " +"implementa várias PEPs relevantes (padrões de proposta de aprimoramento do " +"Python) e é útil para desenvolvedores de ferramentas de empacotamento de " +"terceiros para fazer e enviar :term:`distribuições ` " +"binária e fonte, alcançar interoperabilidade, resolver dependências, " +"gerenciar recursos de pacote e executar outras funções semelhantes." + +#: ../source/key_projects.rst:82 +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." +msgstr "" +"Ao contrário do projeto :ref:`packaging` mais estrito (abaixo), que " +"implementa especificamente padrões modernos de interoperabilidade de pacotes " +"Python, ``distlib`` também tenta fornecer comportamentos de fallback " +"razoáveis quando solicitados a lidar com pacotes legados e metadados " +"anteriores à interoperabilidade moderna padrões e se enquadram no " +"subconjunto de pacotes que são incompatíveis com esses padrões." + +#: ../source/key_projects.rst:93 +msgid "distutils" +msgstr "distutils" + +#: ../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 "" +"O sistema de empacotamento original do Python, adicionado à biblioteca " +"padrão no Python 2.0 e removido no 3.12." + +#: ../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 "" +"Devido aos desafios de manter um sistema de empacotamento onde as " +"atualizações de recursos estão fortemente acopladas às atualizações de tempo " +"de execução da linguagem, o uso direto de :ref:`distutils` foi ativamente " +"desencorajado, com :ref:`Setuptools` sendo o substituto " +"preferido. :ref:`Setuptools` não apenas fornece recursos que " +"o :ref:`distutils` simples não oferece (como declarações de dependência e " +"declarações de ponto de entrada), ele também fornece uma interface de " +"construção consistente e conjunto de recursos em todas as versões Python " +"suportadas ." + +#: ../source/key_projects.rst: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 "" +"Consequentemente, :ref:`distutils` foi descontinuado no Python 3.10 " +"por :pep:`632` e foi :doc:`removido ` da biblioteca " +"padrão em Python 3.12. Setuptools inclui a cópia autônoma de distutils, e é " +"injetado mesmo no Python < 3.12 se você importar setuptools primeiro ou usar " +"pip." + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "flit" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" +"`Documentação `__ | `Issues `__ | `PyPI `__" + +#: ../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 "" +"O Flit fornece uma maneira simples de criar e enviar pacotes e módulos puro " +"Python para o PyPI. Ele se concentra em `facilitar as coisas fáceis `_ para empacotar. O Flit pode gerar um arquivo de configuração " +"para configurar rapidamente um projeto simples, construir distribuições " +"fonte e wheels e enviá-los para PyPI." + +#: ../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 usa ``pyproject.toml`` para configurar um projeto. O Flit não depende " +"de ferramentas como :ref:`setuptools` para construir distribuições, " +"ou :ref:`twine` para enviá-las ao PyPI. O Flit requer Python 3, mas você " +"pode usá-lo para distribuir módulos para Python 2, desde que eles possam ser " +"importados no Python 3." + +#: ../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 "" +"O pacote flit é levantado por `Matthias Bussonnier `__ desde outubro de 2023 na `plataforma do tidelift `__, e os fundos enviados para o PSF e " +"destinados ao uso da PyPA." + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "hatch" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Documentação `__ | `GitHub `__ | `PyPI `__" + +#: ../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 é uma ferramenta de linha de comando unificada destinada para, de " +"forma conveniente, gerenciar dependências e isolamento de ambiente para " +"desenvolvedores Python. Os desenvolvedores de pacotes Python usam o Hatch e " +"seu :term:`backend de construção ` Hatchling para configurar, " +"criar versões, especificar dependências e publicar pacotes no PyPI. Seu " +"sistema de plugins permite estender facilmente a funcionalidade." + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "empacotamento" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +":doc:`Documentação ` | `Issues `__ | `GitHub `__ | " +"`PyPI `__" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" +"Utilitários básicos para o empacotamento do Python usado por :ref:`pip` " +"e :ref:`setuptools`." + +#: ../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 "" +"Os utilitários principais na biblioteca de empacotamento lidam com " +"manipulação de versão, especificadores, marcadores, requisitos, tags e " +"atributos e tarefas semelhantes para pacotes Python. A maioria dos usuários " +"Python confia nesta biblioteca sem precisar chamá-la explicitamente; os " +"desenvolvedores de outras ferramentas de empacotamento, distribuição e " +"instalação Python listadas aqui geralmente usam sua funcionalidade para " +"analisar, descobrir e, de outra forma, lidar com atributos de dependência." + +#: ../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 "" +"Este projeto foca especificamente na implementação dos padrões modernos de " +"interoperabilidade de pacotes Python definidos em :ref:`packaging-" +"specifications`, e irá relatar erros para pacotes legados suficientemente " +"antigos que são incompatíveis com esses padrões. Em contraste, o " +"projeto :ref:`distlib` é uma biblioteca mais permissiva que tenta fornecer " +"uma leitura plausível de metadados ambíguos em casos onde :ref:`packaging` " +"irá relatar um erro." + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "pip" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Documentação `__ | `Issues `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" +"A ferramenta mais popular para instalação de pacotes Python e incluída nas " +"versões modernas do Python." + +#: ../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 "" +"Ele fornece os recursos básicos essenciais para localizar, baixar e instalar " +"pacotes do PyPI e outros índices de pacotes do Python e pode ser incorporado " +"em uma ampla gama de fluxos de trabalho de desenvolvimento por meio de sua " +"interface de linha de comando (CLI)." + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "Pipenv" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +msgstr "" +":doc:`Documentação ` | `Código-fonte `__ | `Issues `__ | `PyPI " +"`__" + +#: ../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 é um projeto que visa trazer o melhor de todos os mundos de " +"empacotamento para o mundo Python. Ele agrega :ref:`Pipfile`, :ref:`pip` " +"e :ref:`virtualenv` em um único conjunto de ferramentas. Ele pode " +"autoimportar ``requirements.txt`` e também pode verificar por CVEs no " +"`Pipfile`_ usando `safety `_." + +#: ../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 "" +"O Pipenv visa ajudar os usuários a gerenciar ambientes, dependências e " +"pacotes importados na linha de comando. Ele também funciona bem no Windows " +"(que outras ferramentas muitas vezes não atendem), cria e verifica hashes de " +"arquivo, para garantir a conformidade com especificadores de dependência " +"bloqueados por hash e facilita a desinstalação de pacotes e dependências." + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "Pipfile" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "`Código-fonte `__" + +#: ../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` e sua irmã :file:`Pipfile.lock` são uma alternativa centrada " +"na aplicação de nível superior ao arquivo de baixo " +"nível :file:`requirements.txt` do :ref:`pip`." + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "pipx" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" +"`Documentação `__ | `GitHub `__ | `PyPI `__" + +#: ../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 é uma ferramenta para instalar e executar aplicações de linha de " +"comando Python sem causar conflitos de dependência com outros pacotes " +"instalados no sistema." + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" +":doc:`Documentação ` | `Issues `__ | `GitHub `__" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "Este guia!" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "readme_renderer" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" +"`GitHub e documentação `__ | `PyPI " +"`__" + +#: ../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`` é uma biblioteca que os desenvolvedores de pacote usam " +"para renderizar seus arquivos de documentação de usuário (README) no HTML a " +"partir de linguagens de marcação como Markdown ou reStructuredText. Os " +"desenvolvedores o chamam por conta própria ou via :ref:`twine`, como parte " +"de seu processo de gerenciamento de lançamento, para verificar se as " +"descrições de seus pacotes serão exibidas corretamente no PyPI." + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "Setuptools" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Documentação `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" +"Setuptools (que inclui ``easy_install``) é uma coleção de melhorias para o " +"distutils do Python que permite a você construir e distribuir mais " +"facilmente :term:`distribuições ` Python, " +"especialmente aquelas que possuem dependências de outros pacotes." + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "trove-classifiers" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" + +#: ../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 é a fonte canônica para `classificadores no PyPI `_, que os mantenedores de projetos usam " +"para :ref:`descrever sistematicamente seus projetos ` para que os usuários possam encontrar melhor os projetos que " +"correspondem às suas necessidades no PyPI." + +#: ../source/key_projects.rst: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 "" +"O pacote trove-classifiers contém uma lista de classificadores válidos e " +"classificadores descontinuados (que são pareados com os classificadores que " +"os substituem). Use este pacote para validar classificadores usados em " +"pacotes destinados ao envio para o PyPI. Como esta lista de classificadores " +"é publicada como código, você pode instalá-la e importá-la, proporcionando " +"um fluxo de trabalho mais conveniente em comparação com a referência à " +"`lista publicada em PyPI `_. O `rastreador de " +"problemas `_ para o " +"projeto hospeda discussões sobre classificadores propostos e solicitações de " +"novos classificadores." + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "twine" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Documentação `__ | `Issues " +"`__ | `GitHub `__ | `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 é a principal ferramenta que os desenvolvedores usam para enviar " +"pacotes para o índice de pacotes Python ou outros Python Package Index. É um " +"programa de linha de comando que passa arquivos de programa e metadados para " +"uma API web. Os desenvolvedores o usam porque é a ferramenta oficial de " +"envio do PyPI, é rápida e segura, é mantida e funciona de forma confiável." + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "virtualenv" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Documentação `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" + +#: ../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 é uma ferramenta para criar :term:`Ambientes Virtuais ` isolados do Python, de forma similar ao :ref:`venv`. Ao " +"contrário de :ref:`venv`, virtualenv pode criar ambientes virtuais para " +"outras versões de Python, que ele localiza usando a variável ambiente PATH. " +"Ele também fornece recursos convenientes para configurar, manter, duplicar e " +"solucionar ambientes virtuais. Para obter mais informações, consulte a " +"seção :ref:`Creating and using Virtual Environments`." + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "Warehouse" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" +"`Documentação `__ | `Issues `__ | `GitHub `__" + +#: ../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 "" +"A base de código atual que alimenta o :term:`Python Package Index (PyPI)`. " +"Está hospedado em `pypi.org `_. A fonte padrão para " +"downloads do :ref:`pip`." + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "wheel" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Documentação `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" + +#: ../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 "" +"Primeiramente, o projeto wheel oferece a extensão ``bdist_wheel`` " +"do :ref:`setuptools` para criar :term:`distribuições wheel `. Além " +"disso, oferece seu próprio utilitário de linha de comando para criar e " +"instalar wheels." + +#: ../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 "" +"Veja também `auditwheel `__, uma " +"ferramenta que os desenvolvedores de pacotes usam para verificar e corrigir " +"pacotes Python que eles estão fazendo no formato de roda binária. Ele " +"fornece funcionalidade para descobrir dependências, verificar a conformidade " +"dos metadados e corrigir wheel e os metadados para vincular e incluir " +"bibliotecas externas compartilhadas em um pacote." + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "Projetos não-PyPA" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "buildout" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" +"`Documentação `__ | `Issues `__ | `PyPI `__ | `GitHub `__" + +#: ../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 "" +"Buildout é um sistema de construção baseado em Python para criar, montar e " +"distribuir aplicações de várias partes, algumas das quais podem ser não " +"baseadas em Python. Ele permite que você crie uma configuração de buildout e " +"reproduza o mesmo software posteriormente." + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "conda" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr ":doc:`Documentação `" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +#, fuzzy +#| 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." +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" +"Conda é uma ferramenta completamente separada de :ref:`pip`, virtualenv e " +"wheel, mas fornece muitos de seus recursos combinados em termos de " +"gerenciamento de pacotes, gerenciamento de ambiente virtual e implantação de " +"extensões binárias." + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +#, fuzzy +#| 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." +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" +"O Conda não instala pacotes do PyPI e pode instalar apenas a partir dos " +"repositórios oficiais do Anaconda, ou anaconda.org (um local para pacotes " +"*conda* contribuídos pelo usuário), ou um servidor de pacotes local (por " +"exemplo, intranet). No entanto, observe que :ref:`pip` pode ser instalado e " +"trabalhar lado a lado com o conda para gerenciar :term:`distribuições " +"` do PyPI. Além disso, `conda skeleton `__ é uma ferramenta para fazer pacotes Python instaláveis " +"pelo conda primeiro obtendo-os em PyPI e modificando seus metadados." + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "devpi" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" +"`Documentação `__ | :gh:`Issues ` | `PyPI `__" + +#: ../source/key_projects.rst:441 +#, fuzzy +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." +msgstr "" +"devpi apresenta um poderoso servidor compatível com PyPI e cache de proxy " +"PyPI com uma ferramenta de linha de comando complementar para conduzir " +"atividades de empacotamento, teste e lançamento com Python. devpi também " +"fornece uma interface web navegável e pesquisável." + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +#, fuzzy +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" +"`GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "enscons" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" +":gh:`Código-fonte ` | :gh:`Issues ` | " +"`PyPI `__" + +#: ../source/key_projects.rst:470 +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 é uma ferramenta de empacotamento Python baseada em `SCons`_. Ele " +"cria distribuições de código-fonte compatíveis com :ref:`pip` e wheels sem " +"usar distutils ou setuptools, incluindo distribuições com extensões C. " +"Enscons tem uma arquitetura e filosofia diferente de :ref:`distutils`. Em " +"vez de adicionar recursos de compilação a um sistema de empacotamento " +"Python, enscons adiciona empacotamento Python a um sistema de construção de " +"propósito geral. Enscons ajuda você a construir sdists que podem ser " +"construídos automaticamente por :ref:`pip`, e wheels que são independentes " +"de enscons." + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +#, fuzzy +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" +"`Documentação `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "Hashdist" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" +"`Documentação `__ | `GitHub " +"`__" + +#: ../source/key_projects.rst:504 +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 é uma biblioteca para construir distribuições de software que não " +"dependem do root. Hashdist está tentando ser \"o preferido do Debian para os " +"casos em que a tecnologia Debian não funciona\". A melhor maneira para " +"Pythonistas pensarem sobre Hashdist pode ser um híbrido mais poderoso " +"de :ref:`virtualenv` e :ref:`buildout`. Ele tem como objetivo resolver o " +"problema de instalação de software científico e tornar a distribuição de " +"pacotes sem estado, com cache e com capacidade de distribuição. É usado por " +"alguns pesquisadores, mas não tem manutenção desde 2016." + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "Maturin" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" +"`Documentação `__ | `GitHub `__" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" +"Maturin é um backend de construção para módulos de extensão Rust, também " +"escrito em Rust. Ele oferece suporte à construção de rodas para python 3.7+ " +"em Windows, Linux, macOS e FreeBSD, pode enviá-las para PyPI e tem suporte " +"básico a PyPy e GraalPy." + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "meson-python" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" +"`Documentação `__ | `GitHub " +"`__" + +#: ../source/key_projects.rst:534 +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`` é um backend de compilação que usa o sistema de compilação " +"Meson_. Ele permite que os autores de pacotes Python usem o Meson_ como o " +"sistema de compilação para seus pacotes. Ele oferece suporte a uma ampla " +"variedade de linguagens, incluindo C, e é capaz de atender às necessidades " +"das configurações de compilação mais complexas." + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "multibuild" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "`GitHub `__" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" +"Multibuild é um conjunto de scripts de CI para construir e testar " +"Python :term:`wheels ` para Linux, macOS e (menos flexível) Windows. " +"Veja também :ref:`cibuildwheel`." + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "pdm" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Documentação `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" +"PDM é um gerenciador de pacotes Python moderno. Ele também " +"usa :term:`pyproject.toml` para armazenar metadados do projeto conforme " +"definido em :pep:`621`." + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Documentação `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "pip-tools" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Documentação `__ | `GitHub " +"`__ | `PyPI `__" + +#: ../source/key_projects.rst:600 +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." +msgstr "" +"pip-tools é um conjunto de ferramentas destinadas aos administradores de " +"sistema Python e gerentes de lançamento que desejam manter suas compilações " +"determinísticas e, ao mesmo tempo, manter-se atualizado com as novas versões " +"de suas dependências. Os usuários podem especificar a liberação particular " +"de suas dependências por meio de hash, fazer convenientemente uma lista " +"devidamente formatada de requisitos de informações em outras partes de seu " +"programa, atualizar todas as dependências (um recurso :ref:`pip` atualmente " +"não fornece) e criar camadas de restrições para o programa obedecer." + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +#, fuzzy +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +"`GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "piwheels" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" +"`Site `__ | :doc:`Documentação ` " +"| `GitHub `__" + +#: ../source/key_projects.rst:629 +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 "" +"piwheels é um site, e o software que o sustenta, que busca pacotes de " +"distribuição de código-fonte do PyPI e os compila em wheels binários que são " +"otimizadas para instalação em computadores Raspberry Pi. O Raspberry Pi OS " +"pré-configura pip para usar piwheels.org como um índice adicional para PyPI." + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "poetry" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Documentação `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:644 +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." +msgstr "" +"poetry é uma ferramenta de linha de comando para lidar com a instalação de " +"dependências e isolamento, bem como construção e empacotamento de pacotes " +"Python. Ele usa ``pyproject.toml`` e, ao invés de depender da funcionalidade " +"do resolvedor no :ref:`pip`, fornece seu próprio resolvedor de dependências. " +"Ele tenta acelerar a experiência dos usuários de instalação e resolução de " +"dependências, armazenando localmente em cache os metadados sobre as " +"dependências." + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +#, fuzzy +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +"`GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +#, fuzzy +msgid "Pulp-python" +msgstr "python" + +#: ../source/key_projects.rst:667 +#, fuzzy +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" +"`Documentação `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +#, fuzzy +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" +"`Documentação `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +#, fuzzy +msgid "pypiprivate" +msgstr "pypiserver" + +#: ../source/key_projects.rst:697 +#, fuzzy +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +"`GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "pypiserver" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" +"`GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:711 +#, fuzzy +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." +msgstr "" +"pypiserver é uma aplicação minimalista que serve como um índice de pacotes " +"privado Python dentro das organizações, implementando uma API simples e uma " +"interface de navegador. Você pode enviar pacotes privados usando ferramentas " +"de envio padrão, e os usuários podem baixar e instalá-los com :ref:`pip`, " +"sem publicá-los publicamente. As organizações que usam o pypiserver " +"geralmente baixam pacotes tanto do pypiserver quanto do PyPI." + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "PyScaffold" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Documentação `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:728 +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 é um gerador de projeto para inicialização de pacotes Python, " +"pronto para ser compartilhado no PyPI e instalável via :ref:`pip`. Ele se " +"baseia em um conjunto de configurações padrão sãs para ferramentas " +"estabelecidas (como o :ref:`setuptools`, pytest_ e Sphinx_) para fornecer um " +"ambiente produtivo para que os desenvolvedores possam começar a codificar " +"imediatamente. PyScaffold também pode ser usado com projetos existentes para " +"tornar o empacotamento mais fácil." + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +#, fuzzy +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +"`GitHub e documentação `__ | `PyPI `__" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "scikit-build" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Documentação `__ | `GitHub " +"`__ | `PyPI `__" + +#: ../source/key_projects.rst:758 +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 é um wrapper do :ref:`setuptools` para CPython que constrói " +"extensões C/C++/Fortran/Cython. Ele usa `cmake `__ (disponível em PyPI) para fornecer melhor suporte para " +"compiladores adicionais, sistemas de construção, compilação cruzada e " +"localização de dependências e seus requisitos de compilação associados. Para " +"acelerar e paralelizar a construção de grandes projetos, o usuário pode " +"instalar `ninja `__ (também disponível em " +"PyPI)." + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "scikit-build-core" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" +"`Documentação `__ | " +"`GitHub `__ | `PyPI " +"`__" + +#: ../source/key_projects.rst:775 +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." +msgstr "" +"Scikit-build-core é um back-end de construção para extensões CPython C/C++/" +"Fortran/Cython. Ele permite que os usuários escrevam extensões com `cmake " +"`__ (disponível no PyPI) para fornecer " +"melhor suporte para compiladores adicionais, sistemas de construção, " +"compilação cruzada e localização de dependências e suas construções " +"associadas requisitos. CMake/Ninja são baixados automaticamente do PyPI se " +"não estiverem disponíveis no sistema." + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "shiv" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Documentação `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:791 +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." +msgstr "" +"shiv é um utilitário de linha de comando para construir *zipapps* Python " +"totalmente autocontidos conforme descrito na :pep:`441`, mas com todas as " +"suas dependências incluídas. Seu objetivo principal é tornar a distribuição " +"Python de aplicações e ferramentas de linha de comando rápida e fácil." + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +#, fuzzy +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +"`GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" +":doc:`Documentação ` | `GitHub `__ | `Artigo `__ | `Slides `__" + +#: ../source/key_projects.rst:819 +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 "" +"Um gerenciador de pacotes flexível projetado para oferecer suporte a várias " +"versões, configurações, plataformas e compiladores. O Spack é como o " +"Homebrew, mas os pacotes são escritos em Python e parametrizados para " +"permitir fácil troca de compiladores, versões de bibliotecas, opções de " +"construção, etc. Arbitrariamente, muitas versões de pacotes podem coexistir " +"no mesmo sistema. O Spack foi projetado para construir rapidamente " +"aplicações científicas de alto desempenho em clusters e supercomputadores." + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" +"O Spack não está no PyPI (ainda), mas não requer instalação e pode ser usado " +"imediatamente após a clonagem do GitHub." + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "zest.releaser" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Documentação `__ | `GitHub " +"`__ | `PyPI `__" + +#: ../source/key_projects.rst:839 +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." +msgstr "" +"``zest.releaser`` é uma ferramenta de lançamento de pacote Python que " +"fornece uma camada de abstração sobre :ref:`twine`. Os desenvolvedores " +"Python usam ``zest.releaser`` para automatizar o incremento de números de " +"versão de pacote, atualizando changelogs, marcando lançamentos no controle " +"de fontes e enviando novos pacotes para PyPI." + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "Projetos de biblioteca padrão" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "ensurepip" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" +"`Documentação `__ | " +"`Issues `__" + +#: ../source/key_projects.rst:856 +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." +msgstr "" +"Um pacote na Biblioteca Padrão do Python que fornece suporte para preparar " +"o :ref:`pip` em uma instalação existente do Python ou em ambiente virtual. " +"Na maioria dos casos, os usuários finais não usarão este módulo, mas em vez " +"disso, ele será usado durante a construção da distribuição Python." + +#: ../source/key_projects.rst:864 +#, fuzzy +msgid "http.server" +msgstr "pypiserver" + +#: ../source/key_projects.rst:866 +#, fuzzy +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" +"`Documentação `__ | " +"`Issues `__" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "venv" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" +"`Documentação `__ | " +"`Issues `__" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" +"Um pacote na Biblioteca Padrão do Python (começando com Python 3.3) para " +"criar :term:`Ambientes Virtuais `. Para obter mais " +"informações, consulte a seção :ref:`Creating and using Virtual Environments`." + +#: ../source/news.rst:2 +msgid "News" +msgstr "Notícias" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" +"Este documento não está atualizado. Anteriormente, o documento realçava as " +"mudanças no empacotamento do Python." + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "Setembro de 2019" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" +"Adicionado um guia sobre como publicar dists por meio do GitHub Actions. " +"(:pr:`647`)" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "Agosto de 2019" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "Atualizado para usar :file:`python3 -m` ao instalar pipx. (:pr:`631`)" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "Julho de 2019" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "Todos os números PEP marcados com função :pep: . (:pr:`629`)" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" +"Atualizada a versão do Sphinx e removido intersphinx para pypa.io. " +"(:pr:`625`)" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "Mencionado :file:`find_namespace_packages`. (:pr:`622`)" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" +"Atualizados os exemplos de layout de diretório para consistência. (:pr:`611`)" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "Atualizado o link do Bandersnatch para GitHub. (:pr:`623`)" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "Junho de 2019" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "Corrigidos de alguns erros de escrita. (:pr:`620`)" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "Maio de 2019" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" +"Adicionado o uso de :file:`python_requires` ao tutorial de empacotamento. " +"(:pr:`613`)" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "Adicionada uma página de guia sobre MANIFEST.in. (:pr:`609`)" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "Abril de 2019" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" +"Adicionada uma menção para :file:`shiv` na seção de projetos-chave. " +"(:pr:`608`)" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "Reduzida a ênfase em virtualenv. (:pr:`606`)" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "Março de 2019" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" +"Movida a opção de versão do guia de única fonte para Python 3. (:pr:`605`)" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "Cobertos detalhes de RTD para contribuição. (:pr:`600`)" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "Fevereiro de 2019" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" +"Explicada as diferenças entre o tutorial e o processo de empacotamento real. " +"(:pr:`602`)" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" +"Adicionadas as instruções para instalar aplicações CLI do Python. (:pr:`594`)" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "Janeiro de 2019" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "Adicionado :file:`--no-deps` ao tutorial de empacotamento. (:pr:`593`)" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "Atualizado Sphinx e Nox. (:pr:`591`)" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "Referenciado o Twine do Python3. (:pr:`581`)" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "Dezembro de 2018" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "Sem programadores no escritório!" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "Novembro de 2018" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" +"Removido o link da página de destino para o guia de migração do PyPI. " +"(:pr:`575`)" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "Alterado bumpversion para bump2version. (:pr:`572`)" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "Adicionado exemplo de versão de pacote de única fonte. (:pr:`573`)" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "Adicionado um guia para a criação de documentação. (:pr:`568`)" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "Outubro de 2018" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "Atualizado o nome do pacote Nox. (:pr:`566`)" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "Mencionadas extensões Sphinx nos guias. (:pr:`562`)" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "Setembro de 2018" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "Adicionada uma seção sobre como verificar a marcação RST. (:pr:`554`)" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "Atualizada página de instalações do usuário. (:pr:`558`)" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "Atualizadas as URLs do Google BigQuery. (:pr:`556`)" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "Substituído o comando tar pelo comando de trabalho. (:pr:`552`)" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" +"Alterado para aspas duplas no pip install SomeProject==1.4. (:pr:`550`)" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "Agosto de 2018" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" +"Removida a recomendação de armazenar senhas em texto não criptografado. " +"(:pr:`546`)" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" +"Movida a Visão geral para um ponto baseado em tarefas junto com os outros. " +"(:pr:`540`)" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "Atualizada a versão do Python compatível com virtualenv. (:pr:`538`)" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "Adicionado esboço/rascunho da nova página de Visão geral. (:pr:`519`)" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "Julho de 2018" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "Melhorada a documentação de extensão binária. (:pr:`531`)" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "Adicionado o scikit-build aos principais projetos. (:pr:`530`)" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "Junho de 2018" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" +"Corrigidas as categorias de interoperabilidade de PEP para pypa.io. " +"(:pr:`527`)" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "Atualizada a explicação das descrições de Markdown. (:pr:`522`)" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "Maio de 2018" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" +"Adicionadas notas sobre problemas com Provides-Dist e Obsoletes-Dist. " +"(:pr:`513`)" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" +"Removido o aviso de desatualizado sobre a mistura da versão Python com o " +"Pipenv. (:pr:`501`)" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "Simplificado o tutorial de empacotamento. (:pr:`498`)" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" +"Atualizadas as instruções do usuário Windows para maior clareza. (:pr:`493`)" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" +"Atualizada a descrição da seção da licença para integridade. (:pr:`492`)" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" +"Adicionado documento de estilo de especificação à seção de contribuição. " +"(:pr:`489`)" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "Adicionados tipos de documentação ao guia de contribuição. (:pr:`485`)" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "Abril de 2018" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "Adicionado guia de README. (:pr:`461`)" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" +"Atualizadas as instruções e status para o lançamento do PyPI. (:pr:`475`)" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "Adicionadas instruções para o Warehouse. (:pr:`471`)" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "Removidas referências de GPG do tutorial de publicação. (:pr:`466`)" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "Adicionado 'O que há em cada Python 3.4–3.6?'. (:pr:`468`)" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "Adicionado um guia para descontinuar as versões do Python. (:pr:`459`)" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "Tornada padrão a variante GFM do Description-Content-Type. (:pr:`462`)" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "Março de 2018" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "Atualizado \"instalando pacotes científicos\". (:pr:`455`)" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" +"Adicionado :file:`long_description_content_type` para seguir a PEP 556. " +"(:pr:`457`)" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" +"Esclarecido um classificador de descrição longa em pypi.org. (:pr:`456`)" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" +"Atualizada a especificação dos metadados principais para seguir a PEP 556. " +"(:pr:`412`)" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "Fevereiro de 2018" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" +"Adicionados python3-venv e python3-pip às instruções de instalação do " +"Debian. (:pr:`445`)" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "Informações de migração do PyPI atualizadas. (:pr:`439`)" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" +"Adicionado um aviso sobre o gerenciamento de várias versões com pipenv. " +"(:pr:`430`)" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" +"Adicionado exemplo de vários e-mails aos metadados principais. (:pr:`429`)" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" +"Adicionada explicação de \"legado\" em test.pypi.org/legacy. (:pr:`426`)" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "Janeiro de 2018" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" +"Adicionado um link para a lista de classificadores do PyPI. (:pr:`425`)" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "Atualizada uma explicação sobre README.rst. (:pr:`419`)" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "Dezembro de 2017" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" +"Substituído :file:`~` por :file:`$HOME` nos guias e tutoriais. (:pr:`418`)" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" +"Adicionada nota sobre quais campos podem ser usados com marcadores de " +"ambiente. (:pr:`416`)" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "Atualizada a seção Requires-Python. (:pr:`414`)" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "Adicionada página de notícias. (:pr:`404`)" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "Novembro de 2017" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" +"Introduzido um novo tutorial de gerenciamento de dependências baseado no " +"Pipenv. (:pr:`402`)" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" +"Atualizado o tutorial *Versão de pacote de fonte única* para refletir a " +"estratégia atual do pip. (:pr:`400`)" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" +"Adicionada documentação sobre o argumento ``py_modules`` ao ``setup``. " +"(:pr:`398`)" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "Simplificadas as palavras da seção :file:`manifest.in`. (:pr:`395`)" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "Outubro de 2017" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" +"Adicionada uma especificação para o arquivo :file:`entry_points.txt`. " +"(:pr:`398`)" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" +"Criado um novo guia para gerenciamento de pacotes usando ``pip`` e " +"``virtualenv``. (:pr:`385`)" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "Dividida a página de especificações em várias páginas. (:pr:`386`)" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "Setembro de 2017" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" +"Incentivado o uso de ``readme_renderer`` validar o :file:`README.rst`. " +"(:pr:`379`)" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "Recomendado o uso da opção ``--user-base``. (:pr:`374`)" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "Agosto de 2017" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" +"Adicionado um novo tutorial experimental sobre a instalação de pacotes " +"usando ``Pipenv``. (:pr:`369`)" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "Adicionado um novo guia sobre como usar o ``TestPyPI``. (:pr:`366`)" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "Adicionado :file:`pypi.org` como um termo. (:pr:`365`)" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "Julho de 2017" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "Adicionado ``flit`` à lista de projetos principais. (:pr:`358`)" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "Adicionado ``enscons`` à lista de projetos principais. (:pr:`357`)" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" +"Atualizado o ``readme`` deste guia com instruções sobre como construir o " +"guia localmente. (:pr:`356`)" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" +"Melhorada a visibilidade da nova URL do ``TestPyPI``, adicionando uma nota à " +"página inicial sobre pypi.org. (:pr:`354`)" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" +"Adicionada uma nota sobre a remoção da API de registro explícito. (:pr:`347`)" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "Junho de 2017" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" +"Adicionado um documento sobre a migração de envios para :file:`PyPI.org`. " +"(:pr:`339`)" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "Adicionada documentação para ``python_requires``. (:pr:`338`)" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" +"Adicionada uma nota sobre a migração do PyPI no tutorial *Recomendações de " +"ferramentas*. (:pr:`335`)" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" +"Adicionada uma nota de que o :file:`manifest.in` não afeta os wheels. " +"(:pr:`332`)" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "Adicionada uma seção de licença ao guia de distribuição. (:pr:`331`)" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "Expandida a seção sobre o argumento ``name``. (:pr:`329`)" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "Ajustada a página inicial. (:pr:`327`, :pr:`326`, :pr:`324`)" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "Atualizado para Sphinx 1.6.2. (:pr:`323`)" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "Trocado para o tema do PyPA. (:pr:`305`)" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "Reorganizada a documentação na nova estrutura. (:pr:`318`)" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "Maio de 2017" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" +"Adicionada documentação para o campo ``Description-Content-Type``. " +"(:pr:`258`)" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "Adicionado guia de contribuidor e de estilo. (:pr:`307`)" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" +"Documentadas as diferenças entre ``pip`` e ``easy_install`` para índices por " +"projeto. (:pr:`233`)" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "Abril de 2017" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" +"Adicionada configuração de travis para testar pull requests. (:pr:`300`)" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" +"Mencionado o requisito do pacote ``wheel`` para a criação de wheels " +"(:pr:`299`)" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" +"Removida a referência a ``twine register`` no tutorial *Distribuindo " +"pacotes*. (:pr:`271`)" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" +"Adicionado um tópico sobre descoberta de plugins. (:pr:`294`, :pr:`296`)" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "Adicionado um tópico sobre pacotes de espaço de nomes. (:pr:`290`)" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" +"Adicionada documentação explicando em destaque como instalar ``pip`` em ``/" +"usr/local``. (:pr:`230`)" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" +"Atualizada a documentação do modo de desenvolvimento para mencionar que a " +"ordem dos pacotes locais é importante. (:pr:`208`)" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" +"Conversão de link do readthedocs para sua migração ``.org`` -> ``.io`` para " +"projetos hospedados (:pr:`239`)" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" +"Trocada a ordem dos argumentos do :file:`setup.py` para o comando de envio, " +"pois a ordem é significativa. (:pr:`260`)" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" +"Explicado como instalar de fontes não suportadas usando uma aplicação " +"auxiliar. (:pr:`289`)" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "Março de 2017" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "Coberto ``manylinux1`` em *wheels de plataforma*. (:pr:`283`)" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "Fevereiro de 2017" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "Adicionada a :pep:`518`. (:pr:`281`)" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "Visão geral do empacotamento para Python" + +#: ../source/overview.rst:7 +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." +msgstr "" +"Como uma linguagem de programação de propósito geral, Python foi projetado " +"para ser usado de várias maneiras. Você pode construir sites ou robôs " +"industriais ou um jogo para seus amigos jogarem e muito mais, todos usando a " +"mesma tecnologia básica." + +#: ../source/overview.rst:12 +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." +msgstr "" +"A flexibilidade do Python é o porquê do primeiro passo em cada projeto " +"Python deva ser pensar sobre o público do projeto e o ambiente " +"correspondente onde o projeto será executado. Pode parecer estranho pensar " +"em empacotamento antes de escrever o código, mas esse processo faz " +"maravilhas para evitar dores de cabeça futuras." + +#: ../source/overview.rst:18 +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." +msgstr "" +"Esta visão geral fornece uma árvore de decisão de propósito geral para " +"raciocinar sobre a abundância de opções de empacotamento do Python. Continue " +"lendo para escolher a melhor tecnologia para seu próximo projeto." + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "Pensando sobre a implantação" + +#: ../source/overview.rst:25 +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:" +msgstr "" +"Os pacotes existem para serem instalados (ou *implantados*, *deployed*), " +"portanto, antes de empacotar qualquer coisa, você vai querer ter algumas " +"respostas para as perguntas de implantação abaixo:" + +#: ../source/overview.rst:29 +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?" +msgstr "" +"Quem são os usuários do seu software? Seu software será instalado por outros " +"desenvolvedores que fazem o desenvolvimento de software, pessoas de " +"operações em um datacenter ou um grupo com menos experiência em software?" + +#: ../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 "" +"O seu software deve ser executado em servidores, desktops, clientes móveis " +"(telefones, tablets, etc.) ou incorporado em dispositivos dedicados?" + +#: ../source/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" +"O seu software é instalado individualmente ou em grandes lotes de " +"implantação?" + +#: ../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 "" +"O empacotamento tem tudo a ver com o ambiente de destino e a experiência de " +"implantação. Existem muitas respostas para as perguntas acima e cada " +"combinação de circunstâncias tem suas próprias soluções. Com essas " +"informações, a visão geral a seguir o guiará para as tecnologias de " +"empacotamento mais adequadas ao seu projeto." + +#: ../source/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "Empacotando bibliotecas e ferramentas Python" + +#: ../source/overview.rst:45 +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`." +msgstr "" +"Você deve ter ouvido falar sobre PyPI, ``setup.py`` e arquivos ``wheel``. " +"Estas são apenas algumas das ferramentas que o ecossistema Python oferece " +"para distribuir código Python para desenvolvedores, sobre as quais você pode " +"ler em :doc:`guides/distributing-packages-using-setuptools`." + +#: ../source/overview.rst:50 +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`." +msgstr "" +"As abordagens a seguir para empacotamento são destinadas a bibliotecas e " +"ferramentas usadas pelo público técnico em um ambiente de desenvolvimento. " +"Se você está procurando maneiras de empacotar Python para um público não " +"técnico e/ou uma configuração de produção, pule para :ref:`packaging-" +"applications`." + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "Módulos Python" + +#: ../source/overview.rst:58 +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." +msgstr "" +"Um arquivo Python, desde que dependa apenas da biblioteca padrão, pode ser " +"redistribuído e reutilizado. Você também precisará garantir que ele foi " +"escrito para a versão correta do Python e depende apenas da biblioteca " +"padrão." + +#: ../source/overview.rst:63 +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 " +"`." +msgstr "" +"Isso é ótimo para compartilhar scripts e trechos simples entre pessoas que " +"possuem versões Python compatíveis (como via e-mail, StackOverflow ou gists " +"do GitHub). Existem até algumas bibliotecas Python inteiras que oferecem " +"isso como uma opção, como :doc:`bottle.py` e :doc:`boltons " +"`." + +#: ../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 "" +"No entanto, esse padrão não será escalonado para projetos que consistem em " +"vários arquivos, precisam de bibliotecas adicionais ou precisam de uma " +"versão específica do Python, daí as opções abaixo." + +#: ../source/overview.rst:75 +msgid "Python source distributions" +msgstr "Distribuições fonte Python" + +#: ../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 "" +"Se o seu código consiste em vários arquivos Python, ele geralmente é " +"organizado em uma estrutura de diretório. Qualquer diretório contendo " +"arquivos Python pode incluir um :term:`Pacote de Importação`." + +#: ../source/overview.rst:81 +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." +msgstr "" +"Como os pacotes consistem em vários arquivos, eles são mais difíceis de " +"distribuir. A maioria dos protocolos oferece suporte à transferência de " +"apenas um arquivo por vez (quando foi a última vez que você clicou em um " +"link e ele baixou vários arquivos?). É mais fácil obter transferências " +"incompletas e mais difícil garantir a integridade do código no destino." + +#: ../source/overview.rst:87 +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." +msgstr "" +"Contanto que seu código não contenha nada além de código puro Python, e você " +"saiba que seu ambiente de implantação oferece suporte a sua versão de " +"Python, então você pode usar as ferramentas de empacotamento nativas do " +"Python para criar um :term:`Pacote de Distribuição` fonte, ou *sdist*." + +#: ../source/overview.rst:92 +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." +msgstr "" +"Os *sdists* do Python são arquivos compactados (arquivos ``.tar.gz``) " +"contendo um ou mais pacotes ou módulos. Se seu código for puro Python e você " +"depender apenas de outros pacotes Python, você pode consultar a " +"especificação de :ref:`source-distribution-format` para saber mais." + +#: ../source/overview.rst:97 +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." +msgstr "" +"Se você confiar em qualquer código não-Python ou pacotes não-Python (como " +"`libxml2 `_ no caso de `lxml " +"`_, ou bibliotecas BLAS no caso de `numpy " +"`_), você precisará usar o formato detalhado " +"no a próxima seção, que também tem muitas vantagens para bibliotecas puro " +"Python." + +#: ../source/overview.rst:104 +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!" +msgstr "" +"Python e PyPI oferecem suporte a várias distribuições, fornecendo diferentes " +"implementações do mesmo pacote. Por exemplo, a `distribuição PIL `_ não mantida, mas inspiracional, fornece o pacote " +"PIL, e também o `Pillow `_, um fork do PIL!" + +#: ../source/overview.rst:111 +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``." +msgstr "" +"Este superpoder de empacotamento do Python torna possível que o Pillow seja " +"um substituto imediato para o PIL, apenas alterando o ``install_requires`` " +"ou ``requirements.txt`` do seu projeto." + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "Distribuições binárias Python" + +#: ../source/overview.rst:118 +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." +msgstr "" +"Grande parte do poder prático do Python vem de sua capacidade de integração " +"com o ecossistema de software, em particular bibliotecas escritas em C, C++, " +"Fortran, Rust e outras linguagens." + +#: ../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." +msgstr "" +"Nem todos os desenvolvedores têm as ferramentas ou experiências certas para " +"construir esses componentes escritos nessas linguagens compiladas, então " +"Python criou o :term:`Wheel`, um formato de pacote projetado para enviar " +"bibliotecas com artefatos compilados. Na verdade, o instalador do pacote " +"Python, ``pip``, sempre prefere wheels porque a instalação é sempre mais " +"rápida, então mesmo os pacotes puro Python funcionam melhor com wheels." + +#: ../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 "" +"As distribuições binárias são melhores quando vêm com distribuições de fonte " +"correspondentes. Mesmo que você não envie wheels do seu código para todos os " +"sistemas operacionais, ao enviar o sdist, você permite que usuários de " +"outras plataformas ainda o construam por conta própria. O padrão é publicar " +"arquivos sdist e wheel juntos, *a menos* que você esteja criando artefatos " +"para um caso de uso muito específico, onde sabe que o destinatário só " +"precisa de um ou de outro." + +#: ../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." +msgstr "" +"Python e PyPI facilitam o envio de wheels e sdists juntos. Basta seguir o " +"tutorial :doc:`tutorials/packaging-projects`." + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" +"Um resumo das capacidades de empacotamento do Python para ferramentas e " +"bibliotecas." + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" +"Bibliotecas embutidas recomendadas e tecnologias de empacotamento de " +"ferramentas do Python. Extraído de `The Packaging Gradient (2017) `_." + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "Empacotando aplicações do Python" + +#: ../source/overview.rst:154 +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." +msgstr "" +"Até agora, discutimos apenas as ferramentas de distribuição nativas do " +"Python. Com base em nossa introdução, você estaria correto em inferir que " +"essas abordagens embutidas têm como alvo apenas ambientes que possuem Python " +"e um público que sabe como instalar pacotes Python." + +#: ../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 "" +"Com a variedade de sistemas operacionais, configurações e pessoas por aí, " +"essa suposição só é segura quando se destina a um público de desenvolvedores." + +#: ../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 "" +"O empacotamento nativo do Python é construído principalmente para distribuir " +"código reutilizável, chamado de bibliotecas, entre os desenvolvedores. Você " +"pode adicionar **ferramentas** ou aplicações básicas para desenvolvedores ao " +"pacote de biblioteca do Python, usando tecnologias como :doc:`entry_points " +"do setuptools `." + +#: ../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." +msgstr "" +"Bibliotecas são blocos de construção, não aplicações completas. Para " +"distribuir aplicações, existe um novo mundo de tecnologias por aí." + +#: ../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 "" +"As próximas seções organizam essas opções de pacote de aplicações de acordo " +"com suas dependências no ambiente de destino, para que você possa escolher o " +"certo para o seu projeto." + +#: ../source/overview.rst:178 +msgid "Depending on a framework" +msgstr "Dependendo de um framework" + +#: ../source/overview.rst:180 +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." +msgstr "" +"Alguns tipos de aplicações Python, como backends de sites e outros serviços " +"de rede, são comuns o suficiente para que tenham estruturas para permitir " +"seu desenvolvimento e empacotamento. Outros tipos de aplicações, como " +"frontends web dinâmicos e clientes móveis, são complexos o suficiente para " +"fazer com que uma estrutura se torne mais do que uma conveniência." + +#: ../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." +msgstr "" +"Em todos esses casos, faz sentido trabalhar de trás para frente, a partir da " +"história de empacotamento e implantação da estrutura. Algumas estruturas " +"incluem um sistema de implantação que envolve as tecnologias descritas no " +"restante do guia. Nesses casos, você desejará consultar o guia de " +"empacotamento de sua estrutura para obter a experiência de produção mais " +"fácil e confiável." + +#: ../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." +msgstr "" +"Se você já se perguntou como essas plataformas e estruturas funcionam nos " +"bastidores, você sempre pode ler as seções seguintes." + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "Plataformas de serviço" + +#: ../source/overview.rst:198 +#, fuzzy +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 "" +"Em todas essas configurações, a plataforma cuida do empacotamento e da " +"implantação, desde que você siga seus padrões. A maioria dos softwares não " +"se encaixa em um desses modelos, daí a existência de todas as outras opções " +"abaixo." + +#: ../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 "" +"Se você estiver desenvolvendo um software que será implantado em suas " +"máquinas, computadores pessoais de usuários ou qualquer outro arranjo, " +"continue lendo." + +#: ../source/overview.rst:209 +msgid "Web browsers and mobile applications" +msgstr "Navegadores web e aplicações móveis" + +#: ../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 "" +"Os avanços constantes do Python estão levando-o a novos espaços. Hoje em " +"dia, você pode escrever uma aplicação móvel ou frontend de aplicação web no " +"Python. Embora a linguagem possa ser familiar, as práticas de empacotamento " +"e implantação são novas." + +#: ../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 "" +"Se você está planejando lançar para essas novas fronteiras, convém verificar " +"as seguintes estruturas e consultar seus guias de empacotamento:" + +#: ../source/overview.rst:220 +#, fuzzy +msgid "`Kivy `_" +msgstr "`Kivy `_" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "`Beeware `_" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "`Brython `_" + +#: ../source/overview.rst:223 +#, fuzzy +msgid "`Flexx `_" +msgstr "`Flexx `_" + +#: ../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 "" +"Se você *não* está interessado em usar um framework ou plataforma, ou apenas " +"quer saber sobre algumas das tecnologias e técnicas utilizadas pelos " +"frameworks acima, continue lendo abaixo." + +#: ../source/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "Dependendo de um Python pré-instalado" + +#: ../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 "" +"Escolha um computador arbitrário e, dependendo do contexto, há uma boa " +"chance do Python já estar instalado. Incluído por padrão na maioria dos " +"sistemas operacionais Linux e Mac por muitos anos, você pode depender " +"razoavelmente do Python preexistente em seus datacenters ou nas máquinas " +"pessoais de desenvolvedores e cientistas de dados." + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "Tecnologias que oferecem suporte a este modelo:" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr ":gh:`PEX ` (Python EXecutable)" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" +":doc:`zipapp ` (não ajuda a gerenciar dependências, " +"requer Python 3.5+)" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr ":gh:`shiv ` (requer Python 3)" + +#: ../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 "" +"De todas as abordagens aqui, depender de um Python pré-instalado depende " +"mais do ambiente de destino. Claro, isso também contribui para o menor " +"pacote, tão pequeno quanto megabytes de um dígito, ou mesmo kilobytes." + +#: ../source/overview.rst:249 +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 "" +"Em geral, diminuir a dependência do sistema de destino aumenta o tamanho do " +"nosso pacote, portanto, as soluções aqui são organizadas de forma grosseira " +"pelo aumento do tamanho da saída." + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "Dependendo de um ecossistema separado de distribuição de software" + +#: ../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 "" +"Por um longo tempo, muitos sistemas operacionais, incluindo Mac e Windows, " +"não tinham gerenciamento de pacotes integrado. Apenas recentemente esses " +"sistemas operacionais ganharam as chamadas \"*app store*\", mas mesmo " +"aqueles se concentram em aplicações de consumo e oferecem pouco para os " +"desenvolvedores." + +#: ../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 "" +"Os desenvolvedores buscaram soluções por muito tempo e, nessa luta, surgiram " +"com suas próprias soluções de gerenciamento de pacotes, como o `Homebrew " +"`_. A alternativa mais relevante para desenvolvedores " +"Python é um ecossistema de pacotes chamado `Anaconda `_. O Anaconda é " +"construído em torno do Python e é cada vez mais comum em ambientes " +"acadêmicos, analíticos e outros ambientes orientados a dados, chegando até a " +"ambientes orientados a servidor `_." + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" +"Instruções sobre como construir e publicar para o ecossistema do Anaconda:" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" +"`Building libraries and applications with conda `_" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" +"`Transitioning a native Python package to Anaconda `_" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" +"Um modelo semelhante envolve a instalação de uma distribuição alternativa " +"Python, mas não oferece suporte a pacotes arbitrários em nível de sistema " +"operacional:" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" +"`ActiveState ActivePython `_" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "`WinPython `_" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "Trazendo seu próprio executável Python" + +#: ../source/overview.rst:290 +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." +msgstr "" +"A computação como a conhecemos é definida pela capacidade de executar " +"programas. Cada sistema operacional oferece suporte nativamente a um ou mais " +"formatos de programas que eles podem executar nativamente." + +#: ../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 "" +"Existem muitas técnicas e tecnologias que transformam seu programa Python em " +"um desses formatos, a maioria das quais envolve a incorporação do " +"interpretador Python e quaisquer outras dependências em um único arquivo " +"executável." + +#: ../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 "" +"Essa abordagem, chamada *congelamento*, oferece ampla compatibilidade e " +"experiência perfeita do usuário, embora muitas vezes exija múltiplas " +"tecnologias e uma boa quantidade de esforço." + +#: ../source/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "Uma seleção de congeladores Python:" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" +"`pyInstaller `_ - " +"Multiplataforma" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" +"`cx_Freeze `_ - Multiplataforma" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" +"`constructor `_ - Para instaladores de " +"linha de comando" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "`py2exe `_ - Windows apenas" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "`py2app `_ - Mac apenas" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "`osnap `_ - Windows e Mac" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "`pynsist `_ - Windows apenas" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" +"A maioria dos itens acima implica em implantações de um único usuário. Para " +"aplicações de servidor com vários componentes, consulte :gh:`Chef Omnibus " +"`." + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "Trazendo seu próprio espaço de usuário" + +#: ../source/overview.rst:321 +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*." +msgstr "" +"Um número crescente de sistemas operacionais -- incluindo Linux, Mac OS e " +"Windows -- pode ser configurado para executar aplicações empacotadas como " +"imagens leves, usando um arranjo relativamente moderno, frequentemente " +"referido como `virtualização em nível de sistema operacional `_ ou " +"*conteinerização*." + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" +"Essas técnicas são principalmente Python agnósticas, porque empacotam " +"sistemas de arquivos inteiros de sistemas operacionais, não apenas Python ou " +"pacotes Python." + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" +"A adoção é mais extensa entre os servidores Linux, onde a tecnologia se " +"originou e onde as tecnologias abaixo funcionam melhor:" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "`AppImage `_" + +#: ../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 "Trazendo seu próprio kernel" + +#: ../source/overview.rst:342 +#, fuzzy +#| 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." +msgid "" +"Most desktop 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 "" +"A maioria dos sistemas operacionais oferece suporte a alguma forma de " +"virtualização clássica, executando aplicações empacotadas como imagens " +"contendo um sistema operacional completo próprio. Executar essas máquinas " +"virtuais, ou VMs, é uma abordagem madura, amplamente difundida em ambientes " +"de datacenter." + +#: ../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:" +msgstr "" +"Essas técnicas são reservadas principalmente para implantações em grande " +"escala em datacenters, embora algumas aplicativas complexas possam se " +"beneficiar desse pacote. As tecnologias são agnósticas ao Python e incluem:" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" +"`VHD `_, `AMI `_ e :doc:`outros formatos " +"`" + +#: ../source/overview.rst:356 +#, fuzzy +#| msgid "" +#| "`OpenStack `_ - A cloud " +#| "management system in Python, with extensive VM support" +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" +"`OpenStack `_ - Um sistema de " +"gerenciamento de nuvem em Python, com suporte extenso a VM" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "Trazendo seu próprio hardware" + +#: ../source/overview.rst:362 +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." +msgstr "" +"A maneira mais abrangente de enviar seu software seria enviá-lo já instalado " +"em algum hardware. Dessa forma, o usuário do seu software precisaria apenas " +"de eletricidade." + +#: ../source/overview.rst:366 +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 "" +"Considerando que as máquinas virtuais descritas acima são reservadas " +"principalmente para os conhecedores de tecnologia, você pode encontrar " +"dispositivos de hardware sendo usados por todos, desde os datacenters mais " +"avançados até as crianças mais novas." + +#: ../source/overview.rst:370 +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 "" +"Incorpore seu código em um :gh:`Adafruit `, " +"`MicroPython `_ ou hardware mais poderoso " +"executando Python e, em seguida, envie-o para o datacenter ou para as casas " +"de seus usuários. Eles conectam e estará funcionando, e você pode encerrar o " +"dia." + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "Um resumo de tecnologias usadas para empacotar aplicações Python." + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" +"A gama simplificada de tecnologias usadas para empacotar aplicações Python." + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "E quanto a..." + +#: ../source/overview.rst:384 +msgid "" +"The sections above can only summarize so much, and you might be wondering " +"about some of the more conspicuous gaps." +msgstr "" +"As seções acima resumem muito, e você pode estar se perguntando sobre " +"algumas das lacunas mais evidentes." + +#: ../source/overview.rst:388 +msgid "Operating system packages" +msgstr "Pacotes de sistema operacional" + +#: ../source/overview.rst:390 +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 "" +"Como mencionado em :ref:`depending-on-a-separate-ecosystem` acima, alguns " +"sistemas operacionais possuem gerenciadores de pacotes próprios. Se você " +"tiver certeza do sistema operacional que está almejando, pode depender " +"diretamente de um formato como `deb `_ (para Debian, Ubuntu , etc.) ou `RPM `_ (para Red Hat, Fedora, etc.) e " +"usar esse gerenciador de pacotes embutido para cuidar da instalação, e mesmo " +"implantação. Você pode até usar `FPM `_ para gerar deb e RPMs da mesma fonte." + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" +"Na maioria das pipelines de implantação, o gerenciador de pacotes do sistema " +"operacional é apenas uma peça do quebra-cabeça." + +#: ../source/overview.rst:407 +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." +msgstr "" +":doc:`Virtualenvs ` têm sido uma ferramenta " +"indispensável para várias gerações de desenvolvedores Python, mas estão " +"desaparecendo lentamente de vista, à medida que estão sendo envoltos por " +"ferramentas de nível superior. Com o empacotamento em particular, " +"virtualenvs são usados como primitivos na :doc:`ferramenta dh-virtualenv ` e `osnap `_, ambos " +"envolvem virtualenvs de uma forma independente." + +#: ../source/overview.rst:416 +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." +msgstr "" +"Para implantações de produção, não dependa da execução de ``python -m pip " +"install`` da Internet em um virtualenv, como alguém pode fazer em um " +"ambiente de desenvolvimento. A visão geral acima está repleta de soluções " +"muito melhores." + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "Segurança" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" +"Quanto mais fundo você descer nas camadas, mais difícil será para atualizar " +"os componentes do seu pacote. Tudo está mais estreitamente ligado." + +#: ../source/overview.rst:426 +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 `_." +msgstr "" +"Por exemplo, se surgir um problema de segurança do kernel e você estiver " +"implantando contêineres, o kernel do sistema host pode ser atualizado sem a " +"necessidade de uma nova compilação em nome da aplicação. Se você implantar " +"imagens de VM, precisará de uma nova construção. Se essa dinâmica torna ou " +"não uma opção mais segura ainda é um debate antigo, voltando à questão ainda " +"não resolvida de `ligação estática versus ligação dinâmica `_." + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "Resumo" + +#: ../source/overview.rst:437 +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." +msgstr "" +"O empacotamento no Python tem a reputação de ser um percurso acidentado. " +"Essa impressão é principalmente um subproduto da versatilidade do Python. " +"Depois de entender os limites naturais entre cada solução de empacotamento, " +"você começa a perceber que o cenário variado é um preço pequeno Python que " +"os programadores pagam por usar uma das linguagens mais equilibradas e " +"flexíveis disponíveis." + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "Formato de distribuição binária" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" +"Um wheel é um arquivo em formato ZIP com um nome de arquivo formatado de " +"forma especial e a extensão ``.whl``. Ele contém uma única distribuição " +"quase como seria instalado de acordo com a PEP 376 com um esquema de " +"instalação particular. Embora um instalador especializado seja recomendado, " +"um arquivo wheel pode ser instalado simplesmente descompactando em pacotes " +"de sites com a ferramenta padrão de \"descompactação\" enquanto preserva " +"informações suficientes para espalhar seu conteúdo em seus caminhos finais a " +"qualquer momento." + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "Detalhes" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "Instalando um wheel 'distribution-1.0-py32-none-any.whl'" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "A instalação do wheel consiste, em teoria, em duas fases:" + +#: ../source/specifications/binary-distribution-format.rst:29 +msgid "Unpack." +msgstr "Desempacotar." + +#: ../source/specifications/binary-distribution-format.rst:31 +msgid "Parse ``distribution-1.0.dist-info/WHEEL``." +msgstr "Analisar ``distribution-1.0.dist-info/WHEEL``." + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" +"Verificar se o instalador é compatível com a versão Wheel. Avisa se a versão " +"secundária é maior, cancela se a versão principal é maior." + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" +"Se Root-Is-Purelib == 'true', descompactar o arquivo em purelib (sites-" +"packages)." + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "Caso contrário, descompactar o arquivo em platlib (site-packages)." + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "Espalhar." + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" +"O arquivo descompactado inclui ``distribution-1.0.dist-info/`` e (se houver " +"dados) ``distribution-1.0.data/``." + +#: ../source/specifications/binary-distribution-format.rst:42 +#, fuzzy +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)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" +"Mover cada subárvore de ``distribution-1.0.data/`` em seu caminho de " +"destino. Cada subdiretório de ``distribution-1.0.data/`` é uma chave para um " +"dicionário de diretórios de destino, como ``distribution-1.0.data/(purelib|" +"platlib|headers|scripts|data)``. Os caminhos inicialmente suportados são " +"obtidos de ``distutils.command.install``." + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" +"Se aplicável, atualizar os scripts começando com ``#!python`` para apontar " +"para o interpretador correto." + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" +"Atualizar ``distribution-1.0.dist-info/RECORD`` com os caminhos instalados." + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "Remover o diretório vazio ``distribution-1.0.data``." + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" +"Compilar qualquer .py instalado em .pyc. (Os desinstaladores devem ser " +"inteligentes o suficiente para remover .pyc, mesmo que não seja mencionado " +"em RECORD.)" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "Recursos de instalador recomendados" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "Reescrever ``#!python``." + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" +"No wheel, os scripts são empacotados em ``{distribution}-{version}.data/" +"scripts/``. Se a primeira linha de um arquivo em ``scripts/`` começar " +"exatamente com ``b'#!python'``, reescreva para apontar para o interpretador " +"correto. Os instaladores do Unix podem precisar adicionar o bit +x a esses " +"arquivos se o arquivo tiver sido criado em Windows." + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" +"A convenção ``b'#!pythonw'`` é permitida. ``b'#!pythonw'`` indica um script " +"GUI ao invés de um script de console." + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "Gerar script wrappers." + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" +"No wheel, scripts empacotados em sistemas Unix certamente não serão " +"acompanhados de wrappers .exe. Os instaladores Windows podem querer adicioná-" +"los durante a instalação." + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "Recursos de arquivador recomendados" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "Colocar ``.dist-info`` no final do arquivo." + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" +"Os arquivadores são encorajados a colocar os arquivos ``.dist-info`` " +"fisicamente no final do repositório. Isso permite alguns truques de ZIP " +"potencialmente interessantes, incluindo a capacidade de corrigir os " +"metadados sem reescrever todo o arquivo." + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "Formato de arquivos" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "Convenção de nome de arquivos" + +#: ../source/specifications/binary-distribution-format.rst:92 +msgid "" +"The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" +"{abi tag}-{platform tag}.whl``." +msgstr "" +"O nome de arquivo do wheel é ``{distribution}-{version}(-{build tag})?-" +"{python tag}-{abi tag}-{platform tag}.whl``." + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "distribution" +msgstr "distribution" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "Nome da distribuição (p.ex., 'django', 'pyramid')." + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "version" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "Versão da distribuição (p.ex., 1.0)." + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "build tag" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" +"Número de construção opcional. Deve começar com um dígito. Atua como um " +"desempate se os nomes de arquivo de dois wheels forem iguais em todos os " +"outros aspectos (ou seja, nome, versão e outras tags). Classifique como uma " +"tupla vazia se não for especificado, caso contrário, classifique como uma " +"tupla de dois itens com o primeiro item sendo os dígitos iniciais como um " +"``int``, e o segundo item sendo o restante da tag como um ``str``." + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" +"Um caso de uso comum para números de construção é reconstruir uma " +"distribuição binária devido a uma mudança no ambiente de construção, como ao " +"usar a imagem manylinux para construir distribuições usando versões de pré-" +"lançamento do CPython." + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" +"Os números de construção não fazem parte da versão de distribuição e, " +"portanto, são difíceis de se referir externamente, especialmente fora do " +"ecossistema do Python de ferramentas e padrões. Um caso comum em que uma " +"distribuição precisa ser referenciada externamente é quando se resolve uma " +"vulnerabilidade de segurança." + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" +"Devido a esta limitação, novas distribuições que precisam ser referenciadas " +"externamente **não devem** usar números de construção ao construir a nova " +"distribuição. Em vez disso, deve ser criada uma **nova versão de " +"distribuição** para esses casos." + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "implementação da linguagem e tag de versão" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "p.ex., 'py27', 'py2', 'py3'." + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "abi tag" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "p.ex., 'cp33m', 'abi3', 'none'." + +#: ../source/specifications/binary-distribution-format.rst:133 +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "platform tag" +msgstr "platform tag" + +#: ../source/specifications/binary-distribution-format.rst:133 +msgid "E.g. 'linux_x86_64', 'any'." +msgstr "p.ex., 'linux_x86_64', 'any'." + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" +"Por exemplo, ``distribution-1.0-1-py27-none-any.whl`` é a primeira " +"construção de um pacote chamado 'distribution' e é compatível com Python 2.7 " +"(qualquer implementação Python 2.7), com sem ABI (puro Python), em qualquer " +"arquitetura de CPU." + +#: ../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 "" +"Os últimos três componentes do nome do arquivo antes da extensão são " +"chamados de \"tags de compatibilidade\". As tags de compatibilidade " +"expressam os requisitos básicos do interpretador do pacote e são detalhadas " +"na PEP 425." + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "Escape e Unicode" + +#: ../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 "" +"Como os componentes do nome do arquivo são separados por um traço (``-``, " +"HYPHEN-MINUS), este caractere não pode aparecer em nenhum componente. Isso é " +"tratado da seguinte maneira:" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" +"Em nomes de distribuição, qualquer ocorrência de caracteres ``-_.`` (HYPHEN-" +"MINUS, LOW LINE e FULL STOP) deve ser substituída por ``_`` (LOW LINE) e " +"caracteres maiúsculos devem ser substituídos pelos minúsculos " +"correspondentes. Isso é equivalente à :ref:`normalização de nome ` regular da :pep:`503` seguida pela substituição de ``-`` por " +"``_``. Porém, ferramentas que usem wheels devem estar preparadas para " +"aceitar ``.`` (FULL STOP) e letras maiúsculas, pois estes eram permitidos " +"por uma versão anterior desta especificação." + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" +"Os números de versão devem ser normalizados de acordo com " +"a :ref:`especificação de especificadores de versão `. Os " +"números de versão normalizados não podem conter ``-``." + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" +"Os componentes restantes não podem conter caracteres ``-``, portanto, nenhum " +"escape é necessário." + +#: ../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 "" +"Ferramentas que produzem wheels devem verificar se os componentes do nome de " +"arquivo não contêm ``-``, pois o arquivo resultante pode não ser processado " +"corretamente se contiverem." + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" +"O nome do arquivo é Unicode. Levará algum tempo até que as ferramentas sejam " +"atualizadas para oferecer suporte a nomes de arquivos não ASCII, mas eles " +"são suportados nesta especificação." + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" +"Os nomes de arquivos *dentro* do arquivo são codificados como UTF-8. Embora " +"alguns clientes ZIP em uso comum não exibam nomes de arquivo UTF-8 " +"apropriadamente, a codificação é suportada pela especificação ZIP e pelo " +"``zipfile`` do Python." + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "Conteúdo dos arquivos" + +#: ../source/specifications/binary-distribution-format.rst:177 +#, fuzzy +#| 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:" +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" +"O conteúdo de um arquivo wheel, onde {distribution} é substituído pelo nome " +"do pacote, por exemplo, ``beaglevote`` e {version} é substituído por sua " +"versão, p.ex., ``1.0.0``, consiste em:" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" +"``/``, a raiz do arquivo, contém todos os arquivos a serem instalados em " +"``purelib`` ou ``platlib`` conforme especificado em ``WHEEL``. ``purelib`` e " +"``platlib`` são normalmente ``site-packages``." + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "``{distribution}-{version}.dist-info/`` contém metadados." + +#: ../source/specifications/binary-distribution-format.rst:188 +#, fuzzy +#| msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "``{distribution}-{version}.dist-info/`` contém metadados." + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" +"``{distribution}-{version}.data/`` contém um subdiretório para cada chave de " +"esquema de instalação não vazia ainda não coberta, onde o nome do " +"subdiretório é um índice em um dicionário de caminhos de instalação (p.ex., " +"``data``, ``scripts``, ``headers``, ``purelib``, ``platlib``)." + +#: ../source/specifications/binary-distribution-format.rst:193 +#, fuzzy +#| 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." +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" +"Scripts Python devem aparecer em ``scripts`` e começar exatamente com ``b'#!" +"python'`` para desfrutar da geração do wrapper de script e reescrever ``#!" +"python`` no momento da instalação. Eles podem ter qualquer ou nenhuma " +"extensão." + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" +"``{distribution}-{version}.dist-info/METADATA`` é Metadata versão 1.1 ou " +"metadados de formato superior." + +#: ../source/specifications/binary-distribution-format.rst:199 +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`` são metadados sobre p arquivo " +"em si no mesmo formato \"chave: valor\"::" + +#: ../source/specifications/binary-distribution-format.rst:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "``Wheel-Version`` é o número de versão da especificação Wheel." + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" +"``Generator`` é o nome e, opcionalmente, a versão do software que produziu o " +"arquivo." + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" +"``Root-Is-Purelib`` é verdadeiro se o diretório de nível superior do arquivo " +"deve ser instalado em purelib; caso contrário, a raiz deve ser instalada no " +"platlib." + +#: ../source/specifications/binary-distribution-format.rst:215 +msgid "" +"``Tag`` is the wheel's expanded compatibility tags; in the example the " +"filename would contain ``py2.py3-none-any``." +msgstr "" +"``Tag`` são as tags de compatibilidade expandida do wheel; no exemplo, o " +"nome do arquivo conteria ``py2.py3-none-any``." + +#: ../source/specifications/binary-distribution-format.rst:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" +"``Build`` é o número da construção e é omitido se não houver número da " +"construção." + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" +"Um instalador de wheel deve avisar se Wheel-Version é maior do que a versão " +"que ele suporta, e deve falhar se Wheel-Version tiver uma versão principal " +"maior do que a versão que ele suporta." + +#: ../source/specifications/binary-distribution-format.rst:221 +msgid "" +"Wheel, being an installation format that is intended to work across multiple " +"versions of Python, does not generally include .pyc files." +msgstr "" +"O Wheel, sendo um formato de instalação destinado a funcionar em várias " +"versões do Python, geralmente não inclui arquivos .pyc." + +#: ../source/specifications/binary-distribution-format.rst:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "Wheel não contém setup.py ou setup.cfg." + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" +"Esta versão da especificação do wheel é baseada nos esquemas de instalação " +"do distutils e não define como instalar arquivos em outros locais. O layout " +"oferece um superconjunto da funcionalidade fornecida pelos formatos binários " +"wininst e egg existentes." + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "O diretório .dist-info" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" +"Os diretórios .dist-info de wheels incluem no mínimo METADATA, WHEEL e " +"RECORD." + +#: ../source/specifications/binary-distribution-format.rst:236 +msgid "" +"METADATA is the package metadata, the same format as PKG-INFO as found at " +"the root of sdists." +msgstr "" +"METADATA são os metadados do pacote, o mesmo formato do PKG-INFO encontrado " +"na raiz dos sdists." + +#: ../source/specifications/binary-distribution-format.rst:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" +"WHEEL são os metadados de wheel específicos para uma construção do pacote." + +#: ../source/specifications/binary-distribution-format.rst:239 +#, fuzzy +#| 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." +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." +msgstr "" +"RECORD é uma lista de (quase) todos os arquivos no wheel seus hashes " +"seguros. Ao contrário da PEP 376, nenhum arquivo, exceto RECORD, pode conter " +"um hash de si mesmo, deve incluir seu hash. O algoritmo hash deve ser sha256 " +"ou melhor; especificamente, md5 e sha1 não são permitidos, pois os arquivos " +"wheel assinados contam com hashes fortes em RECORD para validar a " +"integridade do arquivo." + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "INSTALLER e REQUESTED da PEP 376 não são incluídos no arquivo." + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +#, fuzzy +#| 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." +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" +"Durante a extração, os instaladores de wheels verificam todos os hashes em " +"RECORD em relação ao conteúdo do arquivo. Além de RECORD e suas assinaturas, " +"a instalação falhará se qualquer arquivo no arquivo não for mencionado e com " +"hash correto em RECORD." + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +#, fuzzy +#| msgid "Project name" +msgid "Subdirectory name" +msgstr "Nome do projeto" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#, fuzzy +#| msgid "``license``" +msgid "``licenses``" +msgstr "``license``" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +#, fuzzy +#| msgid ":pep:`600`" +msgid ":pep:`639`" +msgstr ":pep:`600`" + +#: ../source/specifications/binary-distribution-format.rst:265 +#, fuzzy +#| msgid "``license``" +msgid "``license_files``" +msgstr "``license``" + +#: ../source/specifications/binary-distribution-format.rst:266 +#, fuzzy +#| msgid "``LIB``" +msgid "``LICENSES``" +msgstr "``LIB``" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +#, fuzzy +#| msgid ":pep:`571`" +msgid ":pep:`770`" +msgstr ":pep:`571`" + +#: ../source/specifications/binary-distribution-format.rst:271 +#, fuzzy +#| msgid "The .dist-info directory" +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "O diretório .dist-info" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +#, fuzzy +#| msgid "The .dist-info directory" +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "O diretório .dist-info" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "O diretório .data" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" +"Qualquer arquivo que não é normalmente instalado dentro de site-packages vai " +"para o diretório .data, nomeado como o diretório .dist-info, mas com a " +"extensão .data/::" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" +"O diretório .data contém subdiretórios com os scripts, cabeçalhos, " +"documentação e assim por diante da distribuição. Durante a instalação, o " +"conteúdo desses subdiretórios é movido para seus caminhos de destino." + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "FAQ" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "Wheel define um diretório .data. Devo colocar todos os meus dados lá?" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" +"Esta especificação não tem uma opinião sobre como você deve organizar seu " +"código. O diretório .data é apenas um lugar para quaisquer arquivos que não " +"são normalmente instalados dentro de ``site-packages`` ou no PYTHONPATH. Em " +"outras palavras, você pode continuar a usar ``pkgutil.get_data(package, " +"resource)`` ainda que *esses* arquivos normalmente não sejam distribuídos no " +"diretório ``.data`` do *wheel*." + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "Qual é a diferença entre \"purelib\" e \"platlib\"?" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" +"O Wheel preserva a distinção \"purelib\" vs. \"platlib\", que é " +"significativa em algumas plataformas. Por exemplo, o Fedora instala pacotes " +"puro Python em '/usr/lib/pythonX.Y/site-packages' e pacotes dependentes de " +"plataforma em '/usr/lib64/pythonX.Y/site-packages'." + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" +"Um wheel com \"Root-Is-Purelib: false\" com todos os seus arquivos em " +"``{nome}-{versão}.data/purelib`` é equivalente a um wheel com \"Root-Is-" +"Purelib: true\" com os mesmos arquivos na raiz, e é válido ter arquivos nas " +"categorias \"purelib\" e \"platlib\"." + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" +"Na prática, um wheel deve ter apenas um de \"purelib\" ou \"platlib\" " +"dependendo se é puro Python ou não e esses arquivos devem estar na raiz com " +"a configuração apropriada fornecida para \"Root-is-purelib\"." + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "É possível importar código Python diretamente de um arquivo wheel?" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" +"Tecnicamente, devido à combinação de suporte de instalação via extração " +"simples e usando um formato de arquivo compatível com ``zipimport``, um " +"subconjunto de arquivos wheel oferece suporte a ser colocado diretamente no " +"``sys.path``. No entanto, embora esse comportamento seja uma consequência " +"natural do design do formato, não é recomendável confiar nele." + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" +"Em primeiro lugar, o wheel *é* projetado principalmente como um formato de " +"distribuição, então pular a etapa de instalação também significa evitar " +"deliberadamente qualquer dependência de recursos que pressupõem a instalação " +"completa (como ser capaz de usar ferramentas padrão como ``pip`` e " +"``virtualenv`` para capturar e gerenciar dependências de uma forma que " +"possam ser devidamente rastreadas para fins de auditoria e atualização de " +"segurança, ou integração completa com o maquinário de construção padrão para " +"extensões C, publicando arquivos de cabeçalho no local apropriado)." + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" +"Em segundo lugar, embora alguns softwares Python sejam escritos para " +"suportar a execução direta de um arquivo zip, ainda é comum que o código " +"seja escrito assumindo que foi totalmente instalado. Quando essa suposição é " +"quebrada ao tentar executar o software a partir de um arquivo zip, as falhas " +"podem frequentemente ser obscuras e difíceis de diagnosticar (especialmente " +"quando ocorrem em bibliotecas de terceiros). As duas fontes mais comuns de " +"problemas com isso são o fato de que a importação de extensões C de um " +"arquivo zip *não* ser suportada pelo CPython (uma vez que fazer isso não é " +"suportado diretamente pela máquina de carregamento dinâmico em qualquer " +"plataforma) e que quando executando a partir de um arquivo zip, o atributo " +"``__file__`` não se refere mais a um caminho de sistema de arquivos comum, " +"mas a um caminho de combinação que inclui tanto a localização do arquivo zip " +"no sistema de arquivos quanto o caminho relativo para o módulo dentro do " +"arquivo. Mesmo quando o software usa corretamente as APIs de recursos " +"abstratos internamente, a interface com componentes externos ainda pode " +"exigir a disponibilidade de um arquivo real no disco." + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" +"Como metaclasses, *monkeypatching* e importadores de metacaminho, se você " +"ainda não tem certeza de que precisa tirar proveito desse recurso, é quase " +"certo que não precisa dele. Se você decidir usá-lo de qualquer maneira, " +"esteja ciente de que muitos projetos exigirão que uma falha seja reproduzida " +"com um pacote totalmente instalado antes de aceitá-lo como um bug genuíno." + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "Histórico" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +#, fuzzy +msgid "" +"February 2021: The rules on escaping in wheel filenames were revised, to " +"bring them into line with what popular tools actually do." +msgstr "" +"As regras sobre como escapar em nomes de arquivos wheel foram revisadas, " +"para alinhá-las com o que as ferramentas populares realmente fazem " +"(fevereiro de 2021)." + +#: ../source/specifications/binary-distribution-format.rst:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +#, fuzzy +#| msgid "" +#| "This document describes the dependency specifiers format as originally " +#| "specified in :pep:`508`." +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" +"Este documento descreve o formato dos especificadores de dependência " +"conforme originalmente especificado na :pep:`508`." + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "Apêndice" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "Exemplo de implementação de urlsafe-base64-nopad::" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "Exemplo" + +#: ../source/specifications/build-details/index.rst:35 +#, fuzzy +#| msgid "Changes" +msgid "Changelog" +msgstr "Alterações" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "Especificação" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Project" +msgid "*object*" +msgstr "Projeto" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Semantic versioning" +msgid "Schema version." +msgstr "Versionamento semântico" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "enscons" +msgid "const" +msgstr "enscons" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Examples" +msgid "examples" +msgstr "Exemplos" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "python" +msgid "bin/python" +msgstr "python" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "platform tag" +msgid "**platform**" +msgstr "platform tag" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "platform tag" +msgid "System platform string." +msgstr "platform tag" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "linux_x86_64" +msgid "linux-x86\\_64" +msgstr "linux_x86_64" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "version" +msgid "**version**" +msgstr "version" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "version" +msgid "version\\_info" +msgstr "version" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Release" +msgid "releaselevel" +msgstr "Lançamento" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Mercurial" +msgid "serial" +msgstr "Mercurial" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "**Numbers**" +msgid "*number*" +msgstr "**Números**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Additional notes" +msgid "additionalProperties" +msgstr "Notas adicionais" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +msgid "**implementation**" +msgstr "Tipos de documentação" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "name" +msgid "**name**" +msgstr "name" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "python" +msgid "cpython" +msgstr "python" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "abi tag" +msgid "abi" +msgstr "abi tag" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "**Headings**" +msgid "**flags**" +msgstr "**Títulos**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Versions" +msgid "extensions" +msgstr "Versões" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "python" +msgid "libpython" +msgstr "python" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "``dynamic``" +msgid "dynamic" +msgstr "``dynamic``" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Building binary extensions" +msgid "link\\_extensions" +msgstr "Construindo extensões binárias" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "**Numbers**" +msgid "**headers**" +msgstr "**Números**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Arbitrary equality" +msgid "arbitrary\\_data" +msgstr "Igualdade arbitrária" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "Especificações de metadados principais" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" +"Os campos definidos nas especificações a seguir devem ser considerados " +"válidos, completos e não sujeitos a alterações. Os campos obrigatórios são:" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "``Name``" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "Todos os outros campos são opcionais." + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" +"O formato de arquivo padrão para metadados (incluindo em :doc:`wheels " +"` e :doc:`projetos instalados `) é baseado no formato de cabeçalhos de e-mail. No " +"entanto, os formatos de e-mail foram revisados várias vezes e não é " +"especificado exatamente qual RFC de e-mail se aplica aos metadados do " +"pacote. Na ausência de uma definição precisa, o padrão prático é definido " +"pelo que o módulo da biblioteca padrão :mod:`python:email.parser` pode " +"analisar usando a política :data:`~.python:email.policy.compat32`." + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" +"Sempre que os metadados são serializados para um fluxo de bytes (por " +"exemplo, para salvar em um arquivo), as strings devem ser serializadas " +"usando a codificação UTF-8." + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" +"Embora a :pep:`566` tenha definido uma maneira de transformar metadados em " +"um dicionário compatível com JSON, isso ainda não é usado como um formato de " +"intercâmbio padrão. A necessidade de ferramentas para trabalhar com anos de " +"pacotes existentes torna difícil mudar para um novo formato." + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" +"*Interpretando metadados antigos:* Na :pep:`566`, a especificação do formato " +"do campo do especificador de versão foi relaxada para aceitar a sintaxe " +"usada por ferramentas de publicação populares (nomeadamente para remover o " +"requisito de que os especificadores de versão devem estar entre parênteses). " +"Os consumidores de metadados podem querer usar regras de formatação mais " +"relaxadas, mesmo para arquivos de metadados que são nominalmente inferiores " +"à versão 2.1." + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "Metadata-Version" + +#: ../source/specifications/core-metadata.rst:52 +#, fuzzy +#| msgid "" +#| "Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +#| "\"2.1\", \"2.2\", and \"2.3\"." +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" +"Versão do formato de arquivo; valores válidos são \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\" e \"2.3\"." + +#: ../source/specifications/core-metadata.rst:55 +#, fuzzy +#| 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)." +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)." +msgstr "" +"Ferramentas automatizadas que consomem metadados DEVEM avisar se " +"``metadata_version`` é maior que a versão mais alta à qual oferecem suporte, " +"e DEVEM falhar se ``metadata_version`` tem uma versão maior do que a versão " +"mais alta à qual oferecem suporte (como descrito na :ref:`especificação de " +"especificadores de versão `, a versão principal é o " +"valor antes do primeiro ponto)." + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" +"Para uma compatibilidade mais ampla, as ferramentas de construção PODEM " +"escolher produzir metadados de distribuição usando a versão de metadados " +"mais baixa que inclui todos os campos necessários." + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "Exemplo::" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "Nome" + +#: ../source/specifications/core-metadata.rst:77 +#, fuzzy +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "Adicionadas restrições adicionais ao formato da :pep:`508`" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" +"Para propósitos de comparação, os nomes devem ser :ref:`normalizados ` antes da comparação." + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "Versão" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" +"Uma string contendo o número da versão da distribuição. Este campo deve " +"estar no formato especificado na :ref:`especificação de especificadores de " +"versão `." + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "Dynamic (vários usos)" + +#: ../source/specifications/core-metadata.rst:113 +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 "" +"Uma string contendo o nome de outro campo de metadados principal. Os nomes " +"dos campos ``Name``, ``Version`` e ``Metadata-Version`` não podem ser " +"especificados neste campo." + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" +"Quando encontrados nos metadados de uma distribuição fonte, as seguintes " +"regras se aplicam:" + +#: ../source/specifications/core-metadata.rst:120 +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 "" +"Se um campo *não* estiver marcado como ``Dynamic``, então o valor do campo " +"em qualquer wheel construído a partir do sdist DEVE corresponder ao valor do " +"sdist. Se o campo não estiver no sdist e não estiver marcado como " +"``Dynamic``, ele NÃO DEVE estar presente no wheel." + +#: ../source/specifications/core-metadata.rst:124 +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 "" +"Se um campo for marcado como ``Dynamic``, ele pode conter qualquer valor " +"válido em um wheel construído a partir do sdist (incluindo não estar " +"presente)." + +#: ../source/specifications/core-metadata.rst:127 +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 "" +"Se a versão dos metadados sdist for anterior à versão 2.2, todos os campos " +"devem ser tratados como se tivessem sido especificados com ``Dynamic`` (ou " +"seja, não há restrições especiais sobre os metadados dos wheels construídos " +"a partir do sdist)." + +#: ../source/specifications/core-metadata.rst:131 +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 "" +"Em qualquer contexto que não seja uma distribuição fonte, ``Dynamic`` é " +"apenas para informação e indica que o valor do campo foi calculado no tempo " +"de construção do wheel, e pode não ser o mesmo que o valor no sdist ou em " +"outros wheels para o projeto." + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" +"Detalhes completos da semântica de ``Dynamic`` são descritos na :pep:`643`." + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "Platform (vários usos)" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" +"Uma especificação da plataforma que descreve um sistema operacional " +"suportado pela distribuição que não está listado nos classificadores Trove " +"de \"Operating System\". Veja \"Classifier\" abaixo." + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "Exemplos::" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "Supported-Platform (vários usos)" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" +"As distribuições binárias contendo um arquivo PKG-INFO usarão o campo " +"Supported-Platform em seus metadados para especificar o sistema operacional " +"e a CPU para os quais a distribuição binária foi compilada. A semântica do " +"campo Supported-Platform não é especificada nesta PEP." + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "Summary" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "Um resumo de uma linha do que a distribuição faz." + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "Este campo pode ser especificado no corpo da mensagem." + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" +"Uma descrição mais longa da distribuição que pode ter vários parágrafos. " +"Software que lida com metadados não deve presumir nenhum tamanho máximo para " +"este campo, embora as pessoas não devam incluir seu manual de instruções " +"como a descrição." + +#: ../source/specifications/core-metadata.rst:217 +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 "" +"O conteúdo deste campo pode ser escrito usando a marcação reStructuredText " +"[1]_. Para programas que funcionam com metadados, o suporte à marcação é " +"opcional; os programas também podem exibir o conteúdo do campo como está. " +"Isso significa que os autores devem ser conservadores na marcação que usam." + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" +"Para oferecer suporte a linhas vazias e linhas com indentação em relação ao " +"formato do RFC 822, qualquer caractere CRLF deve ser sufixado por 7 espaços " +"seguidos por um caractere de encadeamento ou pipe (\"|\"). Como resultado, o " +"campo Description é codificado em um campo dobrado que pode ser interpretado " +"pelo analisador RFC822 [2]_." + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" +"Esta codificação implica que quaisquer ocorrências de um CRLF seguido por 7 " +"espaços e um caractere pipe devem ser substituídos por um único CRLF quando " +"o campo é desdobrado usando um leitor de RFC822." + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" +"Alternativamente, a descrição da distribuição pode ser fornecida no corpo da " +"mensagem (ou seja, após uma linha completamente em branco após os " +"cabeçalhos, sem recuo ou outra formatação especial necessária)." + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "Description-Content-Type" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" +"Uma string informando a sintaxe de marcação (se houver) usada na descrição " +"da distribuição, para que as ferramentas possam renderizar a descrição de " +"maneira inteligente." + +#: ../source/specifications/core-metadata.rst:260 +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 "" +"Historicamente, o PyPI oferecia suporte a descrições em texto simples e " +"`reStructuredText (reST) `_, e poderia renderizar reST em HTML. No entanto, é " +"comum que os autores da distribuição escrevam a descrição em `Markdown " +"`_ (:rfc:`7763`) visto que " +"tantos sites de hospedagem de código renderizam READMEs de Markdown, e os " +"autores reutilizariam o arquivo para a descrição. O PyPI não reconhecia o " +"formato e, portanto, não conseguia processar a descrição corretamente. Isso " +"resultava em muitos pacotes no PyPI com descrições mal renderizadas quando " +"Markdown é deixado como texto simples, ou pior, era tentado ser renderizado " +"como reST. Este campo permite que o autor da distribuição especifique o " +"formato de sua descrição, abrindo a possibilidade para PyPI e outras " +"ferramentas serem capazes de renderizar Markdown e outros formatos." + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" +"O formato deste campo é o mesmo do cabeçalho ``Content-Type`` em HTTP (ou " +"seja: `RFC 1341 `_). Resumidamente, isso significa que ele tem uma parte do ``tipo/" +"subtipo`` e então pode opcionalmente ter uma série de parâmetros:" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "Formato::" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "A parta ``tipo/subtipo`` tem apenas alguns poucos valores válidos:" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "``text/plain``" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "``text/x-rst``" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "``text/markdown``" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" +"O parâmetro ``charset`` pode ser usado para especificar a codificação de " +"caracteres da descrição. O único valor válido é ``UTF-8``. Se omitido, é " +"considerado ``UTF-8``." + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" +"Outros parâmetros podem ser específicos para o subtipo escolhido. Por " +"exemplo, para o subtipo ``markdown``, existe um parâmetro opcional " +"``variant`` que permite especificar a variante do Markdown em uso (o padrão " +"é ``GFM`` se não for especificado). Atualmente, duas variantes são " +"reconhecidas:" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "``GFM`` para :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "``CommonMark`` para :rfc:`CommonMark <7764#section-3.5>`" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" +"Se um ``Description-Content-Type`` não for especificado, as aplicações devem " +"tentar renderizá-lo como ``text/x-rst; charset=UTF-8`` e volta para ``text/" +"plain`` se não for válido primeiro." + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" +"Se um ``Description-Content-Type`` é um valor não reconhecido, então o tipo " +"de conteúdo presumido ser ``text/plain`` (embora PyPI provavelmente rejeite " +"qualquer coisa com um valor não reconhecido)." + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" +"Se o ``Description-Content-Type`` for ``text/markdown`` e ``variant`` não " +"for especificado ou estiver definido com um valor não reconhecido, então a " +"presume-se ``variant`` ser ``GFM`` ." + +#: ../source/specifications/core-metadata.rst:329 +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 "" +"Portanto, para o último exemplo acima, o ``charset`` padrão é ``UTF-8`` e o " +"``variant`` padrão ``GFM`` e, portanto, é equivalente ao exemplo anterior." + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "Keywords" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" +"Uma lista de palavras-chave adicionais, separadas por vírgulas, a serem " +"usadas para auxiliar na busca pela distribuição em um catálogo maior." + +#: ../source/specifications/core-metadata.rst:351 +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 "" +"A especificação anteriormente mostrava palavras-chave separadas por espaços, " +"mas distutils e setuptools a implementaram com vírgulas. Essas ferramentas " +"foram amplamente utilizadas por muitos anos, então era mais fácil atualizar " +"a especificação para corresponder ao padrão de fato." + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "Author" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" +"Um string contendo o nome do autor, no mínimo; informações de contato " +"adicionais podem ser fornecidas." + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "Author-email" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" +"Uma string contendo o endereço de e-mail do autor. Ela pode conter um nome e " +"endereço de e-mail nas formas válidos para um cabeçalho ``From:`` do RFC-822." + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" +"De acordo com RFC-822, este campo pode conter vários endereços de e-mail " +"separados por vírgula::" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "Mantenedor" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" +"Uma string contendo o nome do mantenedor, no mínimo; informações de contato " +"adicionais podem ser fornecidas." + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" +"Observe que este campo deve ser usado quando um projeto está sendo mantido " +"por alguém que não seja o autor original: ele deve ser omitido se for " +"idêntico a ``Author``." + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "Maintainer-email" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" +"Uma string contendo o endereço de e-mail do mantenedor. Ela pode conter um " +"nome e endereço de e-mail nas formas válidas para um cabeçalho ``From:`` do " +"RFC-822." + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" +"Observe que este campo deve ser usado quando um projeto está sendo mantido " +"por alguém que não seja o autor original: ele deve ser omitido se for " +"idêntico a ``Author-email``." + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "License" + +#: ../source/specifications/core-metadata.rst:449 +#, fuzzy +#| msgid "in favour of ``Requires-Dist``" +msgid "in favour of ``License-Expression``." +msgstr "em favor de ``Requires-Dist``" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" +"Texto indicando a licença cobrindo a distribuição onde a licença não é uma " +"seleção dos classificadores Trove \"License\". Veja :ref:`\"Classifier " +"\"` abaixo. Este campo também pode ser usado para " +"especificar uma versão particular de uma licença que é nomeada através do " +"campo ``Classifier``, ou para indicar uma variação ou exceção a tal licença." + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +#, fuzzy +#| msgid "Requires-Dist (multiple use)" +msgid "License-File (multiple use)" +msgstr "Requires-Dist (vários usos)" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "Classifier (vários usos)" + +#: ../source/specifications/core-metadata.rst:532 +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 "" +"Cada entrada é uma string que fornece um único valor de classificação para a " +"distribuição. Os classificadores são descritos na :pep:`301`, e o Python " +"Package Index publica uma lista dinâmica de `classificadores atualmente " +"definidos `__." + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" +"Este campo pode ser seguido por um marcador de ambiente após um ponto e " +"vírgula." + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "Requires-Dist (vários usos)" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" +"A especificação do formato de campo foi relaxada para aceitar a sintaxe " +"usada por ferramentas de publicação populares." + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" +"Cada entrada contém uma string nomeando algum outro projeto distutils " +"requerido por esta distribuição." + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "O formato de uma string de requisito contém de uma a quatro partes:" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" +"Um nome de projeto, no mesmo formato do campo ``Name:``. A única parte " +"obrigatória." + +#: ../source/specifications/core-metadata.rst:567 +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 "" +"Uma lista separada por vírgulas de nomes \"extras\". Estes são definidos " +"pelo projeto requerido, referindo-se a recursos específicos que podem " +"precisar de dependências extras. Os nomes DEVEM estar em conformidade com as " +"restrições especificadas pelo campo ``Provides-Extra:``." + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" +"Um especificador de versão. As ferramentas que analisam o formato devem " +"aceitar parênteses opcionais em torno disso, mas as ferramentas que o geram " +"não devem usar parênteses." + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" +"Um marcador de ambiente após um ponto e vírgula. Isso significa que o " +"requisito só é necessário nas condições especificadas." + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "Veja a :pep:`508` para detalhes completos do formato permitido." + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" +"Os nomes dos projetos devem corresponder aos nomes encontrados no `Python " +"Package Index`_." + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" +"Os especificadores de versão devem seguir as regras descritas " +"em :doc:`version-specifiers`." + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "Requires-Python" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" +"Este campo especifica a(s) versão(ões) do Python com as quais a distribuição " +"é compatível. As ferramentas de instalação podem observar isso ao escolher " +"qual versão de um projeto instalar." + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" +"O valor deve estar no formato especificado em :doc:`version-specifiers`." + +#: ../source/specifications/core-metadata.rst:606 +#, fuzzy +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" +"Por exemplo, se uma distribuição usa :ref:`f-strings ` " +"então pode impedir a instalação em Python < 3.6 especificando::" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "Este campo não pode ser seguido por um marcador de ambiente." + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "Requires-External (vários usos)" + +#: ../source/specifications/core-metadata.rst:623 +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 "" +"Cada entrada contém uma string que descreve alguma dependência no sistema de " +"que a distribuição deve ser usada. Este campo tem como objetivo servir como " +"uma dica para os mantenedores do projeto downstream, e não tem semântica que " +"seja significativa para a distribuição ``distutils``." + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" +"O formato de uma string de requisito é o nome de uma dependência externa, " +"opcionalmente seguido por uma declaração de versão entre parênteses." + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" +"Como eles se referem a lançamentos de software não-Python, os números de " +"versão para este campo **não** são obrigados a estar em conformidade com o " +"formato especificado na :ref:`especificação de especificadores de versão " +"`: eles devem corresponder ao esquema de versão usado " +"pela dependência externa." + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" +"Observe que não há uma regra específica sobre as strings a serem usadas." + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "Project-URL (vários usos)" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" +"Uma string contendo uma URL navegável para o projeto e um rótulo para ele, " +"separados por uma vírgula." + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "O rótulo é um texto livre limitado a 32 caracteres." + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "Provides-Extra (vários usos)" + +#: ../source/specifications/core-metadata.rst:677 +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 "" +"A :pep:`685` restringiu os valores válidos para serem inequívocos (ou seja, " +"sem necessidade de normalização). Para versões de metadados mais antigas, as " +"restrições de valor foram alinhadas com ``Name:`` e as regras de " +"normalização foram introduzidas." + +#: ../source/specifications/core-metadata.rst:682 +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 "" +"Uma string contendo o nome de um recurso opcional. Um nome válido consiste " +"apenas em letras ASCII minúsculas e números ASCII e hífen. Deve começar e " +"terminar com uma letra ou número. Hífenes não podem ser seguidos por outro " +"hífen. Os nomes são limitados àqueles que correspondem ao seguinte regex " +"(que elimina ambiguidade)::" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" +"O nome especificado pode ser usado para tornar uma dependência condicional " +"ao fato de o recurso opcional ter sido solicitado." + +#: ../source/specifications/core-metadata.rst:698 +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 "" +"Uma segunda distribuição requer uma dependência opcional, colocando-a entre " +"colchetes, e pode solicitar vários recursos, separando-os com uma vírgula " +"(,). Os requisitos são avaliados para cada recurso solicitado e adicionados " +"ao conjunto de requisitos para a distribuição." + +#: ../source/specifications/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" +"Dois nomes de recursos ``test`` e ``doc`` são reservados para marcar " +"dependências que são necessárias para executar testes automatizados e gerar " +"documentação, respectivamente." + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" +"É válido especificar ``Provides-Extra:`` sem referenciá-lo em qualquer " +"``Requer-Dist:``." + +#: ../source/specifications/core-metadata.rst:715 +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 "" +"Ao escrever dados para versões de metadados mais antigas, os nomes DEVEM ser " +"normalizados seguindo as mesmas regras usadas para o campo ``Name:`` ao " +"realizar comparações. Ferramentas que escrevem metadados DEVEM gerar um erro " +"se duas entradas ``Provides-Extra:`` colidirem após serem normalizadas." + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" +"Ao ler dados para versões de metadados mais antigas, as ferramentas DEVEM " +"avisar quando os valores para este campo seriam inválidos em versões de " +"metadados mais recentes. Se um valor for inválido seguindo as regras para " +"``Name:`` em qualquer versão de metadados principais, o usuário DEVE ser " +"avisado e o valor ignorado para evitar ambiguidade. As ferramentas PODEM " +"optar por gerar um erro ao ler um nome inválido para versões de metadados " +"mais antigas." + +#: ../source/specifications/core-metadata.rst:730 +#, fuzzy +#| msgid "Supported-Platform (multiple use)" +msgid "Import-Name (multiple use)" +msgstr "Supported-Platform (vários usos)" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +#, fuzzy +#| msgid "Supported-Platform (multiple use)" +msgid "Import-Namespace (multiple use)" +msgstr "Supported-Platform (vários usos)" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "Campos raramente usados" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" +"Os campos nesta seção são raramente usados atualmente, já que seu design foi " +"inspirado por mecanismos comparáveis em sistemas de gerenciamento de pacotes " +"Linux, e não está claro como as ferramentas devem interpretá-los no contexto " +"de um servidor de indexação aberto, como `PyPI `__." + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" +"Como resultado, as ferramentas de instalação populares os ignoram " +"completamente, o que significa que há pouco incentivo para os editores de " +"pacotes configurá-los apropriadamente. No entanto, eles são retidos na " +"especificação de metadados, pois ainda são potencialmente úteis para fins " +"informativos e também podem ser usados para o propósito originalmente " +"pretendido em combinação com um repositório de pacotes com curadoria." + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "Provides-Dist (vários usos)" + +#: ../source/specifications/core-metadata.rst:847 +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 "" +"Cada entrada contém uma string nomeando um projeto Distutils que está " +"contido nesta distribuição. Este campo *deve* incluir o projeto identificado " +"no campo ``Name``, seguido da versão: Nome (Versão)." + +#: ../source/specifications/core-metadata.rst:852 +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 "" +"Uma distribuição pode fornecer nomes adicionais, por exemplo, para indicar " +"que vários projetos foram agrupados. Por exemplo, distribuições de código-" +"fonte do projeto ``ZODB`` historicamente incluíram o projeto " +"``transaction``, que agora está disponível como uma distribuição separada. " +"Instalar tal distribuição de código-fonte satisfaz os requisitos para " +"``ZODB`` e ``transaction``." + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" +"Uma distribuição também pode fornecer um nome de projeto \"virtual\", que " +"não corresponde a nenhum projeto distribuído separadamente: tal nome pode " +"ser usado para indicar uma capacidade abstrata que pode ser fornecida por um " +"de vários projetos. Por exemplo, vários projetos podem fornecer ligações " +"*(bindings)* de RDBMS para uso por um determinado ORM: cada projeto pode " +"declarar que fornece ``ORM-bindings``, permitindo que outros projetos " +"dependam apenas de ter no máximo um deles instalado." + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" +"Uma declaração de versão pode ser fornecida e deve seguir as regras " +"descritas em :doc:`version-specifiers`. O número da versão da distribuição " +"estará implícito se nenhum for especificado." + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "Obsoletes-Dist (vários usos)" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" +"Cada entrada contém uma string que descreve a distribuição de um projeto " +"distutils que esta distribuição torna obsoleta, o que significa que os dois " +"projetos não devem ser instalados ao mesmo tempo." + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" +"Declarações de versão podem ser fornecidas. Os números de versão devem estar " +"no formato especificado em :doc:`version-specifiers`." + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" +"O uso mais comum deste campo será no caso de alteração do nome de um " +"projeto, por exemplo, Gorgon 2.3 é incluído no Torqued Python 1.0. Quando " +"você instala o Torqued Python, a distribuição Gorgon deve ser removida." + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "Campos descontinuados" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "Home-page" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "Uma string contendo a URL para a página da distribuição." + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "Download-URL" + +#: ../source/specifications/core-metadata.rst:947 +#, fuzzy +#| 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\".)" +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" +"Uma string contendo a URL a partir da qual esta versão da distribuição pode " +"ser baixada. (Isso significa que a URL não pode ser algo como \".../" +"BeagleVote-latest.tgz\", mas deve ser \".../BeagleVote-0.45.tgz\".)" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "Requires" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "em favor de ``Requires-Dist``" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" +"Cada entrada contém uma string descrevendo algum outro módulo ou pacote " +"requerido por este pacote." + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" +"O formato de uma string de requisito é idêntico ao de um nome de módulo ou " +"pacote utilizável com a instrução ``import``, opcionalmente seguida por uma " +"declaração de versão dentro de parênteses." + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" +"Uma declaração de versão é uma série de operadores condicionais e números de " +"versão, separados por vírgulas. Os operadores condicionais devem ser um dos " +"\"<\", \">\"', \"<=\", \">=\", \"=\", e \"!=\". Os números da versão devem " +"estar no formato aceito pela classe ``distutils.version.StrictVersion``: " +"dois ou três componentes numéricos separados por ponto, com uma tag \"pre-" +"release\" opcional no final que consiste na letra 'a' ou 'b' seguida de um " +"número. Os números da versão do exemplo são \"1.0\", \"2.3a2\", \"1.3.99\"." + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" +"Qualquer número de operadores condicionais pode ser especificado, por " +"exemplo, a string \">1.0, !=1.3.4, <2.0\" é uma declaração de versão válida." + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" +"Todos os seguintes são possíveis strings de requisito: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" +"Não há nenhuma lista canônica de quais strings devem ser usadas; a " +"comunidade Python é livre para escolher seus próprios padrões." + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "Provides" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "em favor de ``Provides-Dist``" + +#: ../source/specifications/core-metadata.rst:999 +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 "" +"Cada entrada contém uma string descrevendo um pacote ou módulo que será " +"fornecido por este pacote uma vez instalado. Essas strings devem " +"corresponder às usadas nos campos Requirements. Uma declaração de versão " +"pode ser fornecida (sem um operador de comparação); o número de versão do " +"pacote será implícito se nenhum for especificado." + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "Obsoletes" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "em favor de ``Obsoletes-Dist``" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" +"Cada entrada contém uma string descrevendo um pacote ou módulo que este " +"pacote torna obsoleta, o que significa que os dois projetos não devem ser " +"instalados ao mesmo tempo. Declarações de versão pode ser fornecidas." + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" +"O uso mais comum deste campo será no caso de alteração do nome de um " +"projeto, por exemplo, Gorgon 2.3 é incluído no Torqued Python 1.0. Quando " +"você instala o Torqued Python, o pacote Gorgon deve ser removido." + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +#, fuzzy +#| msgid "" +#| "This document describes the dependency specifiers format as originally " +#| "specified in :pep:`508`." +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" +"Este documento descreve o formato dos especificadores de dependência " +"conforme originalmente especificado na :pep:`508`." + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +#, fuzzy +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" +"Adicionada documentação para o campo ``Description-Content-Type``. " +"(:pr:`258`)" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "Adicionado o campo ``Dinâmico``." + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +#, fuzzy +#| msgid "Added the ``Dynamic`` field." +msgid "Added the ``License-Expression`` field." +msgstr "Adicionado o campo ``Dinâmico``." + +#: ../source/specifications/core-metadata.rst:1060 +#, fuzzy +#| msgid "Added the ``Dynamic`` field." +msgid "Added the ``License-File`` field." +msgstr "Adicionado o campo ``Dinâmico``." + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +#, fuzzy +#| msgid "" +#| "This document describes the dependency specifiers format as originally " +#| "specified in :pep:`508`." +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" +"Este documento descreve o formato dos especificadores de dependência " +"conforme originalmente especificado na :pep:`508`." + +#: ../source/specifications/core-metadata.rst:1068 +#, fuzzy +#| msgid "Added the ``Dynamic`` field." +msgid "Added the ``Import-Name`` field." +msgstr "Adicionado o campo ``Dinâmico``." + +#: ../source/specifications/core-metadata.rst:1069 +#, fuzzy +#| msgid "Added the ``Dynamic`` field." +msgid "Added the ``Import-Namespace`` field." +msgstr "Adicionado o campo ``Dinâmico``." + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "Marcação reStructuredText: https://docutils.sourceforge.io/" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" + +#: ../source/specifications/dependency-groups.rst:5 +#, fuzzy +#| msgid "Dependency Overrides" +msgid "Dependency Groups" +msgstr "Substitui dependências" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +#, fuzzy +#| msgid "Dependency Overrides" +msgid "Dependency Group Include" +msgstr "Substitui dependências" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +#, fuzzy +#| msgid "Package upload" +msgid "Package Building" +msgstr "Envio de pacotes" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +#, fuzzy +#| msgid "Installing Setuptools \"Extras\"" +msgid "Installing Dependency Groups & Extras" +msgstr "Instalando Setuptools \"extras\"" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +#, fuzzy +msgid "Validation and Compatibility" +msgstr "Compatibilidade da ABI" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +#, fuzzy +msgid "Reference Implementation" +msgstr "Tipos de documentação" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +#, fuzzy +#| msgid "" +#| "This document describes the dependency specifiers format as originally " +#| "specified in :pep:`508`." +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" +"Este documento descreve o formato dos especificadores de dependência " +"conforme originalmente especificado na :pep:`508`." + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "Especificadores de dependência" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" +"Este documento descreve o formato dos especificadores de dependência " +"conforme originalmente especificado na :pep:`508`." + +#: ../source/specifications/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 "" +"O trabalho de uma dependência é permitir que ferramentas como pip [#pip]_ " +"encontrem o pacote certo para instalar. Às vezes, isso é muito vago -- " +"apenas especificando um nome -- e, às vezes, muito específico -- referindo-" +"se a um arquivo específico a ser instalado. Às vezes, as dependências são " +"relevantes apenas em uma plataforma, ou apenas algumas versões são " +"aceitáveis, então a linguagem permite descrever todos esses casos." + +#: ../source/specifications/dependency-specifiers.rst:18 +#, fuzzy +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" +"A linguagem definida é um formato compacto baseado em linha que já está em " +"uso generalizado em arquivos de requisitos pip, embora não especifiquemos a " +"manipulação de opção de linha de comando que esses arquivos permitem. Há uma " +"ressalva: o formulário de referência de URL, especificado em :pep:`440`, não " +"é realmente implementado em pip, mas como :pep:`440` é aceito, usamos esse " +"formato em vez do formato nativo atual de pip." + +#: ../source/specifications/dependency-specifiers.rst:31 +msgid "All features of the language shown with a name based lookup::" +msgstr "" +"Todos os recursos do idioma mostrados com uma pesquisa baseada em nome ::" + +#: ../source/specifications/dependency-specifiers.rst:35 +msgid "A minimal URL based lookup::" +msgstr "Uma pesquisa baseada em URL mínima ::" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "Conceitos" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" +"Uma especificação de dependência sempre especifica um nome de distribuição. " +"Pode incluir extras, que expandem as dependências da distribuição nomeada " +"para habilitar recursos opcionais. A versão instalada pode ser controlada " +"usando limites de versão ou fornecendo a URL para um artefato específico " +"para instalação. Finalmente, a dependência pode ser condicionada usando " +"marcadores de ambiente." + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "Gramática" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" +"Primeiro, abordamos brevemente a gramática e, posteriormente, detalhamos a " +"semântica de cada seção." + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" +"Uma especificação de distribuição é escrita em texto ASCII. Usamos uma " +"gramática de parsley [#parsley]_ para fornecer uma gramática precisa. Espera-" +"se que a especificação seja incorporada a um sistema maior que ofereça " +"enquadramento, como comentários, suporte a várias linhas por meio de " +"continuações ou outros recursos semelhantes." + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" +"A gramática completa, incluindo anotações para construir uma árvore de " +"análise útil, está incluída no final deste documento." + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" +"As versões podem ser especificadas de acordo com as regras " +"da :ref:`especificação de especificadores de versão `. " +"(Nota: URI é definido em :rfc:`std-66 <3986>`)::" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" +"Os marcadores de ambiente permitem que uma especificação só tenha efeito em " +"alguns ambientes ::" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" +"Componentes opcionais de uma distribuição podem ser especificados usando o " +"campo extras::" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "Restrições de nomes para extras são definidas na :pep:`685`." + +#: ../source/specifications/dependency-specifiers.rst:113 +msgid "Giving us a rule for name based requirements::" +msgstr "Fornecendo uma regra para requisitos baseados em nome ::" + +#: ../source/specifications/dependency-specifiers.rst:117 +msgid "And a rule for direct reference specifications::" +msgstr "E uma regra para especificações de referência direta ::" + +#: ../source/specifications/dependency-specifiers.rst:121 +msgid "Leading to the unified rule that can specify a dependency.::" +msgstr "Levando à regra unificada que pode especificar uma dependência.::" + +#: ../source/specifications/dependency-specifiers.rst:126 +msgid "Whitespace" +msgstr "Espaço em branco" + +#: ../source/specifications/dependency-specifiers.rst:128 +msgid "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" +"O espaço em branco sem quebra de linha é principalmente opcional, sem " +"significado semântico. A única exceção é detectar o fim de um requisito de " +"URL." + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "Nomes" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" +"Nomes de distribuição Python são atualmente definidos na :pep:`345`. Os " +"nomes atuam como o identificador primário para distribuições. Eles estão " +"presentes em todas as especificações de dependência e são suficientes para " +"serem uma especificação por conta própria. No entanto, PyPI impõe restrições " +"estritas aos nomes: eles devem corresponder a uma regex que não diferencie " +"maiúsculas de minúsculas ou não serão aceitos. Assim, neste documento, " +"limitamos os valores aceitáveis para identificadores a essa regex. Uma " +"redefinição completa do nome pode ocorrer em um futuro PEP de metadados. A " +"regex (executada com re.IGNORECASE) é ::" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "Extras" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" +"Um extra é uma parte opcional de uma distribuição. As distribuições podem " +"especificar quantos extras desejarem, e cada extra resulta na declaração de " +"dependências adicionais da distribuição **quando** o extra é usado em uma " +"especificação de dependência. Por exemplo ::" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" +"União de extras nas dependências que definem com as dependências da " +"distribuição à qual estão anexados. O exemplo acima resultaria na instalação " +"de solicitações e nas próprias dependências das solicitações, além de " +"quaisquer dependências listadas no extra de \"security\" das solicitações." + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "Se vários extras forem listados, todas as dependências serão unidas." + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "Versões" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" +"Consulte a :ref:`especificação de especificadores de versão ` para obter mais detalhes sobre números de versão e comparações " +"de versões. As especificações de versão limitam as versões de uma " +"distribuição que podem ser usadas. Elas se aplicam apenas a distribuições " +"pesquisadas pelo nome, e não por meio de uma URL. A comparação de versões " +"também é usada no recurso de marcadores. Os colchetes opcionais em torno de " +"uma versão estão presentes para compatibilidade com :pep:`345`, mas não " +"devem ser gerados, apenas aceitos." + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "Marcadores de ambiente" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" +"Os marcadores de ambiente permitem que uma especificação de dependência " +"forneça uma regra que descreva quando a dependência deve ser usada. Por " +"exemplo, considere um pacote que precisa de argparse. No Python 2.7, o " +"argparse está sempre presente. Em versões mais antigas Python, ele deve ser " +"instalado como uma dependência. Isso pode ser expresso como ::" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" +"Uma expressão de marcador é avaliada como True ou False. Quando for avaliado " +"como False, a especificação de dependência deve ser ignorada." + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" +"A linguagem do marcador é inspirada no próprio Python, escolhido pela " +"capacidade de avaliá-lo com segurança sem executar código arbitrário que " +"pode se tornar uma vulnerabilidade de segurança. Os marcadores foram " +"padronizados pela primeira vez na :pep:`345`. Este documento corrige alguns " +"problemas que foram observados no projeto descrito em :pep:`426`." + +#: ../source/specifications/dependency-specifiers.rst:199 +#, fuzzy +#| msgid "" +#| "Comparisons in marker expressions are typed by the comparison operator. " +#| "The operators that are not in perform the same " +#| "as they do for strings in Python. The operators use the " +#| "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::" +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" +"As comparações em expressões de marcador são tipadas pelo operador de " +"comparação. Os operadores que não estão em fazem o " +"mesmo que para strings no Python. Os operadores usam as regras " +"de comparação de versão da :ref:`especificação de especificadores de versão " +"` quando são definidas (ou seja, quando ambos os lados " +"têm um especificador de versão válido). Se não houver comportamento definido " +"desta especificação e o operador existir no Python, o operador voltará ao " +"comportamento do Python. Caso contrário, um erro deve ser levantado. Por " +"exemplo, o seguinte resultará em erros ::" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" +"As constantes fornecidas pelo usuário são sempre codificadas como strings " +"com as aspas ``'`` ou ``\"``. Observe que os escapes de barra invertida não " +"são definidos, mas as implementações existentes os suportam. Eles não estão " +"incluídos nesta especificação porque adicionam complexidade e não há nenhuma " +"necessidade observável para eles hoje.Da mesma forma, não definimos suporte " +"a caracteres não-ASCII: espera-se que todas as variáveis de tempo de " +"execução às quais nos referimos sejam somente ASCII." + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" +"As variáveis na gramática do marcador, como \"os_name\", resolvem os valores " +"pesquisados no tempo de execução do Python. Com exceção de \"extra\" todos " +"os valores são definidos em todas as versões Python hoje -- é um erro na " +"implementação de marcadores se um valor não for definido." + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" +"Variáveis desconhecidas devem gerar um erro em vez de resultar em uma " +"comparação avaliada como True ou False." + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" +"As variáveis cujo valor não pode ser calculado em uma determinada " +"implementação do Python devem ser avaliadas como ``0`` para versões e uma " +"string vazia para todas as outras variáveis." + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" +"A variável \"extra\" é especial. É usada pelo wheels para sinalizar quais " +"especificações se aplicam a um determinado extra no arquivo ``METADATA`` do " +"wheel, mas como o arquivo ``METADATA`` é baseado em uma versão de rascunho " +"da :pep:`426`, não há especificação atual para isso. Independentemente " +"disso, fora de um contexto em que esse tratamento especial esteja ocorrendo, " +"a variável \"extra\" deve resultar em um erro como todas as outras variáveis " +"desconhecidas." + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "Marcador" + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "Equivalente no Python" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "Valores de amostra" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "``os_name``" + +#: ../source/specifications/dependency-specifiers.rst:252 +#, fuzzy +msgid ":py:data:`os.name`" +msgstr "``os.name``" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "``posix``, ``java``" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "``sys_platform``" + +#: ../source/specifications/dependency-specifiers.rst:256 +#, fuzzy +msgid ":py:data:`sys.platform`" +msgstr "``sys.platform``" + +#: ../source/specifications/dependency-specifiers.rst:258 +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`` (observe que \"linux\" é " +"do Python3 e \"linux2\" do Python2)" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "``platform_machine``" + +#: ../source/specifications/dependency-specifiers.rst:261 +#, fuzzy +msgid ":py:func:`platform.machine()`" +msgstr "``platform.machine()``" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "``x86_64``" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "``platform_python_implementation``" + +#: ../source/specifications/dependency-specifiers.rst:265 +#, fuzzy +msgid ":py:func:`platform.python_implementation()`" +msgstr "``platform.python_implementation()``" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "``CPython``, ``Jython``" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "``platform_release``" + +#: ../source/specifications/dependency-specifiers.rst:269 +#, fuzzy +msgid ":py:func:`platform.release()`" +msgstr "``platform.release()``" + +#: ../source/specifications/dependency-specifiers.rst:271 +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/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "``platform_system``" + +#: ../source/specifications/dependency-specifiers.rst:273 +#, fuzzy +msgid ":py:func:`platform.system()`" +msgstr "``platform.system()``" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "``Linux``, ``Windows``, ``Java``" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "``platform_version``" + +#: ../source/specifications/dependency-specifiers.rst:277 +#, fuzzy +msgid ":py:func:`platform.version()`" +msgstr "``platform.version()``" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "``python_version``" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "``'.'.join(platform.python_version_tuple()[:2])``" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +#, fuzzy +#| msgid "Version specifiers" +msgid ":ref:`Version `" +msgstr "Especificadores de versão" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "``3.4``, ``2.7``" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "``python_full_version``" + +#: ../source/specifications/dependency-specifiers.rst:287 +#, fuzzy +msgid ":py:func:`platform.python_version()`" +msgstr "``platform.python_version()``" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "``3.4.0``, ``3.5.0b1``" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "``implementation_name``" + +#: ../source/specifications/dependency-specifiers.rst:291 +#, fuzzy +msgid ":py:data:`sys.implementation.name `" +msgstr "``sys.implementation.name``" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "``cpython``" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "``implementation_version``" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "veja a definição abaixo" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "``extra``" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" +"Um erro, exceto quando definido pelo contexto que interpreta a especificação." + +#: ../source/specifications/dependency-specifiers.rst:302 +#, fuzzy +msgid "``toml``" +msgstr "pyproject.toml" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +#, fuzzy +#| msgid "``extra``" +msgid "``extras``" +msgstr "``extra``" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +#, fuzzy +#| msgid "``dependencies``" +msgid "``dependency_groups``" +msgstr "``dependencies``" + +#: ../source/specifications/dependency-specifiers.rst:312 +#, fuzzy +#| msgid "``test``" +msgid "``{\"test\"}``" +msgstr "``test``" + +#: ../source/specifications/dependency-specifiers.rst:314 +#, fuzzy +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" +"A variável do marcador ``implementation_version`` é derivada de " +"``sys.implementation.version``::" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" +"Esta seção de marcadores de ambiente, inicialmente definida na :pep:`508`, " +"substitui a seção de marcadores de ambiente na :pep:`345`." + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "Gramática completa" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "A gramática completa do persley ::" + +#: ../source/specifications/dependency-specifiers.rst:446 +#, fuzzy +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" +"Um programa de teste -- se a gramática estiver em uma string ``grammar``::" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +#, fuzzy +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]_" +msgstr "" +"A definição de ``python_version`` foi alterada de ``platform.python_version()" +"[:3]`` para ``'.'.join(platform.python_version_tuple()[:2])``, para acomodar " +"potenciais futuras versões do Python com versões principais e secundárias de " +"2 dígitos (por exemplo, 3.10). [#future_versions]_" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" +"pip, o instalador recomendado para pacotes Python (http://" +"pip.readthedocs.org/en/stable/)" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" +"A biblioteca de PEG do parsley. (https://pypi.python.org/pypi/parsley/)" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" +"Versões futuras do Python podem ser problemáticas com a definição da " +"variável do marcador de ambiente ``python_version`` (https://github.com/" +"python/peps/issues/560)" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "Gravando a Origem da URL Direta de distribuições instaladas" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" +"Este documento especifica um arquivo :file:`direct_url.json` no diretório " +"``*.dist-info`` de uma distribuição instalada, para registrar a origem da " +"URL direta da distribuição. A estrutura geral e uso de diretórios ``*.dist-" +"info`` é descrita em :ref:`recording-installed-packages`." + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" +"O arquivo :file:`direct_url.json` DEVE ser criado no diretório :file:`*.dist-" +"info` pelos instaladores ao instalar uma distribuição a partir de um " +"requisito especificando uma referência de URL direta (incluindo uma URL de " +"VCS)." + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" +"Este arquivo NÃO DEVE ser criado ao instalar uma distribuição de outro tipo " +"de requisito (ou seja, nome mais especificador de versão)." + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" +"Este arquivo JSON DEVE ser codificado em UTF-8, compatível com :rfc:`8259`, " +"serialização da :doc:`direct-url-data-structure`." + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" +"Quando a URL solicitada tem o esquema file:// e aponta para um diretório " +"local que contém um checkout VCS, os instaladores NÃO DEVEM tentar inferir " +"nenhuma informação VCS e, portanto, NÃO DEVEM emitir nenhuma informação " +"relacionada ao VCS (como ``vcs_info``) in :file:`direct_url.json`." + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" +"Como regra geral, os instaladores devem, tanto quanto possível, preservar as " +"informações fornecidas na URL solicitada ao gerar :file:`direct_url.json`. " +"Por exemplo, as variáveis de ambiente usuário:senha devem ser preservadas e " +"``required_revision`` deve refletir a revisão que foi fornecida na URL " +"solicitada o mais fielmente possível. No entanto, essas informações são " +"*enriquecidas* com dados mais precisos, como ``commit_id``." + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "Exemplo de comandos pip e seus efeitos em direct_url.json" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "Comandos que geram um ``direct_url.json``:" + +#: ../source/specifications/direct-url.rst:49 +#, fuzzy +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "pip install https://example.com/app-1.0.tgz" + +#: ../source/specifications/direct-url.rst:50 +#, fuzzy +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "pip install https://example.com/app-1.0.whl" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``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 +#, fuzzy +msgid "``pip install ./app``" +msgstr "pip install ./app" + +#: ../source/specifications/direct-url.rst:53 +#, fuzzy +msgid "``pip install file:///home/user/app``" +msgstr "pip install file:///home/user/app" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (caso em que, ``url`` será o diretório local " +"para o qual o repositório git foi clonado e ``dir_info`` estará presente com " +"``\"editable\": true`` e nenhum ``vcs_info`` será definido)" + +#: ../source/specifications/direct-url.rst:58 +#, fuzzy +msgid "``pip install -e ./app``" +msgstr "pip install -e ./app" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "Comandos que *não* geram um ``direct_url.json``" + +#: ../source/specifications/direct-url.rst:62 +#, fuzzy +msgid "``pip install app``" +msgstr "pip install app" + +#: ../source/specifications/direct-url.rst:63 +#, fuzzy +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "pip install app --no-index --find-links https://example.com/" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "Estrutura de dados de URL direta" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" +"Este documento especifica uma estrutura de dados abstrata serializável em " +"JSON que pode representar URLs para projetos python e artefatos de " +"distribuição, como árvores de fonte VCS, árvores de fonte local, " +"distribuições fonte e wheels." + +#: ../source/specifications/direct-url-data-structure.rst:13 +#, fuzzy +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 " +"`." +msgstr "" +"A representação dos componentes desta estrutura de dados como uma " +"URL :rfc:`1738` não é especificada formalmente no momento da escrita. Uma " +"representação comum é o formato de URL do pip. Outros exemplos são " +"fornecidos na :ref:`especificação de especificadores de versão `." + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" +"A estrutura de dados da URL direta DEVE ser um dicionário serializável para " +"JSON de acordo com :rfc:`8259`." + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:28 +#, fuzzy +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 "" +"DEVE conter pelo menos dois campos. O primeiro é ``url``, com tipo " +"``string``. Dependendo de qual ``url`` se refere, o segundo campo DEVE ser " +"um de ``vcs_info`` (se ``url`` é uma referência de VCS), ``archive_info`` " +"(se ``url`` é um pacote de código-fonte ou um wheel) ou ``dir_info`` (se " +"``url`` é um diretório local). Estes campos informacionais têm um " +"subdicionário (possivelmente vazio) como valor, com as chaves possíveis " +"definidas abaixo." + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" +"Quando persistido, ``url`` DEVE ser podado a fim de retirar qualquer " +"informação sensível de autenticação, por razões de segurança." + +#: ../source/specifications/direct-url-data-structure.rst:40 +#, fuzzy +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" +"A seção usuário:senha da URL PODE, entretanto, ser composta de variáveis de " +"ambiente, correspondendo à seguinte expressão regular::" + +#: ../source/specifications/direct-url-data-structure.rst:48 +#, fuzzy +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" +"Além disso, a seção usuário:senha da URL PODE ser uma string bem conhecida e " +"não sensível à segurança. Um exemplo típico é ``git`` no caso de uma URL " +"como ``ssh://git@gitlab.com/user/repo``." + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "URLs de VCS" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" +"Quando a ``url`` faz referência a um repositório VCS, a chave ``vcs_info`` " +"DEVE estar presente como um dicionário com as seguintes chaves:" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" +"Uma chave ``vcs`` (tipo ``string``) DEVE estar presente, contendo o nome do " +"VCS (ou seja, um de ``git``, ``hg``, ``bzr``, ``svn``). Outros VCS DEVERIAM " +"ser registrados escrevendo uma PEP para alterar esta especificação. O valor " +"``url`` DEVE ser compatível com o VCS correspondente, para que um instalador " +"possa entregá-lo sem transformação em um comando de checkout/download do VCS." + +#: ../source/specifications/direct-url-data-structure.rst:66 +#, 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). " +"This field MUST match the revision requested by the user and MUST NOT exist " +"when the user did not select a specific revision." +msgstr "" +"Uma chave ``required_revision`` (tipo ``string``) PODE estar presente " +"nomeando um branch/tag/ref/commit/revisão/etc (em um formato compatível com " +"o VCS) para instalar." + +#: ../source/specifications/direct-url-data-structure.rst:70 +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 "" +"Uma chave ``commit_id`` (tipo ``string``) DEVE estar presente, contendo o " +"número exato de commit/revisão que foi/será instalado. Se o VCS oferecer " +"suporte a identificadores de revisão baseados em hash de commit, tal hash de " +"commit DEVE ser usado como ``commit_id`` para referenciar a versão imutável " +"do código-fonte." + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "URLs de arquivos" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" +"Quando ``url`` se refere a um arquivo fonte ou wheel, a chave " +"``archive_info`` DEVE estar presente como um dicionário com as seguintes " +"chaves:" + +#: ../source/specifications/direct-url-data-structure.rst:85 +msgid "" +"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " +"hex encoded digest of the file." +msgstr "" +"Uma chave ``hashes`` DEVE estar presente como um dicionário mapeando um nome " +"de hash para um resumo de arquivo codificado em hex." + +#: ../source/specifications/direct-url-data-structure.rst:88 +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 "" +"Vários hashes podem ser incluídos e cabe ao consumidor decidir o que fazer " +"com vários hashes (pode validar todos eles ou um subconjunto deles, ou nada)." + +#: ../source/specifications/direct-url-data-structure.rst:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" +"Esses nomes de hash DEVEM sempre ser normalizados para letras minúsculas." + +#: ../source/specifications/direct-url-data-structure.rst:94 +#, fuzzy +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." +msgstr "" +"Qualquer algoritmo de hash disponível via ``hashlib`` (especificamente " +"qualquer um que possa ser passado para ``hashlib.new()`` e não requeira " +"parâmetros adicionais) pode ser usado como uma chave para o dicionário de " +"hashes. Pelo menos um algoritmo seguro de ``hashlib.algorithms_guaranteed`` " +"DEVE sempre ser incluído. No momento da escrita, ``sha256`` especificamente " +"é recomendado." + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" +"Uma chave descontinuada ``hash`` (tipo ``string``) PODE estar presente para " +"fins de compatibilidade com versões anteriores, com valor ``=``." + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" +"Os produtores da estrutura de dados DEVEM emitir a chave ``hashes`` se um ou " +"vários hashes estiverem disponíveis. Os produtores DEVEM continuar a emitir " +"a chave ``hash`` em contextos onde o faziam antes, de modo a manter a " +"compatibilidade com versões anteriores para clientes existentes." + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" +"Quando as chaves ``hash`` e ``hashes`` estão presentes, o hash representado " +"na chave ``hash`` DEVE também estar presente no dicionário ``hashes``, para " +"que os consumidores possam considerar a chave ``hashes`` apenas se estiver " +"presente, e voltar para ``hash`` caso contrário." + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "Diretórios locais" + +#: ../source/specifications/direct-url-data-structure.rst:116 +msgid "" +"When ``url`` refers to a local directory, the ``dir_info`` key MUST be " +"present as a dictionary with the following key:" +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:119 +msgid "" +"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " +"installed in editable mode, ``false`` otherwise. If absent, default to " +"``false``." +msgstr "" +"``editable`` (tipo: ``boolean``): ``true`` se a distribuição foi/será " +"instalada em modo editável, ``false`` caso contrário. Se ausente, é usado o " +"padrão ``false``." + +#: ../source/specifications/direct-url-data-structure.rst:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" +"Quando ``url`` se refere a um diretório local, ele DEVE ter o esquema " +"``file`` e ser compatível com :rfc:`8089` Em particular, o componente do " +"caminho deve ser absoluto. Links simbólicos DEVERIAM ser preservados ao " +"tornar os caminhos relativos absolutos." + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "Projetos em subdiretórios" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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 "" +"Um campo ``subdirectory`` de nível superior PODE estar presente contendo um " +"caminho de diretório, relativo à raiz do repositório VCS, arquivo fonte ou " +"diretório local, para especificar onde ``pyproject.toml`` ou ``setup.py`` " +"está localizado." + +#: ../source/specifications/direct-url-data-structure.rst:139 +msgid "Registered VCS" +msgstr "VCS registrados" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" +"Esta seção lista os VCS registrados; expandidos, informações específicas do " +"VCS sobre como usar ``vcs``, ``required_revision`` e outros campos de " +"``vcs_info``; e, em alguns casos, campos adicionais específicos de VCS. As " +"ferramentas PODEM oferecer suporte a outros VCS, embora seja RECOMENDADO " +"registrá-las escrevendo uma PEP para alterar esta especificação. O campo " +"``vcs`` DEVERIA ser o nome do comando (em letras minúsculas). Os campos " +"adicionais que seriam necessários para oferecer suporte a esse VCS DEVERIAM " +"ser prefixados com o nome do comando VCS." + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "Git" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "Site" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "https://git-scm.com/" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "Comando vcs" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "git" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "Campo ``vcs``" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "Campo ``requested_revision``" + +#: ../source/specifications/direct-url-data-structure.rst:163 +msgid "" +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "Campo ``commit_id``" + +#: ../source/specifications/direct-url-data-structure.rst:167 +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:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" +"As ferramentas podem usar os comandos ``git show-ref`` e ``git symbolic-" +"ref`` para determinar se o ``required_revision`` corresponde a um ref Git. " +"Por sua vez, um ref começando com ``refs/tags/`` corresponde a uma tag, e um " +"ref começando com ``refs/remotes/origin/`` após a clonagem corresponde a um " +"branch." + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "Mercurial" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "https://www.mercurial-scm.org/" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "hg" + +#: ../source/specifications/direct-url-data-structure.rst:190 +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:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "Um ID de changeset (40 caracteres hexadecimais)." + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "Bazaar" + +#: ../source/specifications/direct-url-data-structure.rst:199 +#, fuzzy +msgid "https://www.breezy-vcs.org/" +msgstr "https://www.mercurial-scm.org/" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "bzr" + +#: ../source/specifications/direct-url-data-structure.rst:208 +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:211 +msgid "A revision id." +msgstr "Um id de revisão." + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "svn" + +#: ../source/specifications/direct-url-data-structure.rst:226 +msgid "" +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." +msgstr "" +"``requested_revision`` deve ser compatível com a opção ``--revision`` do " +"``svn checkout``. No Subversion, branch ou tag é parte de ``url``." + +#: ../source/specifications/direct-url-data-structure.rst:230 +msgid "" +"Since Subversion does not support globally unique identifiers, this field is " +"the Subversion revision number in the corresponding repository." +msgstr "" +"Visto que o Subversion não oferece suporte a identificadores globalmente " +"únicos, este campo é o número da revisão do Subversion no repositório " +"correspondente." + +#: ../source/specifications/direct-url-data-structure.rst:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "Arquivo fonte:" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "URL Git com tag e hash de commit:" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "Diretório local:" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "Diretório local em modo editável:" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +#, fuzzy +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" +"Janeiro de 2023: Adicionada a chave ``archive_info.hashes`` (`discussão " +"`__)." + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "Especificação de pontos de entrada" + +#: ../source/specifications/entry-points.rst:7 +msgid "" +"*Entry points* are a mechanism for an installed distribution to advertise " +"components it provides to be discovered and used by other code. For example:" +msgstr "" +"*Pontos de entrada* são um mecanismo para uma distribuição instalada " +"anunciar componentes que ela fornece para serem descobertos e usados por " +"outro código. Por exemplo:" + +#: ../source/specifications/entry-points.rst:11 +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 "" +"As distribuições podem especificar pontos de entrada ``console_scripts``, " +"cada um referindo-se a uma função. Quando *pip* (ou outro instalador " +"compatível com console_scripts) instala a distribuição, ele cria um wrapper " +"de linha de comando para cada ponto de entrada." + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" +"As aplicações podem usar pontos de entrada para carregar plug-ins; por " +"exemplo, Pygments (uma ferramenta de realce de sintaxe) pode usar lexers e " +"estilos adicionais de pacotes instalados separadamente. Para mais " +"informações, consulte :doc:`/guides/creating-and-discovering-plugins`." + +#: ../source/specifications/entry-points.rst:19 +#, fuzzy +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 "" +"O formato de arquivo de ponto de entrada foi originalmente desenvolvido para " +"permitir que pacotes construídos com setuptools forneçam metadados de ponto " +"de integração que seriam lidos em tempo de execução com " +"``importlib.metadata``. Ele agora é definido como uma especificação de " +"interoperabilidade PyPA a fim de permitir que outras ferramentas de " +"construção além do setuptools publiquem metadados de ponto de entrada " +"compatíveis com ``importlib.metadata`` e bibliotecas de tempo de execução " +"diferentes de ``importlib.metadata`` para ler portavelmente publicado " +"metadados de ponto de entrada (potencialmente com diferentes estratégias de " +"cache e resolução de conflitos)." + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "Modelo de dados" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" +"Conceitualmente, um ponto de entrada é definido por três propriedades " +"necessárias:" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" +"O **grupo** ao qual um ponto de entrada pertence indica que tipo de objeto " +"ele fornece. Por exemplo, o grupo ``console_scripts`` é para pontos de " +"entrada referentes a funções que podem ser usadas como um comando, enquanto " +"``pygments.styles`` é o grupo para classes que definem estilos de pigmentos. " +"O consumidor normalmente define a interface esperada. Para evitar conflitos, " +"os consumidores que definem um novo grupo devem usar nomes começando com um " +"nome PyPI pertencente ao projeto do consumidor, seguido por ``.``. Os nomes " +"dos grupos devem ser um ou mais grupos de letras, números e sublinhados, " +"separados por pontos (regex ``^\\w+(\\.\\w+)*$``)." + +#: ../source/specifications/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 "" +"O **nome** identifica este ponto de entrada em seu grupo. O significado " +"preciso disso depende do cliente. Para scripts de console, o nome do ponto " +"de entrada é o comando que será usado para iniciá-lo. Em uma distribuição, " +"os nomes dos pontos de entrada devem ser exclusivos. Se distribuições " +"diferentes fornecerem o mesmo nome, o consumidor decide como lidar com tais " +"conflitos. O nome pode conter quaisquer caracteres, exceto ``=``, mas não " +"pode começar ou terminar com nenhum caractere de espaço em branco, ou " +"começar com ``[``. Para novos pontos de entrada, é recomendado usar apenas " +"letras, números, sublinhados, pontos e travessões (regex ``[\\w.-]+``)." + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" +"A **referência de objeto** aponta para um objeto Python. Ele está no formato " +"``importable.module`` ou ``importable.module:object.attr``. Cada uma das " +"partes delimitadas por pontos e dois pontos é um identificador válido " +"Python. Destina-se a ser consultado assim::" + +#: ../source/specifications/entry-points.rst:64 +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 "" +"Algumas ferramentas chamam esse tipo de referência de objeto por si só de " +"\"ponto de entrada\", por falta de um termo melhor, especialmente quando " +"aponta para uma função para iniciar um programa." + +#: ../source/specifications/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" +"Há também uma propriedade opcional: os **extras** são um conjunto de strings " +"que identifica recursos opcionais da distribuição que fornece o ponto de " +"entrada. Se forem especificados, o ponto de entrada requer as dependências " +"desses 'extras'. Veja o campo de metadados :ref:`metadata_provides_extra`." + +#: ../source/specifications/entry-points.rst:73 +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 "" +"Usar extras para um ponto de entrada não é mais recomendado. Os consumidores " +"devem oferecer suporte para analisá-los em distribuições existentes, mas " +"podem então ignorá-los. Novas ferramentas de publicação não precisam " +"suportar especificações extras. A funcionalidade de manipulação de extras " +"estava ligada ao modelo do setuptools de gerenciamento de pacotes \"egg\", " +"mas as ferramentas mais recentes, como pip e virtualenv, usam um modelo " +"diferente." + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "Formato de arquivo" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" +"Os pontos de entrada são definidos em um arquivo " +"chamado :file:`entry_points.txt` no diretório :file:`*.dist-info` da " +"distribuição. Este é o diretório descrito em :ref:`recording-installed-" +"packages` para distribuições instaladas e em :ref:`binary-distribution-" +"format` para wheels. O arquivo usa a codificação de caracteres UTF-8." + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" +"O conteúdo do arquivo está no formato INI, conforme lido pelo " +"módulo :mod:`configparser` do Python. No entanto, o configparser trata os " +"nomes como não diferenciando maiúsculas de minúsculas por padrão, enquanto " +"os nomes de pontos de entrada diferenciam maiúsculas de minúsculas. Um " +"analisador de configuração com distinção entre maiúsculas e minúsculas pode " +"ser feito assim::" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" +"O arquivo de pontos de entrada deve sempre usar ``=`` para delimitar nomes " +"de valores (enquanto o configparser também permite o uso de ``:``)." + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" +"As seções do arquivo de configuração representam grupos de pontos de " +"entrada, os nomes são nomes e os valores codificam a referência do objeto e " +"os extras opcionais. Se extras forem usados, eles serão uma lista separada " +"por vírgulas entre colchetes." + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" +"Dentro de um valor, os leitores devem aceitar e ignorar os espaços " +"(incluindo vários espaços consecutivos) antes ou depois dos dois pontos, " +"entre a referência do objeto e o colchete esquerdo, entre os nomes extras e " +"os colchetes e dois pontos que os delimitam, e depois do quadrado direito " +"suporte. A sintaxe para extras é formalmente especificada como parte " +"da :pep:`508` (como ``extras``) e restrições em valores especificados " +"na :pep:`685`. Para ferramentas de gravação de arquivo, é recomendável " +"inserir apenas um espaço entre a referência do objeto e o colchete esquerdo." + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "Uso para scripts" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" +"Dois grupos de pontos de entrada têm um significado especial no " +"empacotamento: ``console_scripts`` e ``gui_scripts``. Em ambos os grupos, o " +"nome do ponto de entrada deve ser usado como um comando em um shell do " +"sistema após a instalação do pacote. A referência do objeto aponta para uma " +"função que será chamada sem argumentos quando este comando for executado. A " +"função pode retornar um inteiro para ser usado como um código de saída do " +"processo, e retornar ``None`` é equivalente a retornar ``0``." + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" +"Por exemplo, o ponto de entrada ``mycmd = mymod:main`` criaria um comando " +"``mycmd`` lançando um script como este::" + +#: ../source/specifications/entry-points.rst:145 +#, fuzzy +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 "" +"A diferença entre ``console_scripts`` e ``gui_scripts`` afeta apenas os " +"sistemas Windows. ``console_scripts`` são empacotados em um executável de " +"console, então eles são anexados a um console e podem usar ``sys.stdin``, " +"``sys.stdout`` e ``sys.stderr`` para entrada e saída. ``gui_scripts`` são " +"empacotados em um executável GUI, então eles podem ser iniciados sem um " +"console, mas não podem usar streams padrão a menos que o código da aplicação " +"os redirecione. Outras plataformas não têm a mesma distinção." + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" +"Espera-se que as ferramentas de instalação configurem wrappers para " +"``console_scripts`` e ``gui_scripts`` no diretório de scripts do esquema de " +"instalação. Eles não são responsáveis por colocar este diretório na variável " +"de ambiente ``PATH`` que define onde as ferramentas de linha de comando são " +"encontradas." + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" +"Como os arquivos são criados a partir dos nomes e alguns sistemas de " +"arquivos não fazem distinção entre maiúsculas e minúsculas, os pacotes devem " +"evitar o uso de nomes nesses grupos que diferem apenas em maiúsculas e " +"minúsculas. O comportamento das ferramentas de instalação quando os nomes " +"diferem apenas no caso de ser indefinido." + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "Ambiente gerenciado externamente" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" +"Embora algumas instalações do Python sejam totalmente gerenciadas pelo " +"usuário que instalou o Python, outras podem ser fornecidas e gerenciadas por " +"outros meios (como o gerenciador de pacotes do sistema operacional em uma " +"distribuição Linux ou como um ambiente integrado Python em um aplicativo com " +"um instalador dedicado)." + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" +"A tentativa de usar ferramentas de empacotamento convencionais Python para " +"manipular esses ambientes pode ser confusa, na melhor das hipóteses, e, na " +"pior das hipóteses, quebrar completamente todo o sistema operacional " +"subjacente. Os guias de documentação e interoperabilidade passam longe da " +"resolução de tais problemas." + +#: ../source/specifications/externally-managed-environments.rst:18 +#, fuzzy +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" +"A :pep:`668` definiu um arquivo marcador ``EXTERNALLY-MANAGED`` que permite " +"que uma instalação do Python indique para ferramentas específicas do Python, " +"como ``pip``, que eles não instalam nem removem pacotes no ambiente de " +"instalação padrão do interpretador, e deve orientar o usuário final para " +"usar :ref:`virtual-environments`." + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "Terminologia" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +#, fuzzy +msgid "distro" +msgstr "distribution" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +#, fuzzy +msgid "package" +msgstr "empacotamento" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +#, fuzzy +msgid "Python-specific package manager" +msgstr "O gerenciador de pacotes multiplataforma conda" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +#, fuzzy +msgid "distro package manager" +msgstr "Instaladores e gerenciadores de pacote para macOS" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A 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/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "sombra" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +#, fuzzy +msgid "This specification is twofold." +msgstr "Especificações do PyPA" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "Recomendações para distribuições" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +#, fuzzy +msgid "Guide users towards virtual environments" +msgstr "Ativando um ambiente virtual" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +#, fuzzy +msgid "Implementation Notes" +msgstr "Tipos de documentação" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +#, fuzzy +msgid "``pip install``" +msgstr "pip install app" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +#, fuzzy +msgid "``pip install --prefix=/some/path``" +msgstr "pip install -e ./app" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "Chame ``sysconfig.get_preferred_scheme('prefix')``." + +#: ../source/specifications/externally-managed-environments.rst:428 +#, fuzzy +msgid "``pip install --user``" +msgstr "pip install -e ./app" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "Chame ``sysconfig.get_preferred_scheme('user')``." + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "Diretos autorais" + +#: ../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/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +#, fuzzy +#| msgid "" +#| "This document describes the dependency specifiers format as originally " +#| "specified in :pep:`508`." +msgid "This specification was originally defined in :pep:`592`." +msgstr "" +"Este documento descreve o formato dos especificadores de dependência " +"conforme originalmente especificado na :pep:`508`." + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +#, fuzzy +msgid "Installers" +msgstr "Instalador" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +#, fuzzy +msgid "Reference implementation in Python" +msgstr "Tipos de documentação" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "Especificações do PyPA" + +#: ../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 "" +"Esta é uma lista de especificações de interoperabilidade atualmente ativas " +"mantidas pela Python Packaging Authority. O processo de atualização desses " +"padrões e de proposição de novos está documentado em `pypa.io `__." + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +#, fuzzy +#| msgid "" +#| "This document describes the dependency specifiers format as originally " +#| "specified in :pep:`508`." +msgid "This specification was originally defined in :pep:`740`." +msgstr "" +"Este documento descreve o formato dos especificadores de dependência " +"conforme originalmente especificado na :pep:`508`." + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +#, fuzzy +#| msgid "Existing projects" +msgid "Attestation objects" +msgstr "Projetos existentes" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +#, fuzzy +msgid "Inline script metadata" +msgstr "Declarando os metadados do projeto" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +#, fuzzy +msgid "Recommendations" +msgstr "Recomendações de ferramentas" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +#, fuzzy +#| msgid "in favour of ``Requires-Dist``" +msgid "Examples of valid license expressions:" +msgstr "em favor de ``Requires-Dist``" + +#: ../source/specifications/license-expression.rst:45 +#, fuzzy +#| msgid "in favour of ``Requires-Dist``" +msgid "Examples of invalid license expressions:" +msgstr "em favor de ``Requires-Dist``" + +#: ../source/specifications/name-normalization.rst:3 +#, fuzzy +msgid "Names and normalization" +msgstr "Normalização de nome de pacote" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +#, fuzzy +msgid "Name format" +msgstr "Formato de arquivo" + +#: ../source/specifications/name-normalization.rst:15 +#, fuzzy +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`)::" +msgstr "" +"Um nome válido consiste apenas em letras e números ASCII, ponto, sublinhado " +"e hífen. Deve começar e terminar com uma letra ou número. Isso significa que " +"nomes de projeto válidos são limitados àqueles que correspondem ao seguinte " +"regex (executado com ``re.IGNORECASE``)::" + +#: ../source/specifications/name-normalization.rst:26 +#, fuzzy +msgid "Name normalization" +msgstr "Normalização" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" +"O nome deve ser colocado em letras minúsculas com todos os caracteres ``.``, " +"``-`` ou ``_`` substituídos por um único caractere ``-``. Isso pode ser " +"implementado em Python com o módulo re:" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "Isso significa que os seguintes nomes são todos equivalentes:" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "``friendly-bard`` (forma normalizada)" + +#: ../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 "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" +"``FrIeNdLy-._.-bArD`` (uma forma _terrível_ de descrever um nome, mas é " +"válida)" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "Tags de compatibilidade de plataforma" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" +"As tags de compatibilidade de plataforma permitem que ferramentas de " +"construção marquem as distribuições como sendo compatíveis com plataformas " +"específicas e permitem que os instaladores entendam quais distribuições são " +"compatíveis com o sistema em que estão executando." + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "Oformato da tag é ``{python tag}-{abi tag}-{platform tag}``." + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "python tag" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "'py27', 'cp33'" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "'cp32dmu', '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 "" +"Por exemplo, a tag ``py27-none-any`` indica compatibilidade com Python 2.7 " +"(qualquer implementação Python 2.7), com nenhum requisito de ABI, em " +"qualquer plataforma." + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" +"O formato de pacote construído ``wheel`` inclui essas tags em seus nomes de " +"arquivo, no formato ``{distribution}-{version}(-{build tag})?-{python tag}-" +"{abitag}-{platform tag} .whl``. Outros formatos de pacote podem ter suas " +"próprias convenções." + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" +"Quaisquer espaços em potencial em alguma tag deve ser substituído por ``_``." + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "A tag Python" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" +"A tag Python indica a implementação e a versão exigida por uma distribuição. " +"As principais implementações têm códigos abreviados, inicialmente:" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "py: Python genérico (não requer recursos específicos de implementação)" + +#: ../source/specifications/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/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "jy: Jython" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +#, fuzzy +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "Outras implementações Python devem usar ``sys.implementation.name``." + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" +"A versão é ``py_version_nodot``. CPython fica sem ponto, mas se um for " +"necessário, o sublinhado ``_`` é usado em seu lugar. PyPy provavelmente deve " +"usar suas próprias versões aqui ``pp18``, ``pp19``." + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" +"A versão pode ser apenas a versão principal ``2`` ou ``3`` ``py2``, ``py3`` " +"para muitas distribuições de Python puro." + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" +"É importante ressaltar que as tags somente da versão principal, como ``py2`` " +"e ``py3``, não são abreviações para ``py20`` e ``py30``. Em vez disso, essas " +"tags significam que o empacotador lançou intencionalmente uma distribuição " +"compatível com várias versões." + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" +"Uma distribuição compatível com Python 2/3 de fonte única pode usar a tag " +"composta ``py2.py3``. Consulte `Conjuntos de tags compactadas`_, abaixo." + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "A tag ABI" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" +"A tag ABI indica qual ABI do Python é necessária para qualquer módulo de " +"extensão incluído. Para ABIs específicos de implementação, a implementação é " +"abreviada da mesma forma que a tag Python, por exemplo ``cp33d`` seria o ABI " +"CPython 3.3 com depuração." + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" +"A ABI estável do CPython é ``abi3`` como no sufixo da biblioteca " +"compartilhada." + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" +"Implementações com uma ABI muito instável podem usar os primeiros 6 bytes " +"(como 8 caracteres codificados em base64) do hash SHA-256 de sua revisão de " +"código-fonte e sinalizadores de compilador, etc, mas provavelmente não terão " +"uma grande necessidade de distribuir distribuições binárias. A comunidade de " +"cada implementação pode decidir como usar melhor a tag ABI." + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "A tag Platform" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +#, fuzzy +msgid "Basic platform tags" +msgstr "platform tag" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +#, fuzzy +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:" +msgstr "" +"A tag da plataforma é simplesmente ``distutils.util.get_platform()`` com " +"todos os hífens ``-`` e pontos ``.`` substituídos por sublinhados ``_``." + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "win32" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "linux_i386" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "linux_x86_64" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "``manylinux``" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +#, fuzzy +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 "" +"O esquema definido na :pep:`425` é insuficiente para distribuição pública de " +"arquivos wheel (e arquivos wheel do \\*nix em geral) para plataformas Linux, " +"devido ao grande ecossistema de plataformas Linux e diferenças sutis entre " +"elas." + +#: ../source/specifications/platform-compatibility-tags.rst:112 +#, fuzzy +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." +msgstr "" +"Em vez disso, a :pep:`600` define o padrão ``manylinux``, que representa um " +"subconjunto comum de plataformas Linux, e permite a construção de wheels com " +"a tag de plataforma ``manylinux`` que pode ser usada na maioria das " +"distribuições Linux." + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +#, fuzzy +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" +"``manylinux1`` (:pep:`513`) oferece suporte às arquiteturas ``x86_64`` e " +"``i686`` e é baseado em uma plataforma Linux compatível de 2007." + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" +"Em geral, as distribuições construídas para versões mais antigas da " +"especificação são compatíveis com versões futuras (o que significa que as " +"distribuições ``manylinux1`` devem continuar a funcionar em sistemas " +"modernos), mas não compatíveis com versões anteriores (significando que " +"distribuições ``manylinux2010`` não devem trabalhar em plataformas que " +"existiam antes de 2010)." + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" +"Os mantenedores do pacote devem tentar atingir a especificação mais " +"compatível possível, com a ressalva de que o ambiente de compilação " +"fornecido para ``manylinux1`` e ``manylinux2010`` atingiu o fim da vida, o " +"que significa que essas imagens não receberão mais atualizações de segurança." + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" +"A tabela a seguir mostra as versões mínimas de projetos relevantes para " +"oferecer suporte aos vários padrões ``manylinux``:" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "Ferramenta" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "``manylinux1``" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "``manylinux2010``" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "``manylinux2014``" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "``manylinux_x_y``" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "``>=8.1.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "``>=19.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "``>=19.3``" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "``>=20.3``" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "auditwheel" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "``>=1.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "``>=2.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "``>=3.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "``>=3.3.0`` [#]_" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" +"Suporte somente para ``manylinux_2_24`` foi adicionado em auditwheel 3.3.0" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +#, fuzzy +msgid "``musllinux``" +msgstr "``manylinux``" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +#, fuzzy +#| msgid "``x86_64``" +msgid "``arm64``, ``x86_64``" +msgstr "``x86_64``" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +#, fuzzy +#| msgid "``install``" +msgid "``intel``" +msgstr "``install``" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +#, fuzzy +#| msgid "``x86_64``" +msgid "``i386``, ``x86_64``" +msgstr "``x86_64``" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +#, fuzzy +#| msgid "``3.4``, ``2.7``" +msgid "``i386``, ``ppc``" +msgstr "``3.4``, ``2.7``" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +#, fuzzy +#| msgid "``x86_64``" +msgid "``fat64``" +msgstr "``x86_64``" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +#, fuzzy +#| msgid "``x86_64``" +msgid "``ppc64``, ``x86_64``" +msgstr "``x86_64``" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +#, fuzzy +#| msgid "``x86_64``" +msgid "``x86``" +msgstr "``x86_64``" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "Uso" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "cp33-cp33m-linux_x86_64" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "cp33-abi3-linux_x86_64" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "cp3-abi3-linux_x86_64" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "cp33-none-linux_x86_64*" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "cp3-none-linux_x86_64*" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "py33-none-linux_x86_64*" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "py3-none-linux_x86_64*" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "cp33-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "cp3-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "py33-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "py3-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "py32-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "py31-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "py30-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "Conjuntos de Etiquetas Comprimidos" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "Quais etiquetas são utilizadas por padrão?" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +#, fuzzy +#| msgid "" +#| "This document describes the dependency specifiers format as originally " +#| "specified in :pep:`508`." +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" +"Este documento descreve o formato dos especificadores de dependência " +"conforme originalmente especificado na :pep:`508`." + +#: ../source/specifications/platform-compatibility-tags.rst:451 +#, fuzzy +#| msgid "" +#| "This document describes the dependency specifiers format as originally " +#| "specified in :pep:`508`." +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" +"Este documento descreve o formato dos especificadores de dependência " +"conforme originalmente especificado na :pep:`508`." + +#: ../source/specifications/project-status-markers.rst:5 +#, fuzzy +#| msgid "Project Summaries" +msgid "Project Status Markers" +msgstr "Resumos de projetos" + +#: ../source/specifications/project-status-markers.rst:9 +#, fuzzy +#| msgid "" +#| "This document describes the dependency specifiers format as originally " +#| "specified in :pep:`508`." +msgid "This specification was originally defined in :pep:`792`." +msgstr "" +"Este documento descreve o formato dos especificadores de dependência " +"conforme originalmente especificado na :pep:`508`." + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +#, fuzzy +#| msgid "Installation" +msgid "Installer semantics: none." +msgstr "Instalação" + +#: ../source/specifications/project-status-markers.rst:45 +#, fuzzy +#| msgid "``packages``" +msgid "``archived``" +msgstr "``packages``" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +#, fuzzy +msgid "Installer semantics:" +msgstr "Instalador" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +#, fuzzy +#| msgid "Deprecated" +msgid "``deprecated``" +msgstr "Descontinuado" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +#, fuzzy +#| msgid "``pyproject.toml`` specification" +msgid "``pylock.toml`` Specification" +msgstr "Especificação do ``pyproject.toml``" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +#, fuzzy +#| msgid "" +#| "This document describes the dependency specifiers format as originally " +#| "specified in :pep:`508`." +msgid "This specification was originally defined in :pep:`751`." +msgstr "" +"Este documento descreve o formato dos especificadores de dependência " +"conforme originalmente especificado na :pep:`508`." + +#: ../source/specifications/pylock-toml.rst:16 +#, fuzzy +#| msgid "Name" +msgid "File Name" +msgstr "Nome" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +#, fuzzy +#| msgid "``platform_version``" +msgid "``lock-version``" +msgstr "``platform_version``" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +#, fuzzy +#| msgid "Requires" +msgid "**Required?**: yes" +msgstr "Requires" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +#, fuzzy +#| msgid "``entry-points``" +msgid "``environments``" +msgstr "``entry-points``" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +#, fuzzy +#| msgid "TOML_ type: array of strings" +msgid "**Type**: Array of strings" +msgstr "Tipo TOML_: vetor de strings" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +#, fuzzy +#| msgid "TOML_ type: string" +msgid "**Type**: string" +msgstr "Tipo TOML_: string" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +#, fuzzy +#| msgid "``dependencies``" +msgid "``dependency-groups``" +msgstr "``dependencies``" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +#, fuzzy +#| msgid ":ref:`pyproject-toml-spec`" +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr ":ref:`pyproject-toml-spec`" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +#, fuzzy +#| msgid "" +#| "``INSTALLER``: records the name of the tool used to install the project." +msgid "Records the name of the tool used to create the lock file." +msgstr "" +"``INSTALLER``: registra o nome da ferramenta usada para instalar o projeto." + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +#, fuzzy +#| msgid "``packages``" +msgid "``[[packages]]``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +#, fuzzy +#| msgid "TOML_ type: array of strings" +msgid "**Type**: array of tables" +msgstr "Tipo TOML_: vetor de strings" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.name``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +#, fuzzy +#| msgid "" +#| "For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgid "The name of the package :ref:`normalized `." +msgstr "" +"Para propósitos de comparação, os nomes devem ser :ref:`normalizados ` antes da comparação." + +#: ../source/specifications/pylock-toml.rst:210 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.version``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +#, fuzzy +msgid "The version of the package." +msgstr "Criando arquivos do pacote" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.marker``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +#, fuzzy +#| msgid "``requires-python``" +msgid "``packages.requires-python``" +msgstr "``requires-python``" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +#, fuzzy +#| msgid "``dependencies``" +msgid "``[[packages.dependencies]]``" +msgstr "``dependencies``" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +#, fuzzy +#| msgid "``packages``" +msgid "``[packages.vcs]``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +#, fuzzy +#| msgid "TOML_ type: table" +msgid "**Type**: table" +msgstr "Tipo TOML_: tabela" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.vcs.type``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +#, fuzzy +#| msgid "Install from version control systems" +msgid "The type of version control system used." +msgstr "Instalar a partir de sistemas de controle de versão" + +#: ../source/specifications/pylock-toml.rst:306 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.vcs.url``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +#, fuzzy +#| msgid "The source tree" +msgid "The URL_ to the source tree." +msgstr "A árvore fonte" + +#: ../source/specifications/pylock-toml.rst:317 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.vcs.path``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +#, fuzzy +#| msgid "``requested_revision`` field" +msgid "``packages.vcs.requested-revision``" +msgstr "Campo ``requested_revision``" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.vcs.commit-id``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +#, fuzzy +#| 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." +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" +"Uma chave ``commit_id`` (tipo ``string``) DEVE estar presente, contendo o " +"número exato de commit/revisão que foi/será instalado. Se o VCS oferecer " +"suporte a identificadores de revisão baseados em hash de commit, tal hash de " +"commit DEVE ser usado como ``commit_id`` para referenciar a versão imutável " +"do código-fonte." + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +#, fuzzy +#| msgid "``packages``" +msgid "``[packages.directory]``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +#, fuzzy +#| msgid "``package_data``" +msgid "``packages.directory.path``" +msgstr "``package_data``" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +#, fuzzy +#| msgid "``packages``" +msgid "``[packages.archive]``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.archive.url``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.archive.path``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.archive.size``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +#, fuzzy +#| msgid "The name of the project." +msgid "The size of the archive file." +msgstr "O nome do projeto." + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +#, fuzzy +#| msgid "Where the guide is deployed" +msgid "The time the file was uploaded." +msgstr "Onde o guia é disponibilizado" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +#, fuzzy +#| msgid "TOML_ type: array of strings" +msgid "**Type**: Table of strings" +msgstr "Tipo TOML_: vetor de strings" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +#, fuzzy +#| msgid "" +#| "A table of URLs where the key is the URL label and the value is the URL " +#| "itself." +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" +"Uma tabela de URLs onde a chave é o rótulo da URL e o valor é a URL em si." + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.index``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +#, fuzzy +#| msgid "``packages``" +msgid "``[packages.sdist]``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +#, fuzzy +#| msgid "``package_data``" +msgid "``packages.sdist.name``" +msgstr "``package_data``" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +#, fuzzy +#| msgid "``package_data``" +msgid "``packages.sdist.upload-time``" +msgstr "``package_data``" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.sdist.url``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +#, fuzzy +#| msgid "``package_data``" +msgid "``packages.sdist.path``" +msgstr "``package_data``" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.sdist.size``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +#, fuzzy +#| msgid "``package_data``" +msgid "``packages.sdist.hashes``" +msgstr "``package_data``" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +#, fuzzy +#| msgid "``packages``" +msgid "``[[packages.wheels]]``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.wheels.name``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.wheels.url``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:647 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.wheels.path``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:655 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.wheels.size``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:663 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.wheels.hashes``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +#, fuzzy +#| msgid ":ref:`pyproject-toml-spec`" +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr ":ref:`pyproject-toml-spec`" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +#, fuzzy +#| msgid "``packages``" +msgid "``[packages.tool]``" +msgstr "``packages``" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +#, fuzzy +#| msgid "Binary distribution format" +msgid ":ref:`Install `." +msgstr "Formato de distribuição binária" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "O arquivo :file:`.pypirc`" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" +"Um arquivo :file:`.pypirc` permite que você defina a configuração " +"para :term:`índices de pacotes <Índice de Pacotes>` (referido aqui como " +"\"repositórios\"), para que você não precise inserir a URL, nome de usuário " +"ou senha sempre que você enviar um pacote com :ref:`twine` ou :ref:`flit`." + +#: ../source/specifications/pypirc.rst:13 +#, fuzzy +#| msgid "The :file:`.pypirc` file" +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "O arquivo :file:`.pypirc`" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "O formato (originalmente definido pelo pacote :ref:`distutils`) é:" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" +"A seção ``distutils`` define um campo ``index-servers`` que lista o nome de " +"todas as seções descrevendo um repositório." + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "Cada seção descrevendo um repositório define três campos:" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "``repository``: A URL do repositório." + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "``username``: O nome de usuário registrado no repositório." + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" +"``password``: A senha que será usada para autenticar o nome de usuário." + +#: ../source/specifications/pypirc.rst:48 +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 "" +"Esteja ciente de que isso armazena sua senha em texto simples. Para melhor " +"segurança, considere uma alternativa como `chaveiro`_, configurando " +"variáveis de ambiente ou fornecendo a senha na linha de comando." + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" +"Caso contrário, defina as permissões em :file:`.pypirc` para que somente " +"você possa ver ou modificá-lo. Por exemplo, no Linux ou macOS, execute:" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "Configurações comuns" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" +"Esses exemplos se aplicam a :ref:`twine`. Outros projetos (por " +"exemplo, :ref:`flit`) também usam :file:`.pypirc`, mas com padrões " +"diferentes. Consulte a documentação de cada projeto para obter mais detalhes " +"e instruções de uso." + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" +"A configuração padrão do Twine imita um :file:`.pypirc` com seções de " +"repositório para PyPI e TestPyPI:" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" +"Twine irá adicionar configuração adicional de :file:`$HOME/.pypirc`, a linha " +"de comando e variáveis de ambiente a esta configuração padrão." + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "Usando um token do PyPI" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" +"Para definir seu `token de API`_ para PyPI, você pode criar " +"um :file:`$HOME/.pypirc` semelhante a:" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" +"Para o :ref:`TestPyPI `, adicione a seção ``[testpypi]``, " +"usando o token de API de sua conta do TestPyPI." + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "Usando outro índice de pacotes" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" +"Para configurar um repositório adicional, você precisará redefinir o campo " +"``index-servers`` para incluir o nome do repositório. Aqui está um exemplo " +"completo de um :file:`$HOME/.pypirc` para PyPI, TestPyPI e um repositório " +"privado:" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" +"Em vez de usar o campo ``password``, considere salvar seus tokens de API e " +"senhas com segurança usando um `chaveiro`_ (que é instalado pelo Twine):" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "Especificação do ``pyproject.toml``" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +#, fuzzy +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "Declarando dependências do sistema de construção" + +#: ../source/specifications/pyproject-toml.rst:29 +#, fuzzy +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" +"`pyproject.toml` é um formato de arquivo independente do sistema de " +"construção definido na :pep:`518` que os projetos podem fornecer para " +"declarar quaisquer dependências de nível Python que devem ser instaladas " +"para executar o sistema de construção do projeto com sucesso." + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" +"A tabela ``[build-system]`` é usada para armazenar dados relacionados a " +"construção. Inicialmente, apenas uma chave da tabela é válida e é " +"obrigatória para a tabela: ``requires``. Esta chave deve ter um valor de uma " +"lista de strings que representam dependências necessárias para executar o " +"sistema de construção. As strings nesta lista seguem a :ref:`especificação " +"de especificadores de versão `." + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +#, fuzzy +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "Declarando os metadados do projeto" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" +"Existem dois tipos de metadados: *estáticos* e *dinâmicos*. Metadados " +"estáticos são especificados diretamente no arquivo ``pyproject.toml`` e não " +"podem ser especificados ou alterados por uma ferramenta (isso inclui dados " +"*referenciados* pelo metadados, por exemplo, o conteúdo de arquivos " +"referenciados pelos metadados). Os metadados dinâmicos são listados por meio " +"da chave ``dynamic`` (definido posteriormente nesta especificação) e " +"representam os metadados que uma ferramenta fornecerá posteriormente." + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "As únicas chaves que precisam ser definidos estaticamente são:" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" +"As chaves que são obrigatórias, mas podem ser especificadas estaticamente " +"*ou* listadas como dinâmicas são:" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" +"Todas as outras chaves são consideradas opcionais e podem ser especificadas " +"estaticamente, listadas como dinâmicas ou não especificadas." + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "A lista completa de chaves permitidas na tabela ``[project]`` são:" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "``authors``" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "``dependencies``" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "``dynamic``" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "``entry-points``" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "``gui-scripts``" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +#, fuzzy +#| msgid "``name``" +msgid "``import-names``" +msgstr "``name``" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "``maintainers``" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "``optional-dependencies``" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "Tipo TOML_: string" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" +"Campo correspondente dos :ref:`metadados principais `: :ref:`Name `" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "O nome do projeto." + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" +"As ferramentas DEVEM :ref:`normalizar ` este nome, " +"conforme especificado por :pep:`503`, assim que for lido para consistência " +"interna." + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" +"Campo correspondente dos :ref:`metadados principais `: :ref:`Version `" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" +"A versão do projeto, conforme definido na :ref:`especificação de " +"especificadores de versão `." + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "Os usuários DEVEM preferir especificar versões já normalizadas." + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" +"Campo correspondente dos :ref:`metadados principais `: :ref:`Summary `" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "Tipo TOML_: string ou tabela" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" +"Campos correspondente dos :ref:`metadados principais `: :ref:`Description ` " +"e :ref:`Description-Content-Type `" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "A descrição completa do projeto (isto é, o README)." + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" +"A chave aceita uma string ou uma tabela. Se for uma string, então é um " +"caminho relativo ao ``pyproject.toml`` para um arquivo texto contendo a " +"descrição completa. As ferramentas DEVEM presumir que a codificação do " +"arquivo é UTF-8. Se o caminho do arquivo termina com um sufixo ``.md``, ou " +"sua versão em caixa alta, então as ferramentas DEVEM presumir que o tipo de " +"conteúdo é ``text/markdown``. Se o caminho do arquivo termina em ``.rst``, " +"então as ferramentas DEVEM presumir que o tipo de conteúdo é ``text/x-rst``. " +"Se uma ferramenta reconhece mais extensões do que esta PEP, elas podem " +"inferir o tipo de conteúdo para o usuário sem especificar esta chave como " +"``dynamic``. Para todos os sufixos não reconhecidos quando um tipo de " +"conteúdo não é fornecido, as ferramentas DEVEM levantar um erro." + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" +"A chave ``readme`` também pode receber uma tabela. A chave ``file`` tem um " +"valor string que representa um caminho relativo a ``pyproject.toml`` para um " +"arquivo contendo a descrição completa. A chave ``text`` tem um valor de " +"string que é a descrição completa. Essas chaves são mutuamente exclusivas, " +"portanto, as ferramentas DEVEM levantar um erro se os metadados " +"especificarem ambas as chaves." + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" +"Uma tabela especificada na chave ``readme`` também possui uma chave " +"``content-type`` que recebe uma string especificando o tipo de conteúdo da " +"descrição completa. Uma ferramenta DEVE levantar um erro se os metadados não " +"especificarem esse campo na tabela. Se os metadados não especificarem o " +"parâmetro ``charset``, será considerado UTF-8. As ferramentas PODEM oferecer " +"suporte a outras codificações, se assim o desejarem. As ferramentas PODEM " +"oferecer suporte a tipos de conteúdo alternativos que podem transformar em " +"um tipo de conteúdo conforme suportado pelos :ref:`metadados principais " +"`. Caso contrário, as ferramentas DEVEM levantar um erro para " +"tipos de conteúdo não suportados." + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" +"Campo correspondente dos :ref:`metadados principais `: :ref:`Requires-Python `" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "Os requisitos de versão do Python do projeto." + +#: ../source/specifications/pyproject-toml.rst:258 +#, fuzzy +#| msgid "" +#| "Corresponding :ref:`core metadata ` field: :ref:`License " +#| "`" +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" +"Campo correspondente dos :ref:`metadados principais `: :ref:`License `" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +#, fuzzy +#| msgid "PyPA specifications" +msgid "Legacy specification" +msgstr "Especificações do PyPA" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "Tipo TOML_: tabela" + +#: ../source/specifications/pyproject-toml.rst:276 +#, fuzzy +#| msgid "" +#| "Corresponding :ref:`core metadata ` field: :ref:`License " +#| "`" +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" +"Campo correspondente dos :ref:`metadados principais `: :ref:`License `" + +#: ../source/specifications/pyproject-toml.rst:279 +#, fuzzy +#| 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." +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" +"A tabela pode ter uma de duas chaves. A chave ``file`` tem um valor de " +"string que é um caminho de arquivo relativo a ``pyproject.toml`` para o " +"arquivo que contém a licença do projeto. As ferramentas DEVEM presumir que a " +"codificação do arquivo é UTF-8. A chave ``text`` tem um valor de string que " +"é a licença do projeto. Essas chaves são mutuamente exclusivas, portanto, " +"uma ferramenta DEVE levantar um erro se os metadados especificarem ambas as " +"chaves." + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "Tipo TOML_: vetor de strings" + +#: ../source/specifications/pyproject-toml.rst:294 +#, fuzzy +#| msgid "" +#| "Corresponding :ref:`core metadata ` field: :ref:`License " +#| "`" +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" +"Campo correspondente dos :ref:`metadados principais `: :ref:`License `" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "Tipo TOML_: Vetor de tabelas em linha com strings de chaves e valores" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" +"Campos correspondentes dos :ref:`metadados principais `: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer ` " +"e :ref:`Maintainer-email `" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" +"As pessoas ou organizações consideradas \"autoras\" do projeto. O " +"significado exato está aberto à interpretação -- pode listar os autores " +"originais ou primários, mantenedores atuais ou proprietários do pacote." + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" +"A chave \"maintainers\" é semelhante a \"authors\" no sentido de que seu " +"significado exato está aberto à interpretação." + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" +"Estas chaves aceitam um vetor de tabelas com 2 chaves: ``name`` e ``email``. " +"Ambos os valores devem ser strings. O valor ``name`` DEVE ser um nome de e-" +"mail válido (ou seja, o que quer que possa ser colocado como um nome, antes " +"de um e-mail, em :rfc:`822`) e não conter vírgulas. O valor ``email`` DEVE " +"ser um endereço de email válido. Ambas as chaves são opcionais, mas ao menos " +"uma das chaves deve ser especificada na tabela." + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" +"O uso dos dados para preencher :ref:`metadados principais ` " +"deve ser feito da seguinte forma:" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" +"Se somente ``name`` for fornecido, o valor vai em :ref:`Author ` ou :ref:`Maintainer ` conforme " +"apropriado." + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" +"Se somente ``email`` é fornecido, o valor vai em :ref:`Author-email ` ou :ref:`Maintainer-email ` conforme apropriado." + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" +"Se ``email`` e ``name`` são fornecidos, o valor vai em :ref:`Author-email " +"` ou :ref:`Maintainer-email ` conforme apropriado, com o formado ``{name} <{email}>``." + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "Vários valores devem ser separados por vírgulas." + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" +"Campo correspondente dos :ref:`metadados principais `: :ref:`Keywords `" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "As palavras-chave do projeto." + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" +"Campo correspondente dos :ref:`metadados principais `: :ref:`Classifier `" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "Classificadores Trove que se aplicam ao projeto." + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "Tipo TOML_: tabela com chaves e valores de strings" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" +"Campo correspondente dos :ref:`metadados principais `: :ref:`Project-URL `" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "Pontos de entrada" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" +"Tipo TOML_: tabela (``[project.scripts]``, ``[project.gui-scripts]`` e " +"``[project.entry-points]``)" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr ":ref:`Especificação de pontos de entrada `" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" +"Existem três tabelas relacionadas aos pontos de entrada. A tabela " +"``[project.scripts]`` corresponde ao grupo ``console_scripts`` " +"na :ref:`especificação de pontos de entrada `. A chave da " +"tabela é o nome do ponto de entrada e o valor é a referência do objeto." + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" +"A tabela ``[project.gui-scripts]`` corresponde ao grupo ``gui_scripts`` " +"na :ref:`especificação de pontos de entrada `. Seu formato é o " +"mesmo que ``[project.scripts]``." + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" +"A tabela ``[project.entry-points]`` é uma coleção de tabelas. O nome de cada " +"subtabela é um grupo de pontos de entrada. A chave e a semântica do valor " +"são iguais a ``[project.scripts]``. Os usuários NÃO DEVEM criar subtabelas " +"aninhadas, mas sim manter os grupos de pontos de entrada em apenas um nível " +"de profundidade." + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" +"Backends de construção DEVEM levantar um erro se os metadados definem uma " +"tabela ``[project.entry-points.console_scripts]`` ou ``[project.entry-" +"points.gui_scripts]``, pois elas seriam ambíguas perante " +"``[project.scripts]`` e ``[project.gui-scripts]``, respectivamente." + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" +"Tipo TOML_: Vetor de strings da :pep:`508` (``dependencies``) e uma tabela " +"com valores de vetores de strings da :pep:`508` (``optional-dependencies``)" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" +"Campo correspondente dos :ref:`metadados principais `: :ref:`Requires-Dist ` " +"e :ref:`Provides-Extra `" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "As dependências (opcionais) do projeto." + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" +"Para ``dependencies``, é uma chave cujo valor é um array de strings. Cada " +"string representa uma dependência do projeto e DEVE ser formatada como uma " +"string válida :pep:`508`. Cada string mapeia diretamente para " +"um :ref:`Requires-Dist `." + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" +"Para ``optional-dependencies``, é uma tabela onde cada chave especifica um " +"extra e cujo valor é um vetor de strings. As strings dos vetores devem ser " +"strings válidas da :pep:`508`. As chaves DEVEM ser valores válidos " +"para :ref:`Provides-Extra `. Cada valor no " +"vetor torna-se assim uma entrada correspondente de :ref:`Requer-Dist ` para os metadados correspondentes de :ref:`Provides-" +"Extra `." + +#: ../source/specifications/pyproject-toml.rst:485 +#, fuzzy +#| msgid "" +#| "Corresponding :ref:`core metadata ` field: :ref:`Name " +#| "`" +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" +"Campo correspondente dos :ref:`metadados principais `: :ref:`Name `" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +msgid "Examples:" +msgstr "Exemplos:" + +#: ../source/specifications/pyproject-toml.rst:536 +#, fuzzy +#| msgid "" +#| "Corresponding :ref:`core metadata ` field: :ref:`Name " +#| "`" +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" +"Campo correspondente dos :ref:`metadados principais `: :ref:`Name `" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +#, fuzzy +#| msgid "Example::" +msgid "Example:" +msgstr "Exemplo::" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "Tipo TOML_: vetor de string" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" +"Campo correspondente dos :ref:`metadados principais `: :ref:`Dynamic `" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" +"Especifica quais chaves listadas por esta PEP foram intencionalmente não " +"especificadas para que outra ferramenta possa/vai fornecer tais metadados " +"dinamicamente. Isso delineia claramente quais metadados são propositalmente " +"não especificados e espera-se que permaneçam não especificados em comparação " +"a serem fornecidos por meio de ferramentas posteriormente." + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" +"Um backend de construção DEVE respeitar metadados especificados " +"estaticamente (o que significa que os metadados não listam a chave em " +"``dynamic``)." + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" +"Um backend de construção DEVE gerar um erro se os metadados especificarem " +"``name`` em ``dynamic``." + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" +"Se a especificação de :ref:`metadados principais ` lista um " +"campo como \"Required\", então os metadados DEVEM especificar a chave " +"estaticamente ou listá-la em ``dynamic`` (backends de construção DEVEM gerar " +"um erro, caso contrário , ou seja, não deve ser possível que uma chave " +"obrigatória não seja listada de alguma forma na tabela ``[project]``)." + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" +"Se a especificação de :ref:`metadados principais ` listar um " +"campo como \"Optional\", os metadados PODEM listá-lo em ``dynamic`` se a " +"expectativa for um backend de construção fornecerá os dados para a chave " +"mais tarde." + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" +"Os backends de construção DEVEM levantar um erro se os metadados " +"especificarem uma chave estaticamente, além de serem listados em ``dynamic``." + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" +"Se os metadados não listam uma chave em ``dynamic``, então um backend de " +"construção NÃO PODE preencher os metadados necessários em nome do usuário " +"(ou seja, ``dynamic`` é a única maneira de permitir que uma ferramenta " +"preencha metadados e o usuário deve optar pelo preenchimento)." + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" +"Os backends de construção DEVEM levantar um erro se os metadados " +"especificarem uma chave em ``dynamic``, mas o backend de construção não foi " +"capaz de determinar os dados para ele (omitir os dados, se determinado como " +"o valor exato, é aceitável) ." + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "Gravando projetos instalados" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" +"Este documento especifica um formato comum de gravação de informações " +"sobre :term:`projetos ` Python instalados em um ambiente. Um " +"formato de metadados comum permite que as ferramentas consultem, gerenciem " +"ou desinstalem projetos, independentemente de como foram instalados." + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" +"Quase todas as informações são opcionais. Isso permite que ferramentas fora " +"do ecossistema Python, como gerenciadores de pacotes Linux, se integrem com " +"as ferramentas Python tanto quanto possível. Por exemplo, mesmo se um " +"instalador não puder fornecer facilmente uma lista de arquivos instalados em " +"um formato específico para as ferramentas Python, ele ainda deve registrar o " +"nome e a versão do projeto instalado." + +#: ../source/specifications/recording-installed-packages.rst: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 "" +"Cada projeto instalado de uma distribuição deve, além dos arquivos, instalar " +"um diretório \"``.dist-info``\" localizado junto com os módulos e pacotes " +"importáveis (comumente, o diretório ``site-packages``)." + +#: ../source/specifications/recording-installed-packages.rst: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 "" +"Este diretório é nomeado como ``{name}-{version}.dist-info``, com os campos " +"``name`` e ``version`` correspondendo a :ref:`core-metadata`. Ambos os " +"campos devem ser normalizados (consulte a :ref:`name-normalization` e " +"a :pep:`PEP 440 <440#normalization>` para a definição de normalização para " +"cada campo respectivamente) e substitua os caracteres de traço (``-``) por " +"caracteres de sublinhado (``_``), então o diretório ``.dist-info`` sempre " +"tem exatamente um caractere de traço (``-``) em seu radical, separando os " +"campos ``name`` e ``version``." + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" +"Historicamente, as ferramentas falharam em substituir caracteres de ponto ou " +"normalizar maiúsculas e minúsculas no campo ``name``, ou não realizar a " +"normalização no campo ``version``. Ferramentas que consomem diretórios " +"``.dist-info`` devem esperar que esses campos sejam desnormalizados e tratá-" +"los como equivalentes a suas contrapartes normalizadas. Novas ferramentas " +"que escrevem diretórios ``.dist-info`` DEVEM normalizar ambos os campos " +"``name`` e ``version`` usando as regras descritas acima, e as ferramentas " +"existentes são encorajadas a começar a normalizar esses campos." + +#: ../source/specifications/recording-installed-packages.rst:47 +#, fuzzy +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." +msgstr "" +"O nome do diretório ``.dist-info`` é formatado para representar " +"inequivocamente uma distribuição como um caminho do sistema de arquivos. As " +"ferramentas que apresentam um nome de distribuição a um usuário devem evitar " +"o uso do nome normalizado e, em vez disso, apresentar o nome especificado " +"(quando necessário antes da resolução de um pacote instalado) ou ler os " +"respectivos campos nos metadados principais, uma vez que os valores listados " +"não têm escape e são precisos refletem a distribuição. As bibliotecas devem " +"fornecer API para o consumo dessas ferramentas, de forma que as ferramentas " +"possam ter acesso ao nome não normalizado ao exibir informações de " +"distribuição." + +#: ../source/specifications/recording-installed-packages.rst:56 +#, fuzzy +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" +"Este diretório ``.dist-info`` pode conter esses arquivos, descritos em " +"detalhes abaixo:" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "``METADATA``: contém metadados do projeto" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "``RECORD``: registra a lista de arquivos instalados." + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" +"``INSTALLER``: registra o nome da ferramenta usada para instalar o projeto." + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "``entry_points.txt``: veja :ref:`entry-points` para mais detalhes" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "``direct_url.json``: veja :ref:`direct-url` para mais detalhes" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" +"O arquivo ``METADATA`` é obrigatório. Todos os outros arquivos podem ser " +"omitidos a critério da ferramenta de instalação. Arquivos adicionais " +"específicos do instalador podem estar presentes." + +#: ../source/specifications/recording-installed-packages.rst:69 +#, fuzzy +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" +"Este diretório ``.dist-info`` pode conter esses arquivos, descritos em " +"detalhes abaixo:" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" +"A especificação :ref:`binary-distribution-format` descreve arquivos " +"adicionais que podem aparecer no diretório ``.dist-info`` de " +"um :term:`Wheel`. Esses arquivos podem ser copiados para o diretório ``.dist-" +"info`` de um projeto instalado." + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" +"As versões anteriores desta especificação também especificavam um arquivo " +"``REQUESTED``. Este arquivo agora é considerado uma extensão específica da " +"ferramenta, mas pode ser padronizado novamente no futuro. Consulte `PEP 376 " +"`_ para seu significado " +"original." + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "O arquivo METADATA" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" +"O arquivo ``METADATA`` contém metadados conforme descrito na " +"especificação :ref:`core-metadata`, versão 1.1 ou superior." + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" +"O arquivo ``METADATA`` é obrigatório. Se não puder ser criado ou se os " +"metadados principais necessários não estiverem disponíveis, os instaladores " +"devem relatar um erro e falhar ao instalar o projeto." + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "O arquivo RECORD" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" +"O arquivo ``RECORD`` contém a lista de arquivos instalados. É um arquivo CSV " +"contendo um registro (linha) por arquivo instalado." + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" +"O dialeto CSV deve ser legível com o ``reader`` padrão do módulo ``csv`` do " +"Python:" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "delimitador de campo: ``,`` (vírgula)," + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "caractere de aspas: ``\"`` (aspas duplas)," + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "terminador de linha: ``\\r\\n`` ou ``\\n``." + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" +"Cada registro é composto de três elementos: o **caminho** do arquivo, o " +"**hash** do conteúdo e seu **tamanho**." + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" +"O *caminho* pode ser absoluto ou relativo ao diretório que contém o " +"diretório ``.dist-info`` (comumente, o diretório ``site-packages``). No " +"Windows, os diretórios podem ser separados por barras ou barras invertidas " +"(``/`` ou ``\\``)." + +#: ../source/specifications/recording-installed-packages.rst:120 +#, 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 "" +"O *hash* é uma string vazia ou o nome de um algoritmo hash de " +"``hashlib.algorithms_guaranteed``, seguido pelo caractere igual ``=`` e o " +"resumo do conteúdo do arquivo, codificado com a codificação urlsafe-base64-" +"nopad (``base64.urlsafe_b64encode(digest)`` com ``=`` ao final removido)." + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" +"O *tamanho* é a string vazia ou o tamanho do arquivo em bytes, como um " +"inteiro de base 10." + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" +"Para qualquer arquivo, um ou ambos os campos de *hash* e *tamanho* podem ser " +"deixados em branco. Normalmente, entradas para arquivos ``.pyc`` e o próprio " +"arquivo ``RECORD`` têm *hash* e *tamanho* vazios. Para os demais arquivos, " +"não é recomendável deixar as informações de fora, pois impede a verificação " +"da integridade do projeto instalado." + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" +"Se o arquivo ``RECORD`` estiver presente, ele deve listar todos os arquivos " +"instalados do projeto, exceto os arquivos ``.pyc`` correspondentes aos " +"arquivos ``.py`` listados em ``RECORD``, que são opcionais. Notavelmente, o " +"conteúdo do diretório ``.dist-info`` (incluindo o próprio arquivo " +"``RECORD``) deve ser listado. Os diretórios não devem ser listados." + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" +"Para desinstalar completamente um pacote, uma ferramenta precisa remover " +"todos os arquivos listados em ``RECORD``, todos os arquivos ``.pyc`` (de " +"todos os níveis de otimização) correspondentes aos arquivos ``.py`` " +"removidos e quaisquer diretórios esvaziados pela desinstalação." + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "Aqui está um trecho de exemplo de um possível arquivo ``RECORD``::" + +#: ../source/specifications/recording-installed-packages.rst:165 +#, fuzzy +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.)" +msgstr "" +"Se o arquivo ``RECORD`` estiver faltando, as ferramentas que dependem de " +"``.dist-info`` não devem tentar desinstalar ou atualizar o pacote. (Isso não " +"se aplica a ferramentas que dependem de outras fontes de informação, como " +"gerenciadores de pacotes do sistema em distros Linux.)" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "O arquivo INSTALLER" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" +"Se presente, ``INSTALLER`` é um arquivo de texto de uma linha que nomeia a " +"ferramenta usada para instalar o projeto. Se o instalador for executável a " +"partir da linha de comando, ``INSTALLER`` deve conter o nome do comando. " +"Caso contrário, deve conter uma string ASCII imprimível." + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" +"O arquivo pode ser encerrado com zero ou mais caracteres de espaço em branco " +"ASCII." + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "Aqui estão exemplos de dois possíveis arquivos ``INSTALLER``::" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" +"Este valor deve ser usado apenas para fins informativos. Por exemplo, se uma " +"ferramenta é solicitada a desinstalar um projeto, mas não encontra o arquivo " +"``RECORD``, pode sugerir que a ferramenta nomeada em ``INSTALLER`` pode ser " +"capaz de fazer a desinstalação." + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "O arquivo entry_points.txt" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +#, fuzzy +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "Sua especificação detalhada está em :ref:`direct-url`." + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "O arquivo direct_url.json" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" +"Este arquivo DEVE ser criado por instaladores ao instalar uma distribuição a " +"partir de um requisito que especifica uma referência de URL direta " +"(incluindo uma URL de VCS)." + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "Sua especificação detalhada está em :ref:`direct-url`." + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +#, fuzzy +#| msgid "The .dist-info directory" +msgid "The :file:`sboms/` subdirectory" +msgstr "O diretório .dist-info" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "Prevenindo intencionalmente modificações nos pacotes instalados" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +#, fuzzy +#| msgid "Hybrid schemes" +msgid "PyPA schemas" +msgstr "Esquemas híbridos" + +#: ../source/specifications/schemas/index.rst:6 +#, fuzzy +#| msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgid "`direct_url.json `_" +msgstr "``direct_url.json``: veja :ref:`direct-url` para mais detalhes" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../source/specifications/section-distribution-formats.rst:3 +msgid "Package Distribution File Formats" +msgstr "Formatos de arquivos de distribuição de pacotes" + +#: ../source/specifications/section-distribution-metadata.rst:3 +msgid "Package Distribution Metadata" +msgstr "Metadados de distribuição de pacotes" + +#: ../source/specifications/section-installation-metadata.rst:3 +#, fuzzy +msgid "Package Installation Metadata" +msgstr "Metadados do ambiente de instalação de pacotes" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "Interfaces de índices de pacotes" + +#: ../source/specifications/section-python-description-formats.rst:3 +#, fuzzy +#| msgid "Python versions over time" +msgid "Python Description Formats" +msgstr "Versões Python ao longo do tempo" + +#: ../source/specifications/section-reproducible-environments.rst:3 +#, fuzzy +#| msgid "Virtual Environment" +msgid "Reproducible Environments" +msgstr "Ambiente Virtual" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "API de repositório simples" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +#, fuzzy +msgid "Normalized Names" +msgstr "Nomes não normalizados válidos" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +#, fuzzy +msgid "Clients" +msgstr "Conteúdo" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +#, fuzzy +msgid "HTML Serialization" +msgstr "Normalização" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +#, fuzzy +msgid "Project List" +msgstr "Projeto" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +#, fuzzy +msgid "Project Detail" +msgstr "Nome do projeto" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +#, fuzzy +msgid "Backwards Compatibility" +msgstr "Compatibilidade da ABI" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +#, fuzzy +msgid "JSON Serialization" +msgstr "Normalização" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +#, fuzzy +msgid "As an example:" +msgstr "Um exemplo completo" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +#, fuzzy +msgid "``name``: The normalized name of the project." +msgstr "O nome do projeto." + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +#, fuzzy +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." +msgstr "" +"Vários hashes podem ser incluídos e cabe ao consumidor decidir o que fazer " +"com vários hashes (pode validar todos eles ou um subconjunto deles, ou nada)." + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +#, fuzzy +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." +msgstr "" +"Qualquer algoritmo de hash disponível via ``hashlib`` (especificamente " +"qualquer um que possa ser passado para ``hashlib.new()`` e não requeira " +"parâmetros adicionais) pode ser usado como uma chave para o dicionário de " +"hashes. Pelo menos um algoritmo seguro de ``hashlib.algorithms_guaranteed`` " +"DEVE sempre ser incluído. No momento da escrita, ``sha256`` especificamente " +"é recomendado." + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +#, fuzzy +msgid "Content-Types" +msgstr "Conteúdo" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +#, fuzzy +msgid "Version + Format Selection" +msgstr "Versão" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +#, fuzzy +msgid "Endpoint Configuration" +msgstr "Configurações comuns" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "Formato de distribuição fonte" + +#: ../source/specifications/source-distribution-format.rst:8 +#, fuzzy +#| 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." +msgid "" +"The current standard 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 "" +"O formato padrão atual do formato de distribuição fonte é identificado pela " +"presença de um arquivo :file:`pyproject.toml` no arquivo de distribuição. O " +"layout de tal distribuição foi originalmente especificado na :pep:`517` e " +"está formalmente documentado aqui." + +#: ../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 "" +"Existe também o formato de distribuição fonte legado, implicitamente " +"definido pelo comportamento do módulo ``distutils`` na biblioteca padrão, ao " +"executar :command:`setup.py sdist`. Este documento não tenta padronizar este " +"formato, exceto para observar que se uma distribuição de fonte legada contém " +"um arquivo ``PKG-INFO`` usando metadados versão 2.2 ou posterior, então ela " +"DEVE seguir as regras aplicáveis às distribuições de fonte definidas nos " +"metadados especificação." + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "Distribuições fonte também são conhecidas pela abreviação *sdists*." + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "Árvores fonte" + +#: ../source/specifications/source-distribution-format.rst:28 +#, fuzzy +#| 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." +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 used 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 "" +"Uma *árvore fonte* é uma coleção de arquivos e diretórios -- como um " +"checkout local do sistema de controle de versão -- que contém um " +"arquivo :file:`pyproject.toml` que pode ser usado para construir uma " +"distribuição fonte a partir dos arquivos e diretórios contidos. :pep:`517` " +"e :pep:`518` especificam o que é necessário para atender à definição do " +"que :file:`pyproject.toml` deve conter para que algo seja considerado uma " +"árvore fonte." + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "Nome de arquivo da distribuição fonte" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" +"O nome do arquivo de um sdist foi padronizado na :pep:`625`. O nome do " +"arquivo deve estar no formato ``{name}-{version}.tar.gz``, sendo ``{name}`` " +"normalizado de acordo com as mesmas regras das distribuições binárias " +"(veja :ref:`binary-distribution-format`) e ``{version}`` é a forma " +"canonizada da versão do projeto (veja :ref:`version-specifiers`)." + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" +"O nome e os componentes da versão do nome do arquivo DEVEM corresponder aos " +"valores armazenados nos metadados contidos no arquivo." + +#: ../source/specifications/source-distribution-format.rst:49 +#, fuzzy +msgid "" +"Code that produces a source distribution file MUST give the file a name that " +"matches this specification. This includes the ``build_sdist`` hook of " +"a :term:`build backend `." +msgstr "" +"O código que produz um arquivo de distribuição de origem DEVE dar ao arquivo " +"um nome que corresponda a essa especificação. Isso inclui o gancho " +"``build_sdist`` de um backend de construção." + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" +"Código que processa arquivos de distribuição fonte PODE reconhecer arquivos " +"de distribuição fonte pelo sufixo ``.tar.gz`` e a presença de precisamente " +"*um* hífen no nome do arquivo. O código que faz isso pode usar o nome e " +"versão da distribuição a partir do nome do arquivo sem verificação adicional." + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "Formato de arquivo de distribuição fonte" + +#: ../source/specifications/source-distribution-format.rst:61 +#, fuzzy +msgid "" +"A ``.tar.gz`` source distribution (sdist) contains a single top-level " +"directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " +"source files of the package. The name and version MUST match the metadata " +"stored in the file. This directory must also contain " +"a :file:`pyproject.toml` in the format defined in :ref:`pyproject-toml-" +"spec`, and a :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" +"Uma distribuição fonte ``.tar.gz`` (sdist) contém um único diretório de " +"nível superior chamado ``{name}-{version}`` (por exemplo, ``foo-1.0``), " +"contendo os arquivos fonte do pacote. O nome e a versão DEVEM corresponder " +"aos metadados armazenados no arquivo. Este diretório também deve conter " +"um :file:`pyproject.toml` no formato definido em :ref:`declaring-build-" +"dependencies` e um arquivo ``PKG-INFO`` contendo metadados no formato " +"descrito na especificação :ref:`core-metadata`. Os metadados DEVEM estar em " +"conformidade com pelo menos a versão 2.2 da especificação de metadados." + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" +"Nenhum outro conteúdo de um sdist é necessário ou definido. Os sistemas de " +"construção podem armazenar qualquer informação necessária no sdist para " +"construir o projeto." + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" +"O tarball deve usar o formato tar pax POSIX.1-2001 moderno, que especifica " +"nomes de arquivo baseados em UTF-8. Em particular, os arquivos de " +"distribuição fonte devem ser legíveis usando o módulo tarfile de biblioteca " +"padrão com o sinalizador aberto 'r:gz'." + +#: ../source/specifications/source-distribution-format.rst:85 +#, fuzzy +msgid "Source distribution archive features" +msgstr "Formato de arquivo de distribuição fonte" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "Desempacotando com o filtro de dados" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "Desempacotando sem o filtro de dados" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "Arquivos de dispositivo (incluindo pipes)." + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +#, fuzzy +msgid "When extracting *sdist* archives:" +msgstr "Gerando arquivos de distribuição" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "Dicas adicionais" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +#, fuzzy +#| msgid "" +#| "This document describes the dependency specifiers format as originally " +#| "specified in :pep:`508`." +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" +"Este documento descreve o formato dos especificadores de dependência " +"conforme originalmente especificado na :pep:`508`." + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "Especificadores de versão" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +#, fuzzy +msgid "Definitions" +msgstr "Especificações" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +#, fuzzy +msgid "Version scheme" +msgstr "Versões" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +#, fuzzy +msgid "Public version identifiers" +msgstr "Identificadores de versão local" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "Segmento de época: ``N!``" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "Segmento de lançamento: ``N(.N)*``" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "Segmento de pré-lançamento: ``{a|b|rc}N``" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "Segmento de pós lançamento: ``.postN``" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "Segmento de versão de desenvolvimento: ``.devN``" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "Letras ASCII (``[a-zA-Z]``)" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "Dígitos ASCII (``[0-9]``)" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "períodos (``.``)" + +#: ../source/specifications/version-specifiers.rst:147 +#, fuzzy +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "Começar e terminar com uma letra ou dígito ASCII." + +#: ../source/specifications/version-specifiers.rst: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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +#, fuzzy +msgid "Final releases" +msgstr "Publicando lançamentos" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "Por exemplo::" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +#, fuzzy +msgid "Pre-releases" +msgstr "Versionamento de pré-lançamento" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +#, fuzzy +msgid "Post-releases" +msgstr "zest.releaser" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "Pós lançamentos também são permitidos para pré-lançamentos::" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "Versões de desenvolvimento" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +#, fuzzy +msgid "Version epochs" +msgstr "Versões" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +msgid "Normalization" +msgstr "Normalização" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "Sensível a maiúsculas e minúsculas" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +#, fuzzy +msgid "Integer Normalization" +msgstr "Normalização" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +#, fuzzy +msgid "Pre-release separators" +msgstr "Versionamento de pré-lançamento" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +#, fuzzy +msgid "Pre-release spelling" +msgstr "Versionamento de pré-lançamento" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "Número de pré-lançamento implícito" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "Separadores de pós lançamento" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +#, fuzzy +msgid "Post release spelling" +msgstr "Versionamento de pré-lançamento" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "Número implícito de pós lançamento" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "Pós lançamentos implícitos" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "Separadores de versões de desenvolvimento" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "Número implícito de versão de desenvolvimento" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +#, fuzzy +msgid "Local version segments" +msgstr "Identificadores de versão local" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "Caractere predecessor v" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +#, fuzzy +msgid "Examples of compliant version schemes" +msgstr "Aqui estão alguns exemplos de números de versão compatíveis::" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +#, fuzzy +msgid "Simple \"major.minor\" versioning::" +msgstr "Versionamento serial" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "Versionamento simples \"major.minor.micro\" ::" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "Ordenação de versões em diferentes versões de metadados" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +#, fuzzy +msgid "Compatibility with other version schemes" +msgstr "Lidando com os wheels universais" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +#, fuzzy +msgid "DVCS based version labels" +msgstr "Versionamento baseado em data" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +#, fuzzy +msgid "Olson database versioning" +msgstr "Versionamento baseado em data" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "``~=``: `Compatible release`_ clause" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "``==``: `Version matching`_ clause" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "``!=``: `Version exclusion`_ clause" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "``<``, ``>``: `Exclusive ordered comparison`_ clause" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "``===``: `Arbitrary equality`_ clause." + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "Versão compatível" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +#, fuzzy +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "Isso significa que os seguintes nomes são todos equivalentes:" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +#, fuzzy +msgid "Version matching" +msgstr "Versão" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +#, fuzzy +msgid "Version exclusion" +msgstr "Especificador de Versão" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "Comparação ordenada inclusiva" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "Comparação ordenada exclusiva" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=``. É RECOMENDADO que apenas hashes que " +"são fornecidos incondicionalmente pela última versão do módulo ``hashlib`` " +"da biblioteca padrão sejam usados para hashes de arquivo fonte. No momento " +"da escrita, essa lista consistia em 'md5', 'sha1', 'sha224', 'sha256', " +"'sha384' e 'sha512'." + +#: ../source/specifications/version-specifiers.rst:1144 +msgid "" +"For source archive and wheel references, an expected hash value may be " +"specified by including a ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +#, fuzzy +msgid "Remote URL examples::" +msgstr "Por exemplo::" + +#: ../source/specifications/version-specifiers.rst:1177 +#, fuzzy +msgid "File URLs" +msgstr "URLs de arquivos" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "Resumo das diferenças em relação a pkg_resources.parse_version" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +#, fuzzy +msgid "Python Virtual Environments" +msgstr "Ambiente Virtual" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +#, fuzzy +msgid "Runtime detection of virtual environments" +msgstr "Ativando um ambiente virtual" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +#, fuzzy +msgid "Declaring installation environments as Python virtual environments" +msgstr "Instalando pacotes usando pip e ambientes virtuais" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +#, fuzzy +msgid "Well-known Project URLs in Metadata" +msgstr "Nome do projeto" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +#, fuzzy +#| msgid "" +#| "This document describes the dependency specifiers format as originally " +#| "specified in :pep:`508`." +msgid "This specification was originally defined in :pep:`753`." +msgstr "" +"Este documento descreve o formato dos especificadores de dependência " +"conforme originalmente especificado na :pep:`508`." + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +#, fuzzy +msgid "Label normalization" +msgstr "Normalização" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +#, fuzzy +msgid "Normalized" +msgstr "Nomes não normalizados válidos" + +#: ../source/specifications/well-known-project-urls.rst:76 +#, fuzzy +#| msgid "Home-page" +msgid "``Homepage``" +msgstr "Home-page" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +#, fuzzy +#| msgid "Home-page" +msgid "``homepage``" +msgstr "Home-page" + +#: ../source/specifications/well-known-project-urls.rst:78 +#, fuzzy +#| msgid "Home-page" +msgid "``Home-page``" +msgstr "Home-page" + +#: ../source/specifications/well-known-project-urls.rst:80 +#, fuzzy +#| msgid "Home page" +msgid "``Home page``" +msgstr "Site" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +#, fuzzy +msgid "``documentation`` (Documentation)" +msgstr "Criando documentação" + +#: ../source/specifications/well-known-project-urls.rst:124 +#, fuzzy +msgid "The project's online documentation" +msgstr "Criando documentação" + +#: ../source/specifications/well-known-project-urls.rst:125 +#, fuzzy +#| msgid "``upload_docs``" +msgid "``docs``" +msgstr "``upload_docs``" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +#, fuzzy +#| msgid "Basic information" +msgid "Funding Information" +msgstr "Informações básicas" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +#, fuzzy +#| msgid "Example" +msgid "Example behavior" +msgstr "Exemplo" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +#, fuzzy +#| msgid "Core metadata specifications" +msgid "Core metadata representation" +msgstr "Especificações de metadados principais" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "Como obter suporte" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" +"Para suporte relacionado a um projeto específico, consulte os links na " +"página :doc:`Projetos `." + +#: ../source/support.rst:8 +msgid "" +"For something more general, or when you're just not sure, please `open an " +"issue `_ on the `packaging-problems `_ repository on GitHub." +msgstr "" +"Para algo mais geral, ou quando você não tiver certeza, por favor `relate o " +"problema `_ no repositório `packaging-problems `_ no GitHub." + +#: ../source/tutorials/creating-documentation.rst:4 +#, fuzzy +msgid "Creating documentation" +msgstr "Criando documentação" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" +"**Tutoriais** são guias passo a passo opinativos para ajudá-lo a se " +"familiarizar com os conceitos de empacotamento. Para obter informações mais " +"detalhadas sobre tópicos de empacotamento específicos, consulte :doc:`/" +"guides/index`." + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "Instalando pacotes" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" +"Esta seção cobre o básico de como instalar :term:`pacotes ` Python." + +#: ../source/tutorials/installing-packages.rst:10 +#, fuzzy +msgid "" +"It's important to note that the term \"package\" in this context is being " +"used to describe a bundle of software to be installed (i.e. as a synonym for " +"a :term:`distribution `). It does not 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 "" +"É importante notar que o termo \"pacote\" neste contexto está sendo usado " +"para descrever um pacote de software a ser instalado (ou seja, como um " +"sinônimo para uma :term:`distribuição `). Não se " +"refere ao tipo de :term:`pacote ` que você importa em " +"seu código-fonte Python (ou seja, um contêiner de módulos). É comum na " +"comunidade Python referir-se a uma :term:`distribuição ` usando o termo \"pacote\". Usar o termo \"distribuição\" " +"geralmente não é preferido, porque pode ser facilmente confundido com uma " +"distribuição Linux ou outra distribuição de software maior como o próprio " +"Python." + +#: ../source/tutorials/installing-packages.rst:24 +msgid "Requirements for Installing Packages" +msgstr "Requisitos para instalar pacotes" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" +"Esta seção descreve as etapas a serem seguidas antes de instalar outros " +"pacotes Python." + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +msgstr "" +"Certifique-se de que você consegue executar Python a partir da linha de " +"comando" + +#: ../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:" +msgstr "" +"Antes de prosseguir, certifique-se de ter o Python e de que a versão " +"esperada está disponível em sua linha de comando. Você pode verificar isso " +"executando:" + +#: ../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 "" +"Você deve obter alguma saída como ``Python 3.6.3``. Se você não tiver o " +"Python, instale a versão 3.x mais recente de `python.org`_ ou consulte a " +"seção :ref:`Instalando Python ` do Guia do " +"Mochileiro para Python." + +#: ../source/tutorials/installing-packages.rst:53 +msgid "If you're a newcomer and you get an error like this:" +msgstr "Se você for um novato e receber um erro como este:" + +#: ../source/tutorials/installing-packages.rst:62 +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." +msgstr "" +"É porque este comando e outros comandos sugeridos neste tutorial devem ser " +"executados em um *shell* (também chamado de *terminal* ou *console*). Veja o " +"`tutorial de introdução`_ para iniciantes do Python para uma introdução " +"sobre como usar o shell do seu sistema operacional e interagir com o Python." + +#: ../source/tutorials/installing-packages.rst:68 +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:" +msgstr "" +"Se estiver usando um shell aprimorado como o IPython ou o notebook Jupyter, " +"você pode executar comandos do sistema como os deste tutorial precedendo-os " +"com um caractere ``!``:" + +#: ../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 "" +"É recomendado escrever ``{sys.executable}`` em vez de ``python`` simples " +"para garantir que os comandos sejam executados na instalação do Python " +"correspondendo ao ambiente em execução (que pode não ser o mesmo Python " +"instalação à qual o comando ``python`` se refere)." + +#: ../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 "" +"Devido à forma como a maioria das distribuições Linux está lidando com a " +"migração Python 3, os usuários Linux usando o sistema Python sem criar um " +"ambiente virtual primeiro devem substituir o comando ``python`` neste " +"tutorial por ``python3`` e o comando ``python -m pip`` com ``python3 -m pip " +"--user``. *Não* execute nenhum dos comandos neste tutorial com ``sudo``: se " +"você receber um erro de permissão, volte para a seção sobre como criar " +"ambientes virtuais, configure um e então continue com o tutorial como " +"escrito." + +#: ../source/tutorials/installing-packages.rst:95 +msgid "Ensure you can run pip from the command line" +msgstr "" +"Certifique-se de que você pode executar o pip a partir da linha de comando" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" +"Além disso, você precisa ter certeza de ter :ref:`pip` disponível. Você pode " +"verificar isso executando:" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" +"Se você instalou Python a partir do código-fonte, com um instalador de " +"`python.org`_, ou via `Homebrew`_, você já deve ter o pip. Se você estiver " +"no Linux e instalado usando o gerenciador de pacotes do sistema operacional, " +"pode ser necessário instalar o pip separadamente, consulte :doc:`/guides/" +"installing-using-linux-tools`." + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" +"Se o ``pip`` ainda não estiver instalado, tente primeiro inicializá-lo a " +"partir da biblioteca padrão:" + +#: ../source/tutorials/installing-packages.rst:134 +msgid "If that still doesn't allow you to run ``python -m pip``:" +msgstr "Se isso ainda não permitir que você execute ``python -m pip``:" + +#: ../source/tutorials/installing-packages.rst:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" +"Baixe com segurança `get-pip.py `_ [1]_" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" +"Execute ``python get-pip.py``. [2]_ Isso vai instalar ou atualizar o pip. " +"Adicionalmente, vai instalar :ref:`setuptools` e :ref:`wheel` se ainda não " +"estiverem instalados." + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" +"Tenha cuidado se estiver usando uma instalação do Python gerenciada por seu " +"sistema operacional ou outro gerenciador de pacotes. get-pip.py não coordena " +"com essas ferramentas e pode deixar seu sistema em um estado inconsistente. " +"Você pode usar ``python get-pip.py --prefix=/usr/local/`` para instalar em " +"``/usr/local`` que é projetado para software instalado localmente." + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "Certifique-se que pip, setuptools e wheel estejam atualizados" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" +"Embora ``pip`` sozinho seja suficiente para instalar a partir de arquivos " +"binários pré-compilados, cópias atualizadas dos projetos ``setuptools`` e " +"``wheel`` são úteis para garantir que você também possa instalar a partir de " +"arquivos fonte:" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "Opcionalmente, crie um ambiente virtual" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"See :ref:`section below ` for " +"details, but here's the basic :doc:`venv ` [3]_ command " +"to use on a typical Linux system:" +msgstr "" +"Veja a :ref:`seção abaixo ` para " +"detalhes, mas aqui está o comando básico de :doc:`venv ` [3]_ para usar em um sistema Linux típico:" + +#: ../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 "" +"Isso criará um novo ambiente virtual no subdiretório ``tutorial_env`` e " +"configurará o shell atual para usá-lo como o ambiente ``python`` padrão." + +#: ../source/tutorials/installing-packages.rst:199 +msgid "Creating Virtual Environments" +msgstr "Criando ambientes virtuais" + +#: ../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 "" +"\"Ambientes virtuais\" do Python permitem que :term:`pacotes ` Python sejam instalados em um local isolado para uma " +"aplicação em particular, ao invés de serem instalados globalmente. Se você " +"deseja instalar ferramentas de linha de comando globais com segurança, " +"consulte :doc:`/guides/installing-stand-alone-command-line-tools`." + +#: ../source/tutorials/installing-packages.rst:207 +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." +msgstr "" +"Imagine que você tenha uma aplicação que precisa da versão 1 do LibFoo, mas " +"outra aplicação requer a versão 2. Como você pode usar essas duas " +"aplicações? Se você instalar tudo em /usr/lib/python3.6/site-packages (ou " +"qualquer que seja o local padrão de sua plataforma), é fácil acabar em uma " +"situação em que você atualiza acidentalmente uma aplicação que não deveria " +"ser atualizada." + +#: ../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 "" +"Ou, de forma mais geral, e se você quiser instalar uma aplicação e deixá-la " +"como está? Se uma aplicação funcionar, qualquer alteração em suas " +"bibliotecas ou nas versões dessas bibliotecas pode interromper a aplicação." + +#: ../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 "" +"Além disso, e se você não puder instalar :term:`pacotes ` no diretório global site-packages? Por exemplo, em um host " +"compartilhado." + +#: ../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 "" +"Em todos esses casos, os ambientes virtuais podem lhe ajudar. Eles têm seus " +"próprios diretórios de instalação e não compartilham bibliotecas com outros " +"ambientes virtuais." + +#: ../source/tutorials/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" +"Atualmente, existem duas ferramentas comuns para a criação de ambientes " +"virtuais Python:" + +#: ../source/tutorials/installing-packages.rst:226 +#, fuzzy +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" +":doc:`venv ` está disponível por padrão no Python 3.3 e " +"posterior, e instala :ref:`pip` e :ref:`setuptools` em ambientes virtuais " +"criados no Python 3.4 e posterior." + +#: ../source/tutorials/installing-packages.rst:229 +#, fuzzy +#| 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)." +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" +":ref:`virtualenv` precisa ser instalado separadamente, mas oferece suporte a " +"Python 2.7+ e Python 3.3+, e :ref:`pip`, :ref:`setuptools` e :ref:`wheel` " +"são sempre instalados em ambientes virtuais criados por padrão " +"(independentemente da versão Python)." + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "O uso básico é assim:" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "Usando :doc:`venv `:" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "Usando :ref:`virtualenv`:" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" +"Para mais informações, veja a documentação do :doc:`venv ` ou do :doc:`virtualenv `." + +#: ../source/tutorials/installing-packages.rst:271 +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)." +msgstr "" +"O uso de :command:`source` em shells Unix garante que as variáveis do " +"ambiente virtual sejam definidas dentro do shell atual, e não em um " +"subprocesso (que então desaparece, sem nenhum efeito útil)." + +#: ../source/tutorials/installing-packages.rst:276 +#, fuzzy +msgid "" +"In both of the above cases, Windows users should *not* use " +"the :command:`source` command, but should rather run the :command:`activate` " +"script directly from the command shell like so:" +msgstr "" +"Em ambos os casos acima, os usuários Windows não devem _não_ usar o " +"comando :command:`source`, mas devem executar o script :command:`activate` " +"diretamente do shell de comando assim:" + +#: ../source/tutorials/installing-packages.rst:286 +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 "" +"Gerenciar vários ambientes virtuais diretamente pode se tornar tedioso, " +"então o :ref:`tutorial de gerenciamento de dependências ` apresenta uma ferramenta de alto nível, :ref:`Pipenv`, que " +"gerencia automaticamente um ambiente virtual separado para cada projeto e " +"aplicação no qual você trabalha." + +#: ../source/tutorials/installing-packages.rst:293 +msgid "Use pip for Installing" +msgstr "Usar pip para instalação" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" +":ref:`pip` é o instalador recomendado. A seguir, cobriremos os cenários de " +"uso mais comuns. Para obter mais detalhes, consulte a :doc:`documentação do " +"pip `, que inclui um :doc:`Guia de Referências ` " +"completo." + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "Instalando a partir do PyPI" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" +"O uso mais comum do :ref:`pip` é instalar a partir do :term:`Python Package " +"Index ` usando um :term:`especificador de " +"requisitos `. De modo geral, um especificador " +"de requisitos é composto de um nome de projeto seguido por " +"um :term:`especificador de versão ` opcional . A " +"descrição completa dos especificadores suportados podem ser encontrados " +"na :ref:`especificação de especificadores de versão `. " +"Abaixo estão alguns exemplos." + +#: ../source/tutorials/installing-packages.rst:311 +msgid "To install the latest version of \"SomeProject\":" +msgstr "Para instalar a versão mais recente de \"SomeProject\":" + +#: ../source/tutorials/installing-packages.rst:325 +msgid "To install a specific version:" +msgstr "Para instalar uma versão específica:" + +#: ../source/tutorials/installing-packages.rst:339 +msgid "To install greater than or equal to one version and less than another:" +msgstr "Para instalar maior ou igual a uma versão e menor que outra:" + +#: ../source/tutorials/installing-packages.rst:354 +#, fuzzy +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" +"Para instalar uma versão que é :pep:`\"compatível\" <440#compatible-" +"release>` com uma determinada versão: [4]_" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" +"Nesse caso, isso significa instalar qualquer versão \"==1.4.*\" que também " +"seja \">=1.4.2\"." + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "Distribuições de fonte 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` pode instalar a partir de :term:`Distribuições Fonte (sdist) " +"` ou :term:`Wheels `, mas se ambos " +"estiverem presentes no PyPI, pip irá preferir um :term:`wheel ` " +"compatível. Você pode substituir o comportamento padrão do pip, por exemplo " +"usando sua opção :ref:`--no-binary `." + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" +":term:`Wheels ` são um formato de :term:`distribuição ` pré-construído que fornece uma instalação mais rápida em " +"comparação com :term:`Distribuições Fonte (sdist) `, especialmente quando um projeto contém extensões compiladas." + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" +"Se :ref:`pip` não encontrar um wheel para instalar, ele irá construir um " +"wheel localmente e armazená-lo em cache para instalações futuras, ao invés " +"de reconstruir a distribuição fonte no futuro." + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "Atualize um ``SomeProject`` já instalado para o mais recente do PyPI." + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "Instalando para o site do usuário" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" +"Para instalar :term:`pacotes ` que são isolados para " +"o usuário atual, use o sinalizador ``--user``:" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" +"Para obter mais informações, consulte a seção `User Installs `_ da documentação do pip." + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +msgstr "" +"Observe que o sinalizador ``--user`` não tem efeito quando dentro de um " +"ambiente virtual -- todos os comandos de instalação afetarão o ambiente " +"virtual." + +#: ../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`:" +msgstr "" +"Se ``SomeProject`` definir quaisquer scripts de linha de comando ou pontos " +"de entrada de console, ``--user`` fará com que sejam instalados dentro do " +"diretório binário da `base do usuário`_, que pode ou não já estar presente " +"em seu :envvar:`PATH` do shell. (A partir da versão 10, pip exibe um aviso " +"ao instalar qualquer script em um diretório fora de :envvar:`PATH`.) Se os " +"scripts não estiverem disponíveis em seu shell após a instalação, você " +"precisará adicionar o diretório ao seu :envvar:`PATH`:" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" +"No Linux e no macOS você pode encontrar o diretório binário da base do " +"usuário executando ``python -m site --user-base`` e adicionando ``bin`` no " +"final. Por exemplo, isso normalmente imprimirá ``~/.local`` (com ``~`` " +"expandido para o caminho absoluto para o seu diretório inicial), então você " +"precisará adicionar ``~/.local/bin`` para seu ``PATH``. Você pode definir " +"seu ``PATH`` permanentemente `modificando ~/.profile`_." + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" +"No Windows você pode encontrar o diretório binário base do usuário " +"executando ``py -m site --user-site`` e substituindo ``site-packages`` por " +"``Scripts``. Por exemplo, isso poderia retornar ``C:" +"\\Users\\Username\\AppData\\Roaming\\Python36\\site-packages``, então você " +"precisaria definir seu ``PATH`` para incluir ``C:" +"\\Users\\Username\\AppData\\Roaming\\Python36\\Scripts``. Você pode definir " +"seu usuário ``PATH`` permanentemente no `Painel de Controle`_. Você pode " +"precisar encerrar a sessão para que as alterações de ``PATH`` tenham efeito." + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" +"Instale uma lista de requisitos especificados em um :ref:`arquivo de " +"requisitos `." + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "Instalando a partir de VCS" + +#: ../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 `." +msgstr "" +"Instale um projeto a partir de VCS em um modo \"editável\". Para um " +"instrução completa da sintaxe, veja a seção do pip em :ref:`VCS Support " +"`." + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "Instalando a partir de outros índices" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "Instalar a partir de um índice alternativo" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" +"Pesquise um índice adicional durante a instalação, além do :term:`PyPI " +"`" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "Instalando a partir de uma árvore de fontes local" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" +"Instale a partir dos fontes locais em :doc:`Development Mode " +"`, ou seja, de tal forma que o " +"projeto parece estar instalado, mas ainda seja editável a partir da árvore " +"de fontes." + +#: ../source/tutorials/installing-packages.rst:558 +msgid "You can also install normally from src" +msgstr "Você também pode instalar normalmente a partir dos fontes" + +#: ../source/tutorials/installing-packages.rst:573 +msgid "Installing from local archives" +msgstr "Instalando de arquivos locais" + +#: ../source/tutorials/installing-packages.rst:575 +msgid "Install a particular source archive file." +msgstr "Instale um arquivo de pacote fonte em particular." + +#: ../source/tutorials/installing-packages.rst:589 +msgid "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" +"Instale de um pacote contendo diretório local (e não verifique o :term:`PyPI " +"`)" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "Instalando a partir de outras fontes" + +#: ../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 "" +"Para instalar a partir de outras fontes de dados (por exemplo, armazenamento " +"Amazon S3), você pode criar uma aplicação auxiliar que apresente os dados em " +"um formato compatível com a :ref:`API de repositório simples `, e usar o sinalizador ``--extra-index-url`` para direcionar " +"o pip para usar esse índice." + +#: ../source/tutorials/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "Instalando pré-lançamentos" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" +"Encontre versões de pré-lançamento e desenvolvimento, além de versões " +"estáveis. Por padrão, pip só encontra versões estáveis." + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "Instalando \"Extras\"" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" +"Extras são \"variantes\" opcionais de um pacote, que podem incluir " +"dependências adicionais e, assim, habilitar funcionalidades adicionais do " +"pacote. Se você deseja instalar um extra para um pacote que você sabe que " +"publica um, você pode incluí-lo no comando de instalação pip:" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" +"\"Segurança\" neste contexto significa usar um navegador moderno ou uma " +"ferramenta como :command:`curl` que verifica os certificados SSL ao baixar " +"de URLs https." + +#: ../source/tutorials/installing-packages.rst:675 +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`." +msgstr "" +"Começando com Python 3.4, ``venv`` (uma alternativa à biblioteca padrão " +"para :ref:`virtualenv`) criará ambientes do virtualenv com ``pip`` pré-" +"instalado, tornando-o uma alternativa igual a :ref:`virtualenv`." + +#: ../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" +msgstr "" +"O especificador de versão compatível foi aceito em :pep:`440` e o suporte " +"foi lançado em :ref:`setuptools` v8.0 e :ref:`pip` v6.0" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "Gerenciando dependências de aplicações" + +#: ../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." +msgstr "" +"O :ref:`tutorial de instalação do pacote ` cobriu os " +"fundamentos da configuração para instalar e atualizar pacotes Python." + +#: ../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." +msgstr "" +"No entanto, executar esses comandos interativamente pode se tornar tedioso " +"até mesmo para seus próprios projetos pessoais, e as coisas ficam ainda mais " +"difíceis ao tentar configurar ambientes de desenvolvimento automaticamente " +"para projetos com vários contribuidores." + +#: ../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 "" +"Este tutorial orienta você no uso de :ref:`Pipenv` para gerenciar " +"dependências para uma aplicação. Ele mostrará como instalar e usar as " +"ferramentas necessárias e fará recomendações fortes sobre as melhores " +"práticas." + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" +"Lembre-se de que Python é usado para muitos propósitos diferentes e, " +"precisamente, como você deseja gerenciar suas dependências pode mudar com " +"base em como você decide publicar seu software. A orientação apresentada " +"aqui é mais diretamente aplicável ao desenvolvimento e implantação de " +"serviços de rede (incluindo aplicações web), mas também é muito adequada " +"para gerenciar ambientes de desenvolvimento e teste para qualquer tipo de " +"projeto." + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" +"Para alternativas, veja `Outras ferramentas para gerenciamento de " +"dependências de aplicações`_." + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "Instalando Pipenv" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" +":ref:`Pipenv` é um gerenciador de dependências para projetos Python. Se você " +"está familiarizado com o `npm`_ do Node.js ou o `bundler`_ do Ruby, é " +"semelhante em espírito a essas ferramentas. Enquanto :ref:`pip` por si só " +"costuma ser suficiente para uso pessoal, Pipenv é recomendado para projetos " +"colaborativos por ser uma ferramenta de nível superior que simplifica o " +"gerenciamento de dependências para casos de uso comuns." + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "Use ``pip`` para instalar Pipenv:" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" +"fIsso faz uma `instalação do usuário`_ para evitar quebrar qualquer pacote " +"do sistema. Se ``pipenv`` não estiver disponível em seu shell após a " +"instalação, você precisará adicionar o diretório binário da :py:data:`base " +"de usuário ` ao seu ``PATH``. Veja :ref:`Instalando " +"no Site do Usuário ` para mais informações." + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "Instalando pacotes para seu projeto" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +msgstr "" +"O Pipenv gerencia dependências por projeto. Para instalar pacotes, mude para " +"o diretório do seu projeto (ou apenas um diretório vazio para este tutorial) " +"e execute:" + +#: ../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):" +msgstr "" +"Pipenv irá instalar a biblioteca `Requests`_ e criar um ``Pipfile`` para " +"você no diretório do seu projeto. O :ref:`Pipfile` é usado para rastrear " +"quais dependências seu projeto precisa no caso de você precisar reinstalá-" +"las, como quando você compartilha seu projeto com outras pessoas. Você deve " +"obter uma saída semelhante a esta (embora os caminhos exatos mostrados " +"variem):" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "Usando pacotes 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 "" +"Agora que Requests está instalado você pode criar um :file:`main.py` simples " +"para usá-lo:" + +#: ../source/tutorials/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "Então, você pode executar este script usando ``pipenv run``:" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "Você deve obter uma saída similar a esta:" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" +"Usar ``pipenv run`` garante que seus pacotes instalados estejam disponíveis " +"para seu script. Também é possível gerar um novo shell que garante que todos " +"os comandos tenham acesso aos seus pacotes instalados com ``pipenv shell``." + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "Próximos passos" + +#: ../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 "" +"Parabéns, agora você sabe como gerenciar dependências e ambientes de " +"desenvolvimento com eficácia em um projeto colaborativo Python! ✨ 🍰 ✨" + +#: ../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 "" +"Se você estiver interessado em criar e distribuir seus próprios pacotes " +"Python, veja o :ref:`tutorial sobre empacotamento e distribuição de pacotes " +"`." + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" +"Observe que quando sua aplicação inclui definições de pacotes fonte do " +"Python, elas (e suas dependências) podem ser adicionadas ao seu ambiente de " +"``pipenv`` com ``pipenv install -e `` " +"(por exemplo, ``pipenv install -e .`` ou ``pipenv install -e src``)." + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "Outras ferramentas para gerenciamento de dependências de aplicações" + +#: ../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 "" +"Se você achar que essa abordagem específica para gerenciar dependências de " +"aplicações não está funcionando bem para você ou seu caso de uso, convém " +"explorar essas outras ferramentas e técnicas, listadas em ordem alfabética, " +"para ver se uma delas se encaixa melhor:" + +#: ../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 `_ para uma cobertura opinativa de " +"ainda mais etapas no fluxo de trabalho de gerenciamento de projeto, como " +"incrementar versões e criar novos projetos básicos a partir de modelos de " +"projeto." + +#: ../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 "" +"micropipenv `_ para um " +"invólucro leve do pip que oferece suporte a ``requirements.txt``, arquivos " +"de bloqueio de Pipenv e de Poetry ou convertê-los em saída compatível com " +"pip-tools. Projetado para aplicações em contêineres Python, mas não se " +"limitando a elas." + +#: ../source/tutorials/managing-dependencies.rst:170 +#, fuzzy +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" +"`PDM `_ para uma ferramenta moderna de " +"gerenciamento de pacotes Python que oferece suporte a :pep:`582` " +"(substituindo ambientes virtuais pelo diretório ``__pypackages__`` para " +"instalação de pacotes) e contando com padrões como :pep:`517` e :pep:`621`." + +#: ../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 "" +"`pip-tools `_ para criar um arquivo " +"de bloqueio de todas as dependências de uma lista de pacotes usados " +"diretamente em um projeto e garantir que apenas essas dependências estão " +"instalados." + +#: ../source/tutorials/managing-dependencies.rst:175 +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." +msgstr "" +"`Poetry `__ para uma ferramenta " +"comparável em escopo a Pipenv que se concentra mais diretamente em casos de " +"uso onde o projeto sendo gerenciado é estruturado como um pacote Python " +"distribuível com um arquivo ``pyproject.toml`` válido. Por outro lado, " +"Pipenv explicitamente evita fazer a suposição de que a aplicação na qual " +"está sendo trabalhada será compatível com a distribuição como um pacote " +"Python instalável com ``pip``." + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "Empacotando projetos Python" + +#: ../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 "" +"Este tutorial mostra como empacotar um projeto Python simples. Ele mostrará " +"como adicionar os arquivos e a estrutura necessários para criar o pacote, " +"como construir o pacote e como enviá-lo para o Índice de Pacotes do 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 "" +"Se você tiver problemas para executar os comandos neste tutorial, copie o " +"comando e sua saída e, em seguida, `relate um problema`_ no repositório " +"`packaging-problems`_ no GitHub. Faremos o nosso melhor para ajudá-lo!" + +#: ../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:" +msgstr "" +"Alguns comandos exigem uma nova versão de :ref:`pip`, então comece " +"certificando-se de que você tenha a versão mais recente instalada:" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "Um projeto simples" + +#: ../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 "" +"Este tutorial usa um projeto simples chamado " +"``example_package_YOUR_USERNAME_HERE``. Se seu nome de usuário for ``me``, " +"então o pacote seria ``example_package_me``; isso garante que você tenha um " +"nome de pacote exclusivo que não entre em conflito com os pacotes carregados " +"por outras pessoas seguindo este tutorial. Recomendamos seguir este tutorial " +"como está usando este projeto, antes de empacotar seu próprio projeto." + +#: ../source/tutorials/packaging-projects.rst:44 +msgid "Create the following file structure locally:" +msgstr "Crie a seguinte estrutura de arquivos localmente:" + +#: ../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 "" +"O diretório que contém os arquivos Python deve corresponder ao nome do " +"projeto. Isso simplifica a configuração e é mais óbvio para os usuários que " +"instalam o pacote." + +#: ../source/tutorials/packaging-projects.rst:57 +#, fuzzy +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" +":file:`__init__.py` é necessário para importar o diretório como um pacote, e " +"deve estar vazio." + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" +":file:`example.py` é um exemplo de módulo dentro do pacote que pode conter a " +"lógica (funções, classes, constantes, etc.) do seu pacote. Abra esse arquivo " +"e insira o seguinte conteúdo:" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" +"Se você não está familiarizado com :term:`módulos ` e :term:`pacotes " +"de importação ` do Python, reserve alguns minutos para " +"ler a `documentação do Python para pacotes e módulos`_." + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"Once you create this structure, you'll want to run all of the commands in " +"this tutorial within the ``packaging_tutorial`` directory." +msgstr "" +"Depois de criar esta estrutura, você desejará executar todos os comandos " +"neste tutorial dentro do diretório ``packaging_tutorial``." + +#: ../source/tutorials/packaging-projects.rst:83 +msgid "Creating the package files" +msgstr "Criando arquivos do pacote" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" +"Agora você adicionará arquivos que são usados para preparar o projeto para " +"distribuição. Quando terminar, a estrutura do projeto ficará assim:" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "Criando um diretório de teste" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" +":file:`tests/` é um espaço reservado, ou *placeholder*, para arquivos de " +"teste. Deixe-o vazio por enquanto." + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "Escolhendo uma construção de backend" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +#, fuzzy +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 "" +":file:`pyproject.toml` diz a ferramentas de construção \"frontend\" " +"como :ref:`pip` e :ref:`build` qual ferramenta \"backend\" usar para " +"criar :term:`pacotes de distribuição ` para o seu " +"projeto. Você pode escolher entre vários backends; este tutorial " +"usa :ref:`Hatchling ` por padrão, mas funcionará de forma idêntica " +"com :ref:`setuptools`, :ref:`Flit `, :ref:`PDM ` e outros que " +"oferecem suporte à tabela ``[project]`` para :ref:`metadados `." + +#: ../source/tutorials/packaging-projects.rst:129 +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 "" +"Alguns backends de construção fazem parte de ferramentas maiores que " +"fornecem uma interface de linha de comando com recursos adicionais, como " +"inicialização de projeto e gerenciamento de versão, além de construção, " +"envio e instalação de pacotes. Este tutorial usa ferramentas de propósito " +"único que funcionam de forma independente." + +#: ../source/tutorials/packaging-projects.rst:134 +#, fuzzy +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." +msgstr "" +":file:`pyproject.toml` informa as ferramentas de construção (como :ref:`pip` " +"e :ref:`build`) o que é necessário para construir seu projeto. Este tutorial " +"usa :ref:`setuptools`, então abra :file:`pyproject.toml` e insira o seguinte " +"conteúdo:" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +#, fuzzy +msgid "" +"The ``build-backend`` key is the name of the Python object that frontends " +"will use to perform the build." +msgstr "" +"``build-backend`` é o nome do objeto Python que os frontends usarão para " +"executar a construção." + +#: ../source/tutorials/packaging-projects.rst:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "Configurando metadados" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" +"Abra :file:`pyproject.toml` e insira o seguinte conteúdo. Mude o ``name`` " +"para incluir seu nome de usuário; isso garante que você tenha um nome de " +"pacote exclusivo que não entre em conflito com os pacotes carregados por " +"outras pessoas que seguem este tutorial." + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" +"``name`` é o *nome da distribuição* do seu pacote. Pode ser qualquer nome, " +"desde que contenha apenas letras, números, ``.``, ``_`` e ``-``. Também não " +"deve ser feito em PyPI. **Certifique-se de atualizá-lo com seu nome de " +"usuário** para este tutorial, pois isso garante que você não tentará enviar " +"um pacote com o mesmo nome de um que já existe." + +#: ../source/tutorials/packaging-projects.rst:201 +#, fuzzy +msgid "" +"``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`` é a versão do pacote. Veja a :ref:`especificação de " +"especificadores de versão ` para mais detalhes sobre as " +"versões. Alguns backends de construção permitem que ela seja especificada de " +"outra maneira, como a partir de um arquivo ou de uma tag git." + +#: ../source/tutorials/packaging-projects.rst:203 +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." +msgstr "" +"``authors`` é usado para identificar o autor do pacote; você especifica um " +"nome e um e-mail para cada autor. Você também pode listar ``maintainers`` no " +"mesmo formato." + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "``description`` é um resumo curto do pacote contendo apenas uma frase." + +#: ../source/tutorials/packaging-projects.rst:207 +#, 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`` é um caminho para um arquivo contendo uma descrição detalhada do " +"pacote. Isso é mostrado na página de detalhes do pacote em PyPI. Neste caso, " +"a descrição é carregada de :file:`README.md` (que é um padrão comum). Há " +"também um formulário de tabela mais avançado descrito na :ref:`especificação " +"de metadados do projeto `." + +#: ../source/tutorials/packaging-projects.rst:212 +#, fuzzy +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." +msgstr "" +"``requires-python`` fornece as versões do Python suportadas pelo seu " +"projeto. Instaladores como :ref:`pip` olharão para as versões anteriores dos " +"pacotes até encontrar um que tenha uma versão correspondente do Python." + +#: ../source/tutorials/packaging-projects.rst:215 +#, fuzzy +#| 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/." +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on and which operating systems your package " +"will work on. For a complete list of classifiers, see https://pypi.org/" +"classifiers/." +msgstr "" +"``classifiers`` fornece o índice e :ref:`pip` alguns metadados adicionais " +"sobre seu pacote. Nesse caso, o pacote é compatível apenas com Python 3, " +"está licenciado sob a licença MIT e é independente do sistema operacional. " +"Você deve sempre incluir pelo menos a(s) versão(ões) do Python em que seu " +"pacote funciona, em que licença seu pacote está disponível e em quais " +"sistemas operacionais seu pacote funcionará. Para obter uma lista completa " +"de classificadores, consulte https://pypi.org/classifiers/." + +#: ../source/tutorials/packaging-projects.rst:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +#, fuzzy +#| msgid "" +#| "Now run this command from the same directory where :file:`pyproject.toml` " +#| "is located:" +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" +"Agora, execute este comando a partir do mesmo diretório no " +"qual :file:`pyproject.toml` está localizado:" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" +"``urls`` permite listar qualquer número de links extras para mostrar no " +"PyPI. Geralmente, isso pode ser para o código-fonte, a documentação, os " +"rastreadores de problemas, etc." + +#: ../source/tutorials/packaging-projects.rst:229 +#, fuzzy +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." +msgstr "" +"Veja a :ref:`especificação de metadados do projeto ` para detalhes sobre estes e outros campos que podem ser definidos " +"na tabela ``[project]``. Outros campos comuns são ``keywords`` para melhorar " +"a descoberta e as ``dependencies`` que são necessárias para instalar seu " +"pacote." + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "Criando README.md" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" +"Abra :file:`README.md` e insira o seguinte conteúdo. Você pode personalizar " +"isso se desejar." + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "Criando um LICENSE" + +#: ../source/tutorials/packaging-projects.rst:253 +#, fuzzy +#| 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:" +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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 "" +"É importante que cada pacote enviado para o Índice de Pacotes do Python " +"inclua uma licença. Isso informa aos usuários que instalam seu pacote os " +"termos sob os quais eles podem usá-lo. Para obter ajuda na escolha de uma " +"licença, consulte https://choosealicense.com/. Depois de escolher uma " +"licença, abra :file:`LICENSE` e digite o texto da licença. Por exemplo, se " +"você escolheu a licença MIT:" + +#: ../source/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "Incluindo outros arquivos" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" +"Os arquivos listados acima serão incluídos automaticamente em " +"sua :term:`distribuição fonte `. Se você " +"deseja incluir arquivos adicionais, veja a documentação para seu backend de " +"construção." + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "Gerando arquivos de distribuição" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" +"O próximo passo é gerar :term:`pacotes de distribuição ` para o pacote. Estes são arquivos que são enviados para o " +"Índice de Pacotes do Python e podem ser instalados pelo :ref:`pip`." + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" +"Certifique-se de que você tenha a versão mais recente da :ref:`construção " +"` do PyPA instalada:" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" +"Se você tiver problemas ao instalá-los, veja o tutorial :doc:`installing-" +"packages`." + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" +"Agora, execute este comando a partir do mesmo diretório no " +"qual :file:`pyproject.toml` está localizado:" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" +"Este comando deve produzir muito texto e, uma vez concluído, deve gerar dois " +"arquivos no diretório :file:`dist`:" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" +"O arquivo ``tar.gz`` é um :term:`distribuição fonte ` enquanto o arquivo ``.whl`` é uma :term:`distribuição " +"construída `. As versões :ref:`pip` mais recentes " +"instalam preferencialmente distribuições construídas, mas irão recorrer às " +"distribuições fonte se necessário. Você deve sempre enviar uma distribuição " +"fonte e fornecer distribuições construídas para as plataformas com as quais " +"seu projeto é compatível. Neste caso, nosso pacote de exemplo é compatível " +"com Python em qualquer plataforma, portanto, apenas uma distribuição " +"construída é necessária." + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "Enviando os arquivos de distribuição" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" +"Finalmente, é hora de enviar seu pacote para o Índice de Pacotes do Python!" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" +"A primeira coisa que você precisa fazer é registrar uma conta no Test PyPI, " +"que é uma instância separada do índice do pacote destinada a teste e " +"experimentação. É ótimo para coisas como este tutorial, em que não queremos " +"necessariamente enviar para o índice real. Para registrar uma conta, vá em " +"https://test.pypi.org/account/register/ e conclua as etapas nessa página. " +"Você também precisará verificar seu endereço de e-mail antes de enviar " +"qualquer pacote. Para mais detalhes, veja :doc:`/guides/using-testpypi`." + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" +"Para enviar seu projeto com segurança, você precisará de um `token de API`_ " +"do PyPI. Crie um em https://test.pypi.org/manage/account/#api-tokens, " +"definindo o \"Escopo\" como \"Toda a conta\". **Não feche a página antes de " +"copiar e salvar o token -- você não verá o token novamente.**" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" +"Agora que você está registrado, você pode usar :ref:`twine` para enviar os " +"pacotes de distribuição. Você precisará instalar o Twine:" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" +"Uma vez instalado, execute o Twine para enviar de todos os arquivos " +"em :file:`dist`:" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "" +"Depois que o comando for concluído, você deverá ver uma saída semelhante a " +"esta:" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" +"Depois de enviado, seu pacote pode ser visto no Test PyPI; por exemplo: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "Instalando seu pacote recém-enviado" + +#: ../source/tutorials/packaging-projects.rst:424 +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 "" +"Você pode usar o :ref:`pip` para instalar seu pacote e verificar se ele " +"funciona. Crie um :ref:`ambiente virtual ` e instale seu pacote a partir do Test PyPI:" + +#: ../source/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "Certifique-se de especificar seu nome de usuário no nome do pacote!" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" +"pip deve instalar o pacote de Test PyPI e a saída deve ser semelhante a esta:" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" +"Este exemplo usa o sinalizador ``--index-url`` para especificar Test PyPI em " +"vez do PyPI real. Além disso, ele especifica ``--no-deps``. Como o Test PyPI " +"não tem os mesmos pacotes que o PyPI real, é possível que a tentativa de " +"instalação de dependências falhe ou instale algo inesperado. Embora nosso " +"pacote de exemplo não tenha nenhuma dependência, é uma boa prática evitar " +"instalar dependências ao usar o Test PyPI." + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" +"Você pode testar se ele foi instalado corretamente importando o pacote. " +"Certifique-se de que ainda está em seu ambiente virtual e execute o Python:" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "e importe o pacote:" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "**Parabéns, você empacotou e distribuiu um projeto Python!** ✨ 🍰 ✨" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" +"Lembre-se de que este tutorial mostrou como enviar o seu pacote para Test " +"PyPI, que não é um armazenamento permanente. O sistema de teste " +"ocasionalmente exclui pacotes e contas. É melhor usar Test PyPI para testes " +"e experimentos como este tutorial." + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" +"Quando estiver pronto para carregar um pacote real para o Índice de Pacotes " +"do Python, você pode fazer quase o mesmo que fez neste tutorial, mas com " +"estas diferenças importantes:" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" +"Escolha um nome único e memorável para o seu pacote. Você não precisa " +"acrescentar seu nome de usuário como fez no tutorial, mas você não pode usar " +"um nome existente." + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" +"Registre uma conta em https://pypi.org -- observe que esses são dois " +"servidores separados e os detalhes de login do servidor de teste não são " +"compartilhados com o servidor principal." + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" +"Use ``twine upload dist/*`` para enviar seu pacote e insira suas credenciais " +"para a conta que você registrou no PyPI real. Agora que você está enviando o " +"pacote em produção, você não precisa especificar ``--repository``; o pacote " +"será enviado para https://pypi.org/ por padrão." + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" +"Instale seu pacote a partir do PyPI real usando ``python3 -m pip install " +"[seu-pacote]``." + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" +"Neste ponto, se você quiser ler mais sobre o empacotamento de bibliotecas " +"Python, aqui estão algumas coisas que você pode fazer:" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" +"Considere as ferramentas de empacotamento que fornecem uma única interface " +"de linha de comando para gerenciamento e empacotamento de projetos, " +"como :ref:`hatch`, :ref:`flit`, :ref:`pdm` e :ref:`poetry`." + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "Notas" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" + +#~ msgid "" +#~ "Refer to the `pkg_resources documentation `__ for more details." +#~ msgstr "" +#~ "Confira a `documentação de pkg_resources `__ para mais detalhes." + +#~ msgid "" +#~ "A complete working example of two pkg_resources-style namespace packages " +#~ "can be found in the `pkg_resources namespace example project`_." +#~ msgstr "" +#~ "Um exemplo de completamente funcional de dois pacotes de espaço de nomes " +#~ "no estilo pkg_resources pode ser encontrado no `projeto exemplo de espaço " +#~ "de nomes de pkg_resources`_." + +#~ msgid "" +#~ "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." +#~ msgstr "" +#~ "RECORD.jws é usado para assinaturas digitais. Não é mencionado no RECORD." + +#~ 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 "" +#~ "RECORD.p7s é permitido como cortesia para qualquer pessoa que prefira " +#~ "usar assinaturas S/MIME para proteger seus arquivos wheels. Não é " +#~ "mencionado no RECORD." + +#~ msgid "Signed wheel files" +#~ msgstr "Arquivos wheels assinados" + +#~ 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::" +#~ msgstr "" +#~ "Os arquivos wheels incluem um RECORD estendido que permite assinaturas " +#~ "digitais. O RECORD da PEP 376 foi alterado para incluir um hash seguro " +#~ "``digestname=urlsafe_b64encode_nopad(digest)`` (codificação base64 de " +#~ "urlsafe sem caracteres ao final =) como a segunda coluna em vez de um " +#~ "md5sum. Todas as entradas possíveis são hash, incluindo quaisquer " +#~ "arquivos gerados, como arquivos .pyc, mas não RECORD, que não pode conter " +#~ "seu próprio hash. Por exemplo::" + +#~ 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." +#~ msgstr "" +#~ "O(s) arquivo(s) de assinatura RECORD.jws e RECORD.p7s não são mencionados " +#~ "em RECORD, pois eles só podem ser adicionados após RECORD ser gerado. " +#~ "Todos os outros arquivos no arquivo devem ter um hash correto em RECORD " +#~ "ou a instalação falhará." + +#, fuzzy +#~ msgid "" +#~ "If JSON web signatures are used, one or more JSON Web Signature JSON " +#~ "Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent " +#~ "to RECORD. JWS is used to sign RECORD by including the SHA-256 hash of " +#~ "RECORD as the signature's JSON payload:" +#~ msgstr "" +#~ "Se assinaturas da web JSON forem usadas, uma ou mais assinaturas JSON Web " +#~ "Signature JSON Serialization (JWS-JS) serão armazenadas em um arquivo " +#~ "RECORD.jws adjacente a RECORD. JWS é usado para assinar RECORD incluindo " +#~ "o hash SHA-256 de RECORD como a carga JSON da assinatura::" + +#~ msgid "(The hash value is the same format used in RECORD.)" +#~ msgstr "(O valor hash é o mesmo formato usado em RECORD.)" + +#~ msgid "" +#~ "If RECORD.p7s is used, it must contain a detached S/MIME format signature " +#~ "of RECORD." +#~ msgstr "" +#~ "Se RECORD.p7s for usado, ele deve conter uma assinatura de formato S/MIME " +#~ "separada de RECORD." + +#~ 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." +#~ msgstr "" +#~ "Um instalador de wheel não precisa entender as assinaturas digitais, mas " +#~ "DEVE verificar os hashes em RECORD em relação ao conteúdo do arquivo " +#~ "extraído. Quando o instalador verifica os hashes do arquivo em relação ao " +#~ "RECORD, um verificador de assinatura separado só precisa estabelecer se " +#~ "RECORD corresponde à assinatura." + +#~ msgid "See" +#~ msgstr "Veja" + +#~ msgid "https://datatracker.ietf.org/doc/html/rfc7515" +#~ msgstr "https://datatracker.ietf.org/doc/html/rfc7515" + +#~ msgid "" +#~ "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" +#~ "serialization-01" +#~ msgstr "" +#~ "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" +#~ "serialization-01" + +#~ msgid "https://datatracker.ietf.org/doc/html/rfc7517" +#~ msgstr "https://datatracker.ietf.org/doc/html/rfc7517" + +#~ msgid "" +#~ "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" +#~ msgstr "" +#~ "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" + +#~ msgid "Why does wheel include attached signatures?" +#~ msgstr "Por que o wheel inclui assinaturas anexadas?" + +#~ 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." +#~ msgstr "" +#~ "Assinaturas anexadas são mais convenientes do que assinaturas separadas " +#~ "porque elas viajam com o arquivo. Uma vez que apenas os arquivos " +#~ "individuais são assinados, o arquivo pode ser recompactado sem invalidar " +#~ "a assinatura ou os arquivos individuais podem ser verificados sem ter que " +#~ "baixar todo o arquivo." + +#~ msgid "Why does wheel allow JWS signatures?" +#~ msgstr "Por que wheel permite assinaturas JWS?" + +#~ msgid "" +#~ "The JOSE specifications of which JWS is a part are designed to be easy to " +#~ "implement, a feature that is also one of wheel's primary design goals. " +#~ "JWS yields a useful, concise pure-Python implementation." +#~ msgstr "" +#~ "As especificações JOSE das quais o JWS faz parte foram projetadas para " +#~ "serem fáceis de implementar, um recurso que também é um dos principais " +#~ "objetivos do projeto da roda. O JWS produz uma implementação puro Python " +#~ "concisa e útil." + +#~ msgid "Why does wheel also allow S/MIME signatures?" +#~ msgstr "Por que wheel também permite assinaturas S/MIME?" + +#~ msgid "" +#~ "S/MIME signatures are allowed for users who need or want to use existing " +#~ "public key infrastructure with wheel." +#~ msgstr "" +#~ "Assinaturas S/MIME são permitidas para usuários que precisam ou querem " +#~ "usar uma infraestrutura de chaves públicas existente com o wheel." + +#~ msgid "" +#~ "Signed packages are only a basic building block in a secure package " +#~ "update system. Wheel only provides the building block." +#~ msgstr "" +#~ "Pacotes assinados são apenas um bloco de construção básico em um sistema " +#~ "de atualização segura de pacotes. Wheel só fornece o bloco de construção." + +#, fuzzy +#~| msgid "The minimum required versions of the respective tools are:" +#~ msgid "The license expressions for these projects are:" +#~ msgstr "As versões mínimas exigidas das respectivas ferramentas são:" + +#~ msgid "`Vagrant `_" +#~ msgstr "`Vagrant `_" + +#, fuzzy +#~| msgid ":ref:`pyproject-toml-spec`" +#~ msgid "**Inspiration**: :ref:` pyproject-tool-table`" +#~ msgstr ":ref:`pyproject-toml-spec`" + +#~ msgid "Signing the distribution packages" +#~ msgstr "Assinando os pacotes de distribuição" + +#~ msgid "" +#~ "The following job signs the distribution packages with `Sigstore`_, the " +#~ "same artifact signing system `used to sign CPython `_." +#~ msgstr "" +#~ "O trabalho a seguir assina os pacotes de distribuição com `Sigstore`_, o " +#~ "mesmo sistema de assinatura de artefato `usado para assinar o CPython " +#~ "`_." + +#~ 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 "" +#~ "Em primeiro lugar, ele usa `sigstore/gh-action-sigstore-python do GitHub " +#~ "Action`_ para assinar os pacotes de distribuição. Na próxima etapa, uma " +#~ "versão vazia do GitHub da tag atual é criada usando a CLI ``gh``. Observe " +#~ "que esta etapa pode ser ainda mais personalizada. Consulte a " +#~ "`documentação de lançamento do gh `_ como referência." + +#~ 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." +#~ msgstr "" +#~ "Pode ser necessário gerenciar suas permissões do ``GITHUB_TOKEN`` para " +#~ "permitir a criação da versão do GitHub. Consulte a `documentação do " +#~ "GitHub `_ para obter instruções. Especificamente, o " +#~ "token precisa da permissão ``contents: write``." + +#~ msgid "" +#~ "Finally, the signed distributions are uploaded to the GitHub Release." +#~ msgstr "" +#~ "Finalmente, as distribuições assinadas são enviadas para o GitHub Release." + +#~ 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." +#~ msgstr "" +#~ "Este é um substituto para assinaturas GPG, para as quais o suporte foi " +#~ "`removido do PyPI `_. No entanto, este trabalho não é obrigatório para o envio para PyPI e " +#~ "pode ser omitido." + +#, fuzzy +#~| msgid "" +#~| "This can take two forms. You can put your license in a file, typically " +#~| "``LICENSE`` or ``LICENSE.txt``, and link that file here:" +#~ msgid "" +#~ "This can take two forms. You can put your license in a file, " +#~ "typically :file:`LICENSE` or :file:`LICENSE.txt`, and link that file here:" +#~ msgstr "" +#~ "Isto pode tomar duas formas. Você pode colocar sua licença em um arquivo, " +#~ "tipicamente ``LICENSE`` ou ``LICENSE.txt``, e vincular esse arquivo aqui:" + +#~ msgid "or you can write the name of the license:" +#~ msgstr "ou você pode escrever o nome da licença:" + +#, fuzzy +#~ msgid "" +#~ "If you are using a standard, well-known license, it is not necessary to " +#~ "use this field. Instead, you should use one of the :ref:`classifiers` " +#~ "starting with ``License ::``. (As a general rule, it is a good idea to " +#~ "use a standard, well-known license, both to avoid confusion and because " +#~ "some organizations avoid software whose license is unapproved.)" +#~ msgstr "" +#~ "O argumento ``license`` é mais comumente usado para indicar diferenças de " +#~ "licenças conhecidas ou para incluir sua própria licença exclusiva. Como " +#~ "regra geral, é uma boa ideia usar uma licença padrão bem conhecida, tanto " +#~ "para evitar confusão quanto porque algumas organizações evitam software " +#~ "cuja licença não é aprovada." + +#, fuzzy +#~ msgid "Additional file information" +#~ msgstr "Notas adicionais" + +#~ msgid "" +#~ "Most build backends automatically include license files in packages. See " +#~ "your backend's documentation for more details." +#~ msgstr "" +#~ "A maioria dos backends de construção inclui automaticamente arquivos de " +#~ "licença em pacotes. Consulte a documentação do seu backend para obter " +#~ "mais detalhes." + +#~ 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." +#~ msgstr "" +#~ "conda é a ferramenta de gerenciamento de pacotes para as instalações do " +#~ "`Anaconda `__ Python . Anaconda " +#~ "Python é uma distribuição do `Anaconda, Inc `__ voltada especificamente para a comunidade " +#~ "científica, e em particular no Windows onde a instalação de extensões " +#~ "binárias é frequentemente difícil ." + +#~ 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." +#~ msgstr "" +#~ "Você será solicitado a fornecer um nome de usuário e uma senha. Para o " +#~ "nome de usuário, use ``__token__``. Para a senha, use o valor do token, " +#~ "incluindo o prefixo ``pypi-``." + +#~ msgid "Update this page for build backends other than setuptools." +#~ msgstr "Atualizar esta página para construir backends além do setuptools." + +#~ msgid "" +#~ "Read the file in :file:`setup.py` and get the version. Example (from `pip " +#~ "setup.py `_)::" +#~ msgstr "" +#~ "Leia o arquivo em :file:`setup.py` e obtenha a versão. Exemplo (do " +#~ "`setup.py do pip `_)::" + +#~ 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 "" +#~ "A partir do lançamento do setuptools 46.4.0, pode-se realizar a mesma " +#~ "coisa colocando o seguinte no arquivo :file:`setup.cfg` do projeto " +#~ "(substituindo \"pacote\" pelo nome de importação do pacote):" + +#~ msgid "" +#~ "As of the release of setuptools 61.0.0, one can specify the version " +#~ "dynamically in the project's :file:`pyproject.toml` file." +#~ msgstr "" +#~ "A partir do lançamento do setuptools 61.0.0, pode-se especificar a versão " +#~ "dinamicamente no arquivo :file:`pyproject.toml` do projeto." + +#~ msgid "" +#~ "Please be aware that declarative config indicators, including the " +#~ "``attr:`` directive, are not supported in parameters to :file:`setup.py`." +#~ msgstr "" +#~ "Esteja ciente de que os indicadores de configuração declarativos, " +#~ "incluindo a diretiva ``attr:``, não são suportados em parâmetros " +#~ "para :file:`setup.py`." + +#~ msgid "" +#~ "Use an external build tool that either manages updating both locations, " +#~ "or offers an API that both locations can use." +#~ msgstr "" +#~ "Use uma ferramenta de construção externa que gerencia a atualização de " +#~ "ambos os locais ou oferece uma API que ambos os locais podem usar." + +#~ msgid "" +#~ "Few tools you could use, in no particular order, and not necessarily " +#~ "complete: `bump2version `_, " +#~ "`changes `_, `commitizen `_, `zest.releaser `_." +#~ msgstr "" +#~ "Poucas ferramentas que você poderia usar, sem nenhuma ordem específica, e " +#~ "não necessariamente completas: `bump2version `_, `changes `_, " +#~ "`commitizen `_, `zest.releaser " +#~ "`_." + +#~ msgid "" +#~ "Set the value to a ``__version__`` global variable in a dedicated module " +#~ "in your project (e.g. :file:`version.py`), then have :file:`setup.py` " +#~ "read and ``exec`` the value into a variable." +#~ msgstr "" +#~ "Defina o valor para uma variável global ``__version__`` em um módulo " +#~ "dedicado em seu projeto (por exemplo, :file:`version.py`), então faça com " +#~ "que :file:`setup.py` leia e execute (``exec``) o valor em uma variável." + +#~ msgid "" +#~ "Example using this technique: `warehouse `_." +#~ msgstr "" +#~ "Exemplo usando esta técnica: `warehouse `_." + +#~ msgid "" +#~ "Place the value in a simple ``VERSION`` text file and have " +#~ "both :file:`setup.py` and the project code read it." +#~ msgstr "" +#~ "Coloque o valor em um arquivo de texto simples ``VERSION`` e tenha " +#~ "ambos :file:`setup.py` e o código do projeto lidos." + +#~ msgid "" +#~ "An advantage with this technique is that it's not specific to Python. " +#~ "Any tool can read the version." +#~ msgstr "" +#~ "Uma vantagem dessa técnica é que ela não é específica do Python. Qualquer " +#~ "ferramenta pode ler a versão." + +#~ msgid "" +#~ "With this approach you must make sure that the ``VERSION`` file is " +#~ "included in all your source and binary distributions (e.g. add ``include " +#~ "VERSION`` to your :file:`MANIFEST.in`)." +#~ msgstr "" +#~ "Com esta abordagem, você deve se certificar de que o arquivo ``VERSION`` " +#~ "está incluído em todas as suas distribuições de fonte e binárias (por " +#~ "exemplo, adicione ``include VERSION`` ao seu :file:`MANIFEST.in`)." + +#~ 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::" +#~ msgstr "" +#~ "Defina o valor em :file:`setup.py` e faça com que o código do projeto use " +#~ "a API ``importlib.metadata`` para buscar o valor em tempo de execução. " +#~ "(``importlib.metadata`` foi introduzido no Python 3.8 e está disponível " +#~ "para versões anteriores como o projeto ``importlib-metadata``.) A versão " +#~ "de um projeto instalado pode ser obtida com a API da seguinte forma::" + +#~ msgid "" +#~ "Be aware that the ``importlib.metadata`` API only knows about what's in " +#~ "the installation metadata, which is not necessarily the code that's " +#~ "currently imported." +#~ msgstr "" +#~ "Esteja ciente de que a API ``importlib.metadata`` só sabe sobre o que " +#~ "está nos metadados de instalação, o que não é necessariamente o código " +#~ "que está importado no momento." + +#~ msgid "" +#~ "If a project uses this method to fetch its version at runtime, then its " +#~ "``install_requires`` value needs to be edited to install ``importlib-" +#~ "metadata`` on pre-3.8 versions of Python like so::" +#~ msgstr "" +#~ "Se um projeto usa este método para buscar sua versão em tempo de " +#~ "execução, então seu valor ``install_requires`` precisa ser editado para " +#~ "instalar ``importlib-metadata`` em versões pré-3.8 do Python como::" + +#~ msgid "" +#~ "An older (and less efficient) alternative to ``importlib.metadata`` is " +#~ "the ``pkg_resources`` API provided by ``setuptools``::" +#~ msgstr "" +#~ "’Uma alternativa mais antiga (e menos eficiente) ao " +#~ "``importlib.metadata`` é a API ``pkg_resources`` fornecida pelo " +#~ "``setuptools``::" + +#~ 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 "" +#~ "Se um projeto usa ``pkg_resources`` para buscar sua própria versão em " +#~ "tempo de execução, então ``setuptools`` deve ser adicionado à lista " +#~ "``install_requires`` do projeto." + +#~ msgid "" +#~ "Example using this technique: `setuptools `_." +#~ msgstr "" +#~ "Exemplo usando esta técnica: `setuptools `_." + +#~ msgid "" +#~ "Set the value to ``__version__`` in ``sample/__init__.py`` and import " +#~ "``sample`` in :file:`setup.py`." +#~ msgstr "" +#~ "Defina o valor para ``__version__`` em ``sample/__init__.py`` e importe " +#~ "``sample`` no :file:`setup.py`." + +#~ msgid "" +#~ "Although this technique is common, beware that it will fail if ``sample/" +#~ "__init__.py`` imports packages from ``install_requires`` dependencies, " +#~ "which will very likely not be installed yet when :file:`setup.py` is run." +#~ msgstr "" +#~ "Embora esta técnica seja comum, esteja ciente que ela vai falhar se " +#~ "``sample/__init__.py`` importar pacotes de dependências " +#~ "``install_requires``, que muito provavelmente ainda não estarão " +#~ "instalados quando :file:`setup.py` for executado." + +#~ 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 `_." +#~ msgstr "" +#~ "Mantenha o número da versão nas tags de um sistema de controle de versão " +#~ "(Git, Mercurial, etc), em vez de no código, e extraia-o automaticamente " +#~ "de lá usando `setuptools_scm `_." + +#~ 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 "" +#~ "Há uma diferença significativa entre as tabelas ``[build-system]`` e " +#~ "``[project]``. O primeiro deve estar sempre presente, independentemente " +#~ "de qual backend de construção você usa (já que *define* a ferramenta que " +#~ "você usa). Este último é entendido pela *maioria* dos backends de " +#~ "construção mas alguns backends de construção usam um formato diferente." + +#~ msgid "" +#~ "Additionally, the user:password section of the URL MAY be a well-known, " +#~ "non security sensitive string. A typical example is ``git`` in the case " +#~ "of an URL such as ``ssh://git@gitlab.com/user/repo``." +#~ msgstr "" +#~ "Além disso, a seção usuário:senha da URL PODE ser uma string bem " +#~ "conhecida e não sensível à segurança. Um exemplo típico é ``git`` no caso " +#~ "de uma URL como ``ssh://git@gitlab.com/user/repo``." + +#~ 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." +#~ msgstr "" +#~ "Este guia é especificamente para usuários de :ref:`setuptools`, outras " +#~ "ferramentas de empacotamento como ``flit`` podem oferecer funcionalidade " +#~ "semelhante, mas os usuários precisarão consultar a documentação relevante." + +#~ msgid "This workflow requires that:" +#~ msgstr "Este fluxo de trabalho exige que:" + +#~ msgid "The publisher is using the latest version of :ref:`setuptools`," +#~ msgstr "O editor esteja usando a versão mais recente de :ref:`setuptools`," + +#~ msgid "The latest version of :ref:`twine` is used to upload the package," +#~ msgstr "A última versão do :ref:`twine` seja usada para enviar o pacote," + +#~ 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." +#~ msgstr "" +#~ "Visto que ser possível sobrescrever as configurações de :file:`setup.cfg` " +#~ "via sinalizadores CLI, certifique-se de que seus scripts não tenham ``--" +#~ "universal`` em seus scripts de criação de pacote." + +#~ msgid "1. Download the newest version of Setuptools" +#~ msgstr "1. Baixe a versão mais recente do Setuptools" + +#~ msgid "" +#~ "Ensure that before you generate source distributions or binary " +#~ "distributions, you update Setuptools and install twine." +#~ msgstr "" +#~ "Certifique-se de, antes de gerar distribuições de fontes ou distribuições " +#~ "binárias, atualizar o Setuptools e instalar o twine." + +#~ msgid "Steps:" +#~ msgstr "Passos:" + +#~ msgid "``setuptools`` version should be above 24.0.0." +#~ msgstr "A versão do ``setuptools`` deve ser superior a 24.0.0." + +#~ msgid "" +#~ "The way to set those values is within the call to ``setup`` within " +#~ "your :file:`setup.py` script. This will insert the ``Requires-Python`` " +#~ "metadata values based on the argument you provide in ``python_requires``." +#~ msgstr "" +#~ "A maneira de definir esses valores está na chamada de ``setup`` dentro do " +#~ "seu script :file:`setup.py`. Isso irá inserir os valores de metadados " +#~ "``Requires-Python`` com base no argumento fornecido em " +#~ "``python_requires``." + +#~ msgid "4. Using Twine to publish" +#~ msgstr "4. Usando Twine para publicar" + +#~ msgid "" +#~ "Twine has a number of advantages, apart from being faster it is now the " +#~ "supported method for publishing packages." +#~ msgstr "" +#~ "Twine tem uma série de vantagens, além de ser mais rápido, agora é o " +#~ "método suportado para publicação de pacotes." + +#~ msgid "Make sure you are using the newest version of Twine, at least 1.9." +#~ msgstr "" +#~ "Certifique-se de estar usando a versão mais recente do Twine, pelo menos " +#~ "1.9." + +#~ msgid "" +#~ "Once you have published a package with the Requires-Python metadata, you " +#~ "can then make a further update removing that Python runtime from support." +#~ msgstr "" +#~ "Depois de publicar um pacote com os metadados de Requires-Python, você " +#~ "pode fazer uma atualização adicional removendo esse tempo de execução " +#~ "Python do suporte." + +#~ msgid "It must be done in this order for the automated fallback to work." +#~ msgstr "" +#~ "Deve ser feito nesta ordem para que o alternativa automatizada funcione." + +#~ msgid "" +#~ "For example, you published the Requires-Python: \">=2.7\" as version " +#~ "1.0.0 of your package." +#~ msgstr "" +#~ "Por exemplo, você publicou o Requires-Python: \">=2.7\" como a versão " +#~ "1.0.0 do seu pacote." + +#~ 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 "" +#~ "Se você atualizasse a string da versão para \">=3.5\" e publicasse uma " +#~ "nova versão 2.0.0 do seu pacote, todos os usuários executando o Pip 9.0+ " +#~ "a partir da versão 2.7 terão a versão 1.0.0 do pacote instalada e " +#~ "qualquer >=3.5 usuários receberão a versão 2.0.0." + +#~ msgid "" +#~ "The standard :term:`Built Distribution` format. See :ref:`package-" +#~ "formats` for more information." +#~ msgstr "" +#~ "O formato padrão de :term:`Distribuição Construída`. Veja :ref:`package-" +#~ "formats` para mais informações." + +#~ msgid "The summary description of the project." +#~ msgstr "A descrição resumida do projeto." + +#~ 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 "" +#~ "Uma chave ``required_revision`` (tipo ``string``) PODE estar presente " +#~ "nomeando um branch/tag/ref/commit/revisão/etc (em um formato compatível " +#~ "com o VCS)." + +#~ msgid "Wheel vs Egg" +#~ msgstr "Wheel vs 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` e :term:`Egg` são formatos de empacotamento que visam " +#~ "oferecer suporte ao caso de uso de necessidade de um artefato de " +#~ "instalação que não requer construção ou compilação, o que pode ser caro " +#~ "em testes e fluxos de trabalho de produção." + +#~ msgid "" +#~ ":term:`Wheel` is currently considered the standard for :term:`built " +#~ "` and :term:`binary ` packaging " +#~ "for Python." +#~ msgstr "" +#~ ":term:`Wheel` é atualmente considerado o padrão para o " +#~ "empacotamento :term:`contruído ` e :term:`binário " +#~ "` para Python." + +#~ msgid "" +#~ ":term:`Egg` uploads have been disabled for upload to PyPI, " +#~ "per :pep:`715`. Read the `deprecation notice `_ for more information." +#~ msgstr "" +#~ "Envio de :term:`Egg` foram desativados para o envio para o PyPI, " +#~ "conforme :pep:`715`. Leia o `aviso de descontinuação `_ para mais " +#~ "informações." + +#~ 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 "" +#~ "Um formato :term:`Distribuição Construída` introduzido " +#~ "por :ref:`setuptools`, que está sendo substituído por :term:`Wheel`. Para " +#~ "obter detalhes, consulte :doc:`The Internal Structure of Python Eggs " +#~ "` e `Python Eggs `_" + +#~ 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 "" +#~ "Um formato de :term:`Distribuição Construída` introduzido por " +#~ "um :doc:`especificação de padrão ` oficial, que se destina a substituir o formato :term:`Egg`. O " +#~ "Wheel é atualmente suportado pelo :ref:`pip`." + +#~ msgid "" +#~ "If you're familiar with Python packaging and installation, and just want " +#~ "to know what tools are currently recommended, then here it is." +#~ msgstr "" +#~ "Se você está familiarizado com o pacote e a instalação do Python e só " +#~ "deseja saber quais ferramentas são recomendadas atualmente, aqui está." + +#~ msgid "Application dependency management" +#~ msgstr "Gerenciamento de dependências de aplicações" + +#~ msgid "" +#~ "Use :ref:`pip` in a `secure manner`_ to install a Python application and " +#~ "its dependencies during deployment." +#~ msgstr "" +#~ "Use :ref:`pip` de uma `maneira segura`_ para instalar um aplicativo " +#~ "Python e suas dependências durante a implantação." + +#~ msgid "" +#~ "Use :ref:`virtualenv` or :doc:`venv ` to isolate " +#~ "application-specific dependencies from a shared Python installation. [4]_" +#~ msgstr "" +#~ "Use :ref:`virtualenv` ou :doc:`venv ` para isolar " +#~ "dependências específicas da aplicação de uma instalação compartilhada do " +#~ "Python. [4]_" + +#~ msgid "" +#~ "Use `pip-tools`_, :ref:`pipenv`, or `poetry`_ to generate the fully-" +#~ "specified application-specific dependencies, when developing Python " +#~ "applications." +#~ msgstr "" +#~ "Use `pip-tools`_, :ref:`pipenv`, ou `poetry`_ para gerar as dependências " +#~ "específicas da aplicação totalmente especificadas, ao desenvolver " +#~ "aplicações Python." + +#~ msgid "Installation tool recommendations" +#~ msgstr "Recomendações de ferramentas de instalação" + +#~ msgid "" +#~ "Use :ref:`pip` to install Python :term:`packages ` " +#~ "from :term:`PyPI `. [1]_ [2]_ Depending on " +#~ "how :ref:`pip` is installed, you may need to also install :ref:`wheel` to " +#~ "get the benefit of wheel caching. [3]_" +#~ msgstr "" +#~ "Use :ref:`pip` para instalar :term:`pacotes ` do " +#~ "Python a partir do :term:`PyPI `. [1]_ [2]_ " +#~ "Dependendo de como :ref:`pip` é instalado, você também pode precisar " +#~ "instalar o :ref:`wheel` para obter o benefício do armazenamento em cache " +#~ "do wheel. [3]_" + +#~ msgid "" +#~ "Use :ref:`virtualenv` or :doc:`venv ` to isolate " +#~ "project-specific dependencies from a shared Python installation. [4]_" +#~ msgstr "" +#~ "Use :ref:`virtualenv` ou :doc:`venv ` para isolar " +#~ "dependências específicas do projeto de uma instalação compartilhada do " +#~ "Python. [4]_" + +#~ msgid "" +#~ "If you're looking for management of fully integrated cross-platform " +#~ "software stacks, consider:" +#~ msgstr "" +#~ "Se você estiver procurando por gerenciamento de pilhas de software " +#~ "multiplataforma totalmente integradas, considere:" + +#~ msgid ":ref:`buildout`: primarily focused on the web development community" +#~ msgstr "" +#~ ":ref:`buildout`: focado principalmente na comunidade de desenvolvimento " +#~ "web" + +#~ msgid "" +#~ ":ref:`spack`, :ref:`hashdist`, or :ref:`conda`: primarily focused on the " +#~ "scientific community." +#~ msgstr "" +#~ ":ref:`spack`, :ref:`hashdist` ou :ref:`conda`: focado principalmente na " +#~ "comunidade científica." + +#~ msgid "Packaging tool recommendations" +#~ msgstr "Recomendações de ferramentas de empacotamento" + +#~ msgid "Use :ref:`setuptools` to define projects. [5]_ [6]_" +#~ msgstr "Use :ref:`setuptools` para definir projetos. [5]_ [6]_" + +#~ msgid "" +#~ "Use :ref:`build` to create :term:`Source Distributions ` and :term:`wheels `." +#~ msgstr "" +#~ "Use :ref:`build` para criar :term:`Distribuições Fontes ` e :term:`wheels `." + +#~ msgid "" +#~ "Use `twine `_ for uploading distributions " +#~ "to :term:`PyPI `." +#~ msgstr "" +#~ "Use `twine `_ para enviar distribuições " +#~ "para o :term:`PyPI `." + +#~ msgid "Publishing platform migration" +#~ msgstr "Migração da plataforma de publicação" + +#~ msgid "" +#~ "The original Python Package Index implementation (previously hosted at " +#~ "`pypi.python.org `_) has been phased out in " +#~ "favour of an updated implementation hosted at `pypi.org `_." +#~ msgstr "" +#~ "A implementação do Python Package Index original (anteriormente hospedada " +#~ "em `pypi.python.org `_) foi eliminada em favor " +#~ "de uma implementação atualizada hospedada em `pypi.org `_." + +#~ msgid "" +#~ "See :ref:`Migrating to PyPI.org` for more information on the status of " +#~ "the migration, and what settings to change in your clients." +#~ msgstr "" +#~ "Veja :ref:`Migrando para PyPI.org ` para mais " +#~ "informações sobre o status da migração, e quais configurações alterar em " +#~ "seus clientes." + +#~ msgid "" +#~ "There are some cases where you might choose to use ``easy_install`` " +#~ "(from :ref:`setuptools`), e.g. if you need to install from :term:`Eggs " +#~ "` (which pip doesn't support). For a detailed breakdown, " +#~ "see :ref:`pip vs easy_install`." +#~ msgstr "" +#~ "Existem alguns casos em que você pode escolher usar ``easy_install`` " +#~ "(do :ref:`setuptools`), por exemplo se você precisar instalar a partir " +#~ "de :term:`Eggs ` (que pip não oferece suporte). Para uma análise " +#~ "detalhada, consulte :ref:`pip vs easy_install`." + +#~ msgid "" +#~ "The acceptance of :pep:`453` means that :ref:`pip` will be available by " +#~ "default in most installations of Python 3.4 or later. See " +#~ "the :pep:`rationale section <453#rationale>` from :pep:`453` as for why " +#~ "pip was chosen." +#~ msgstr "" +#~ "A aceitação da :pep:`453` significa que :ref:`pip` estará disponível por " +#~ "padrão na maioria das instalações do Python 3.4 ou posterior. Veja " +#~ "a :pep:`seção de motivos <453#rationale>` da :pep:`453` para saber por " +#~ "que pip foi escolhido." + +#~ msgid "" +#~ "`get-pip.py `_ " +#~ "and :ref:`virtualenv` install :ref:`wheel`, whereas :ref:`ensurepip` " +#~ "and :ref:`venv ` do not currently. Also, the common \"python-pip\" " +#~ "package that's found in various linux distros, does not depend on " +#~ "\"python-wheel\" currently." +#~ msgstr "" +#~ "`get-pip.py `_ " +#~ "e :ref:`virtualenv` instalam :ref:`wheel`, enquanto :ref:`ensurepip` " +#~ "e :ref:`venv ` não instalam atualmente. Além disso, o pacote comum " +#~ "\"python-pip\" que é encontrado em várias distros do Linux, não depende " +#~ "do \"python-wheel\" atualmente." + +#~ msgid "" +#~ "Beginning with Python 3.4, ``venv`` will create virtualenv environments " +#~ "with ``pip`` installed, thereby making it an equal alternative " +#~ "to :ref:`virtualenv`. However, using :ref:`virtualenv` will still be " +#~ "recommended for users that need cross-version consistency." +#~ msgstr "" +#~ "A partir do Python 3.4, ``venv`` criará ambientes virtualenv com ``pip`` " +#~ "instalado, tornando-o uma alternativa igual a :ref:`virtualenv`. No " +#~ "entanto, usar :ref:`virtualenv` ainda será recomendado para usuários que " +#~ "precisam de consistência entre versões." + +#~ msgid "" +#~ "Although you can use pure :ref:`distutils` for many projects, it does not " +#~ "support defining dependencies on other projects and is missing several " +#~ "convenience utilities for automatically populating distribution metadata " +#~ "correctly that are provided by ``setuptools``. Being outside the standard " +#~ "library, ``setuptools`` also offers a more consistent feature set across " +#~ "different versions of Python, and (unlike ``distutils``), recent versions " +#~ "of ``setuptools`` support all of the modern metadata fields described " +#~ "in :ref:`core-metadata`." +#~ msgstr "" +#~ "Embora você possa usar :ref:`distutils` puro para muitos projetos, ele " +#~ "não oferece suporta à definição de dependências em outros projetos e não " +#~ "possui vários utilitários de conveniência para preencher automaticamente " +#~ "os metadados de distribuição fornecidos pelo ``setuptools``. Estando fora " +#~ "da biblioteca padrão, ``setuptools`` também oferece um conjunto de " +#~ "recursos mais consistente em diferentes versões do Python e (ao contrário " +#~ "de ``distutils``), versões recentes do ``setuptools`` oferecem suporte a " +#~ "todos os campos de metadados modernos descritos em :ref:`core-metadata`." + +#~ msgid "" +#~ "Even for projects that do choose to use ``distutils``, when :ref:`pip` " +#~ "installs such projects directly from source (rather than installing from " +#~ "a prebuilt :term:`wheel ` file), it will actually build your " +#~ "project using :ref:`setuptools` instead." +#~ msgstr "" +#~ "Mesmo para projetos que escolhem usar ``distutils``, quando o :ref:`pip` " +#~ "instala tais projetos diretamente da fonte (ao invés de instalar de um " +#~ "arquivo :term:`wheel ` pré-construído), ele irá, na verdade, " +#~ "construir seu projeto usando :ref:`setuptools`." + +#~ msgid "" +#~ "`distribute`_ (a fork of setuptools) was merged back " +#~ "into :ref:`setuptools` in June 2013, thereby making setuptools the " +#~ "default choice for packaging." +#~ msgstr "" +#~ "`distribute`_ (um fork do setuptools) foi mesclado no :ref:`setuptools` " +#~ "em junho de 2013, tornando assim setuptools a escolha padrão para " +#~ "empacotamento." + +#~ msgid "Standards compliance for interoperability" +#~ msgstr "Conformidade de padrões para interoperabilidade" + +#~ msgid "Here are some examples of compliant version numbers::" +#~ msgstr "Aqui estão alguns exemplos de números de versão compatíveis::" + +#~ msgid "" +#~ "To further accommodate historical variations in approaches to version " +#~ "numbering, :pep:`440` also defines a comprehensive technique " +#~ "for :pep:`version normalisation <440#normalization>` that maps variant " +#~ "spellings of different version numbers to a standardised canonical form." +#~ msgstr "" +#~ "Para acomodar ainda mais as variações históricas nas abordagens de " +#~ "numeração de versão, :pep:`440` também define uma técnica abrangente " +#~ "para :pep:`normalização de versão <440#normalization>` que mapeia grafias " +#~ "variantes de diferentes números de versão para uma forma canônica " +#~ "padronizada." + +#~ msgid "Scheme choices" +#~ msgstr "Opções de esquema" + +#~ msgid "" +#~ "For new projects, the recommended versioning scheme is based on `Semantic " +#~ "Versioning `_, but adopts a different approach to " +#~ "handling pre-releases and build metadata." +#~ msgstr "" +#~ "Para novos projetos, o esquema de controle de versão recomendado é " +#~ "baseado em `Versionamento semântico `_, mas adota " +#~ "uma abordagem diferente para lidar com pré-lançamentos e metadados de " +#~ "compilação." + +#~ msgid "" +#~ "Adopting this approach as a project author allows users to make use " +#~ "of :pep:`\"compatible release\" <440#compatible-release>` specifiers, " +#~ "where ``name ~= X.Y`` requires at least release X.Y, but also allows any " +#~ "later release with a matching MAJOR version." +#~ msgstr "" +#~ "Adotar essa abordagem como autor do projeto permite que os usuários façam " +#~ "uso dos especificadores de :pep:`\"lançamentos compatíveis\" " +#~ "<440#compatible-release>`, onde ``name ~= X.Y`` requer pelo menos a " +#~ "versão X.Y, mas também permite qualquer versão posterior com uma versão " +#~ "PRINCIPAL correspondente." + +#~ msgid "Date based versioning" +#~ msgstr "Versionamento baseado em data" + +#~ msgid "" +#~ "Version numbers for date based projects typically take the form of " +#~ "YEAR.MONTH (for example, ``12.04``, ``15.10``)." +#~ msgstr "" +#~ "Os números de versão para projetos baseados em data normalmente assumem a " +#~ "forma de ANO.MÊS (por exemplo, ``12.04``, ``15.10``)." + +#~ msgid "" +#~ "This is the simplest possible versioning scheme, and consists of a single " +#~ "number which is incremented every release." +#~ msgstr "" +#~ "Este é o esquema de versionamento mais simples possível e consiste em um " +#~ "único número que é incrementado a cada versão." + +#~ msgid "Pre-release versioning" +#~ msgstr "Versionamento de pré-lançamento" + +#~ msgid "" +#~ "Regardless of the base versioning scheme, pre-releases for a given final " +#~ "release may be published as:" +#~ msgstr "" +#~ "Independentemente do esquema de versionamento base, os pré-lançamentos " +#~ "para uma determinada versão final podem ser publicados como:" + +#~ msgid "zero or more dev releases (denoted with a \".devN\" suffix)" +#~ msgstr "zero ou mais versões dev (denotadas com um sufixo \".devN\")" + +#~ msgid "zero or more alpha releases (denoted with a \".aN\" suffix)" +#~ msgstr "zero ou mais versões alfa (denotadas com um sufixo \".aN\")" + +#~ msgid "zero or more beta releases (denoted with a \".bN\" suffix)" +#~ msgstr "zero ou mais versões beta (denotadas com um sufixo \".bN\")" + +#~ msgid "zero or more release candidates (denoted with a \".rcN\" suffix)" +#~ msgstr "" +#~ "zero ou mais candidatos a lançamento (denotados com um sufixo \".rcN\")" + +#~ msgid "" +#~ "``pip`` and other modern Python package installers ignore pre-releases by " +#~ "default when deciding which versions of dependencies to install." +#~ msgstr "" +#~ "``pip`` e outros instaladores de pacotes Python modernos ignoram os pré-" +#~ "lançamentos por padrão ao decidir quais versões de dependências instalar." + +#~ msgid "" +#~ "A local version identifier takes the form ``+``. For example::" +#~ msgstr "" +#~ "Um identificador de versão local assume a forma ``+``. Por exemplo::" + +#~ msgid "Three options are available in this area:" +#~ msgstr "Três opções estão disponíveis nesta área:" + +#~ msgid "pip provides local caching options," +#~ msgstr "pip fornece opções de cache local," + +#~ msgid "" +#~ "devpi provides higher-level caching option, potentially shared amongst " +#~ "many users or machines, and" +#~ msgstr "" +#~ "devpi fornece uma opção de cache de alto nível, potencialmente " +#~ "compartilhada entre vários usuários ou várias máquinas, e" + +#~ msgid "" +#~ "bandersnatch provides a local complete mirror of all PyPI :term:`packages " +#~ "`." +#~ msgstr "" +#~ "bandersnatch fornece um espelho local completo de todos os :term:`pacotes " +#~ "` do PyPI." + +#~ msgid "Caching with devpi" +#~ msgstr "Fazendo cache com devpi" + +#~ msgid "" +#~ "devpi is a caching proxy server which you run on your laptop, or some " +#~ "other machine you know will always be available to you. See the `devpi " +#~ "documentation for getting started`__." +#~ msgstr "" +#~ "devpi é um servidor proxy de cache que você executa em seu laptop ou " +#~ "alguma outra máquina que você sabe que sempre estará disponível para " +#~ "você. Veja a `documentação do devpi para começar`__." + +#~ msgid "Complete mirror with bandersnatch" +#~ msgstr "Espelho completo com bandersnatch" + +#~ msgid "" +#~ "bandersnatch will set up a complete local mirror of all " +#~ "PyPI :term:`packages ` (externally-hosted packages " +#~ "are not mirrored). See the `bandersnatch documentation for getting that " +#~ "going`__." +#~ msgstr "" +#~ "bandersnatch irá configurar um espelho local completo de todos " +#~ "os :term:`pacotes ` do PyPI (pacotes hospedados " +#~ "externamente não são espelhados). Veja a `documentação do bandersnatch " +#~ "para fazer isso`__." + +#~ msgid "" +#~ "A benefit of devpi is that it will create a mirror which " +#~ "includes :term:`packages ` that are external to " +#~ "PyPI, unlike bandersnatch which will only cache :term:`packages " +#~ "` hosted on PyPI." +#~ msgstr "" +#~ "Um benefício do devpi é que ele criará um espelho que " +#~ "inclui :term:`pacotes ` que são externos ao PyPI, " +#~ "ao contrário do bandersnatch que armazenará apenas em cache " +#~ "os :term:`pacotes ` hospedados no PyPI." + +#, fuzzy +#~ msgid "" +#~ "By default, any hash algorithm available via `hashlib `_ (specifically any that can be " +#~ "passed to ``hashlib.new()`` and do not require additional parameters) can " +#~ "be used as a key for the hashes dictionary. At least one secure algorithm " +#~ "from ``hashlib.algorithms_guaranteed`` **SHOULD** always be included. At " +#~ "the time of this spec, ``sha256`` specifically is recommended." +#~ msgstr "" +#~ "Qualquer algoritmo de hash disponível via ``hashlib`` (especificamente " +#~ "qualquer um que possa ser passado para ``hashlib.new()`` e não requeira " +#~ "parâmetros adicionais) pode ser usado como uma chave para o dicionário de " +#~ "hashes. Pelo menos um algoritmo seguro de " +#~ "``hashlib.algorithms_guaranteed`` DEVE sempre ser incluído. No momento da " +#~ "escrita, ``sha256`` especificamente é recomendado." + +#, fuzzy +#~ msgid "pyproject type" +#~ msgstr "pyproject.toml" + +#~ msgid "" +#~ "pex is both a library and tool for generating :file:`.pex` (Python " +#~ "EXecutable) files, standalone Python environments in the spirit " +#~ "of :ref:`virtualenv`. :file:`.pex` files are just carefully constructed " +#~ "zip files with a ``#!/usr/bin/env python`` and " +#~ "special :file:`__main__.py`, and are designed to make deployment of " +#~ "Python applications as simple as ``cp``." +#~ msgstr "" +#~ "pex é uma biblioteca e ferramenta para gerar arquivos :file:`.pex` " +#~ "(Python EXecutable), ambientes autônomos Python no espírito " +#~ "de :ref:`virtualenv`. Os arquivos :file:`.pex` são apenas arquivos zip " +#~ "cuidadosamente construídos com um ``#!/usr/bin/env python`` e " +#~ "um :file:`__main__.py` especial, e são projetados para fazer a " +#~ "implantação de aplicações Python tão simples quanto ``cp``." + +#, fuzzy +#~ msgid "" +#~ "The HTML format is defined in :pep:`503`, with the addition of \"yank\" " +#~ "support (allowing a kind of file deletion) in :pep:`592`, specifying the " +#~ "interface version provided by an index server in :pep:`629`, and " +#~ "providing package metadata independently from a package in :pep:`658` and " +#~ "revised in :pep:`714`." +#~ msgstr "" +#~ "A interface atual para consultar versões de pacotes disponíveis e " +#~ "recuperar pacotes de um servidor de indexação é definida na :pep:`503`, " +#~ "com a adição de suporte a retirada ou \"yank\" (que permite um tipo de " +#~ "exclusão de arquivo) na :pep:`592`, especificando a versão da interface " +#~ "fornecida por um servidor de indexação na :pep:`629` e fornecendo " +#~ "metadados de pacotes independentemente de um pacote na :pep:`658`." + +#~ msgid "" +#~ "If you're developing for a \"Platform-as-a-Service\" or \"PaaS\" like " +#~ "Heroku or Google App Engine, you are going to want to follow their " +#~ "respective packaging guides." +#~ msgstr "" +#~ "Se estiver desenvolvendo para uma \"plataforma como serviço\" ou " +#~ "\"PaaS\", como Heroku ou Google App Engine, você vai querer seguir seus " +#~ "respectivos guias de empacotamento." + +#~ msgid "" +#~ "`Heroku `_" +#~ msgstr "" +#~ "`Heroku `_" + +#~ msgid "" +#~ "`Google App Engine `_" +#~ msgstr "" +#~ "`Google App Engine `_" + +#~ msgid "`PythonAnywhere `_" +#~ msgstr "`PythonAnywhere `_" + +#~ msgid "`OpenShift `_" +#~ msgstr "`OpenShift `_" + +#~ msgid "\"Serverless\" frameworks like :gh:`Zappa `" +#~ msgstr "Frameworks \"serverless\" como :gh:`Zappa `" + +#~ msgid "" +#~ "There were multiple iterations of the ``manylinux`` specification, each " +#~ "representing the common subset of Linux platforms at a given point in " +#~ "time:" +#~ msgstr "" +#~ "Houve várias iterações da especificação ``manylinux``, cada uma " +#~ "representando o subconjunto comum de plataformas Linux em um determinado " +#~ "ponto no tempo:" + +#~ msgid "" +#~ "``manylinux2010`` (:pep:`571`) supports ``x86_64`` and ``i686`` " +#~ "architectures. and updates the previous specification to be based on a " +#~ "compatible Linux platform from 2010 instead." +#~ msgstr "" +#~ "``manylinux2010`` (:pep:`571`) oferece suporte às arquiteturas ``x86_64`` " +#~ "e ``i686`` e atualiza a especificação anterior para se basear em uma " +#~ "plataforma Linux compatível a partir de 2010." + +#~ msgid "" +#~ "``manylinux2014`` (:pep:`599`) adds support for a number of additional " +#~ "architectures (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, and " +#~ "``s390x``) and updates the base platform to a compatible Linux platform " +#~ "from 2014." +#~ msgstr "" +#~ "``manylinux2014`` (:pep:`599`) adiciona suporte para várias arquiteturas " +#~ "adicionais (``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le`` e ``s390x``) " +#~ "e atualiza a plataforma base para uma plataforma Linux compatível de 2014." + +#~ msgid "" +#~ "``manylinux_x_y`` (:pep:`600`) supersedes all previous PEPs to define a " +#~ "future-proof standard. It defines ``x`` and ``y`` as glibc major an minor " +#~ "versions supported (e.g. ``manylinux_2_24`` should work on any distro " +#~ "using glibc 2.24+). Previous tags are still supported for backward " +#~ "compatibility." +#~ msgstr "" +#~ "``manylinux_x_y`` (:pep:`600`) substitui todas as PEPs anteriores para " +#~ "definir um padrão à prova de futuro. Ele define ``x`` e ``y`` como as " +#~ "versões principais e secundárias do glibc suportadas (por exemplo, " +#~ "``manylinux_2_24`` deve funcionar em qualquer distro usando glibc 2.24+). " +#~ "Tags anteriores ainda são suportadas para compatibilidade com versões " +#~ "anteriores." + +#~ msgid "Manylinux compatibility support" +#~ msgstr "Suporte a compatibilidade de manylinux" + +#~ msgid "" +#~ "The ``manylinux2014`` specification is relatively new and is not yet " +#~ "widely recognised by install tools." +#~ msgstr "" +#~ "A especificação de ``manylinux2014`` é relativamente nova e ainda não é " +#~ "amplamente reconhecida pelas ferramentas de instalação." + +#~ msgid "" +#~ "The ``manylinux_x_y`` specification is relatively new and is not yet " +#~ "widely recognised by install tools." +#~ msgstr "" +#~ "A especificação de ``manylinux_x_y`` é relativamente nova e não é " +#~ "amplamente reconhecida pelas ferramentas de instalação." + +#, fuzzy +#~ msgid "The following changes were applied since the initial version:" +#~ msgstr "" +#~ "As seguintes alterações foram feitas com base no feedback após sua " +#~ "implementação inicial:" + +#~ msgid "" +#~ "The rules on escaping in wheel filenames were revised, to bring them into " +#~ "line with what popular tools actually do (February 2021)." +#~ msgstr "" +#~ "As regras sobre como escapar em nomes de arquivos wheel foram revisadas, " +#~ "para alinhá-las com o que as ferramentas populares realmente fazem " +#~ "(fevereiro de 2021)." + +#~ msgid "" +#~ "The name of the distribution. The name field is the primary identifier " +#~ "for a distribution. A valid name consists only of ASCII letters and " +#~ "numbers, period, underscore and hyphen. It must start and end with a " +#~ "letter or number. Distribution names are limited to those which match the " +#~ "following regex (run with ``re.IGNORECASE``)::" +#~ msgstr "" +#~ "O nome da distribuição. O campo de nome é o identificador principal de " +#~ "uma distribuição. Um nome válido consiste apenas em letras e números " +#~ "ASCII, ponto, sublinhado e hífen. Deve começar e terminar com uma letra " +#~ "ou número. Os nomes de distribuição são limitados àqueles que " +#~ "correspondem ao seguinte regex (executado com ``re.IGNORECASE``)::" + +#~ msgid "Summary of changes to PEP 508" +#~ msgstr "Resumo das alterações à PEP 508" + +#~ msgid "" +#~ "The following changes were made based on feedback after its initial " +#~ "implementation:" +#~ msgstr "" +#~ "As seguintes alterações foram feitas com base no feedback após sua " +#~ "implementação inicial:" + +#~ msgid "" +#~ "The definition of ``python_version`` was changed from " +#~ "``platform.python_version()[:3]`` to " +#~ "``'.'.join(platform.python_version_tuple()[:2])``, to accommodate " +#~ "potential future versions of Python with 2-digit major and minor versions " +#~ "(e.g. 3.10). [#future_versions]_" +#~ msgstr "" +#~ "A definição de ``python_version`` foi alterada de " +#~ "``platform.python_version()[:3]`` para " +#~ "``'.'.join(platform.python_version_tuple()[:2])``, para acomodar " +#~ "potenciais futuras versões do Python com versões principais e secundárias " +#~ "de 2 dígitos (por exemplo, 3.10). [#future_versions]_" + +#~ msgid "" +#~ "March 2020: the ``direct_url.json`` metadata file was originally " +#~ "specified in :pep:`610` and is formally documented here." +#~ msgstr "" +#~ "Março de 2020: o arquivo de metadados ``direct_url.json`` foi " +#~ "originalmente especificado na :pep:`610` e está formalmente documentado " +#~ "aqui." + +#~ msgid "" +#~ "March 2020: this data structure was originally specified as part of the " +#~ "``direct_url.json`` metadata file in :pep:`610` and is formally " +#~ "documented here." +#~ msgstr "" +#~ "Março de 2020: esta estrutura de dados foi originalmente especificada " +#~ "como parte do arquivo de metadados ``direct_url.json`` em :pep:`610` e " +#~ "está formalmente documentada aqui." + +#~ msgid "" +#~ "January 2023: Added the ``archive_info.hashes`` key ([discussion](https://" +#~ "discuss.python.org/t/22299))." +#~ msgstr "" +#~ "Janeiro de 2023: Adicionada a chave ``archive_info.hashes`` (`discussão " +#~ "`__)." + +#~ msgid "" +#~ "Project names are \"normalized\" for use in various contexts. This " +#~ "document describes how project names should be normalized." +#~ msgstr "" +#~ "Os nomes dos projetos são \"normalizados\" para uso em vários contextos. " +#~ "Este documento descreve como os nomes dos projetos devem ser normalizados." + +#~ msgid "The following PEPs contributed to this spec:" +#~ msgstr "Os seguintes PEPs contribuíram para esta especificação:" + +#~ msgid ":pep:`425`" +#~ msgstr ":pep:`425`" + +#~ msgid ":pep:`513`" +#~ msgstr ":pep:`513`" + +#~ msgid ":pep:`599`" +#~ msgstr ":pep:`599`" + +#~ msgid "History and change workflow" +#~ msgstr "Histórico e fluxo de trabalho de mudança" + +#, fuzzy +#~ msgid "" +#~ "The metadata described here was first specified in :pep:`376`, and later " +#~ "amended in :pep:`627` (and other PEPs). It was formerly known as " +#~ "*Database of Installed Python Distributions*. As with other PyPA " +#~ "specifications, editorial amendments with no functional impact may be " +#~ "made through the GitHub pull request workflow. Proposals for functional " +#~ "changes that would require amendments to package building and/or " +#~ "installation tools must be made through the PEP process (see :pep:`1`)." +#~ msgstr "" +#~ "Os metadados descritos aqui foram especificados primeiro na :pep:`376`, e " +#~ "posteriormente alterados na :pep:`627`. Era conhecido anteriormente como " +#~ "*Banco de dados de distribuições Python instaladas*. Outras alterações " +#~ "(exceto correções triviais de linguagem ou tipografia) devem ser feitas " +#~ "através do processo de PEP (veja :pep:`1`)." + +#, fuzzy +#~ msgid "" +#~ "While this document is the normative specification, the PEPs that " +#~ "introduce changes to it may include additional information such as " +#~ "rationales and backwards compatibility considerations." +#~ msgstr "" +#~ "Embora este documento seja a especificação normativa, essas PEPs que " +#~ "introduzem alterações nele podem incluir informações adicionais, como " +#~ "justificativas e considerações de compatibilidade com versões anteriores." + +#~ msgid "" +#~ "This is the name of your project, determining how your project is listed " +#~ "on :term:`PyPI `. Per :pep:`508`, valid " +#~ "project names must:" +#~ msgstr "" +#~ "Este é o nome do seu projeto, determinando como ele está listado " +#~ "no :term:`PyPI `. Conforme :pep:`508`, nomes " +#~ "de projetos válidos devem:" + +#~ msgid "Start & end with an ASCII letter or digit." +#~ msgstr "Começar e terminar com uma letra ou dígito ASCII." + +#~ msgid "" +#~ "This is the current version of your project, allowing your users to " +#~ "determine whether or not they have the latest version, and to indicate " +#~ "which specific versions they've tested their own software against." +#~ msgstr "" +#~ "Esta é a versão atual do seu projeto, permitindo que seus usuários " +#~ "determinem se têm ou não a versão mais recente e indiquem em quais " +#~ "versões específicas eles testaram seu próprio software." + +#~ msgid "" +#~ "Versions are displayed on :term:`PyPI ` for " +#~ "each release if you publish your project." +#~ msgstr "" +#~ "As versões são exibidas em :term:`PyPI ` " +#~ "para cada lançamento se você publicar seu projeto." + +#~ msgid "" +#~ "If the project code itself needs run-time access to the version, the " +#~ "simplest way is to keep the version in both :file:`setup.py` and your " +#~ "code. If you'd rather not duplicate the value, there are a few ways to " +#~ "manage this. See the \":ref:`Single sourcing the version`\" Advanced " +#~ "Topics section." +#~ msgstr "" +#~ "Se o código do projeto em si precisa de acesso em tempo de execução para " +#~ "a versão, a maneira mais simples é manter a versão em :file:`setup.py` e " +#~ "seu código. Se você preferir não duplicar o valor, existem algumas " +#~ "maneiras de gerenciar isso. Consulte a seção de tópicos avançados " +#~ "\":ref:`Fonte única da versão `\"." + +#~ msgid "Give a short and long description for your project." +#~ msgstr "Da uma descrição curta e longa para seu projeto." + +#~ msgid "" +#~ "These values will be displayed on :term:`PyPI ` if you publish your project. On ``pypi.org``, the user interface " +#~ "displays ``description`` in the grey banner and ``long_description`` in " +#~ "the section named \"Project Description\"." +#~ msgstr "" +#~ "Esses valores serão exibidos no :term:`PyPI ` se você publicar seu projeto. No ``pypi.org``, a interface do " +#~ "usuário exibe ``description`` no banner cinza e ``long_description`` na " +#~ "seção chamada \"Descrição do Projeto\"." + +#~ msgid "" +#~ "``description`` is also displayed in lists of projects. For example, it's " +#~ "visible in the search results pages such as https://pypi.org/search/?" +#~ "q=jupyter, the front-page lists of trending projects and new releases, " +#~ "and the list of projects you maintain within your account profile (such " +#~ "as https://pypi.org/user/jaraco/)." +#~ msgstr "" +#~ "``description`` também é exibido em listas de projetos. Por exemplo, ele " +#~ "é visível nas páginas de resultados de pesquisa, como https://pypi.org/" +#~ "search/?q=jupyter, nas listas da página inicial de projetos populares e " +#~ "novos lançamentos e na lista de projetos que você mantém no perfil de sua " +#~ "conta (como https://pypi.org/user/jaraco/)." + +#~ msgid "" +#~ "A :ref:`content type ` can be " +#~ "specified with the ``long_description_content_type`` argument, which can " +#~ "be one of ``text/plain``, ``text/x-rst``, or ``text/markdown``, " +#~ "corresponding to no formatting, `reStructuredText (reST) `_, and the GitHub-flavored Markdown dialect of `Markdown `_ respectively." +#~ msgstr "" +#~ "Um :ref:`tipo de conteúdo ` pode " +#~ "ser especificado com o argumento ``long_description_content_type``, que " +#~ "pode ser um de ``text/plain``, ``text/x-rst`` ou ``text/markdown``, " +#~ "correspondendo a nenhuma formatação, `reStructuredText (reST) `_, e o dialeto Markdown com sabor do GitHub de `Markdown `_ respectivamente." + +#~ msgid "``url``" +#~ msgstr "``url``" + +#~ msgid "Give a homepage URL for your project." +#~ msgstr "Fornece o URL da página inicial do seu projeto." + +#, fuzzy +#~ msgid "``author``" +#~ msgstr "author" + +#~ msgid "Provide details about the author." +#~ msgstr "Fornece detalhes sobre o autor." + +#~ msgid "" +#~ "The ``license`` argument doesn't have to indicate the license under which " +#~ "your package is being released, although you may optionally do so if you " +#~ "want. If you're using a standard, well-known license, then your main " +#~ "indication can and should be via the ``classifiers`` argument. " +#~ "Classifiers exist for all major open-source licenses." +#~ msgstr "" +#~ "O argumento ``license`` não precisa indicar a licença sob a qual seu " +#~ "pacote está sendo lançado, embora você possa opcionalmente fazer isso se " +#~ "desejar. Se você estiver usando uma licença padrão bem conhecida, sua " +#~ "indicação principal pode e deve ser por meio do argumento " +#~ "``classifiers``. Existem classificadores para todas as principais " +#~ "licenças de código aberto." + +#~ msgid "" +#~ "Provide a list of classifiers that categorize your project. For a full " +#~ "listing, see https://pypi.org/classifiers/." +#~ msgstr "" +#~ "Fornece uma lista de classificadores que categorizam seu projeto. Para " +#~ "obter uma lista completa, consulte https://pypi.org/classifiers/." + +#~ msgid "List keywords that describe your project." +#~ msgstr "Lista as palavras-chave que descrevem seu projeto." + +#, fuzzy +#~ msgid "``project_urls``" +#~ msgstr "project_urls" + +#~ msgid "" +#~ "List additional relevant URLs about your project. This is the place to " +#~ "link to bug trackers, source repositories, or where to support package " +#~ "development. The string of the key is the exact text that will be " +#~ "displayed on PyPI." +#~ msgstr "" +#~ "Lista URLs relevantes adicionais sobre seu projeto. Este é o lugar para " +#~ "se conectar a rastreadores de bugs, repositórios fontes ou onde oferecer " +#~ "suporte ao desenvolvimento de pacotes. A string da chave é o texto exato " +#~ "que será exibido no PyPI." + +#, fuzzy +#~ msgid "``python_requires``" +#~ msgstr "python_requires" + +#~ msgid "" +#~ "If your project only runs on certain Python versions, setting the " +#~ "``python_requires`` argument to the appropriate :pep:`440` version " +#~ "specifier string will prevent :ref:`pip` from installing the project on " +#~ "other Python versions. For example, if your package is for Python 3+ " +#~ "only, write::" +#~ msgstr "" +#~ "Se o seu projeto só funciona em certas versões do Python, definir o " +#~ "argumento ``python_requires`` para a string apropriada especificadora de " +#~ "versão da :pep:`440` impedirá :ref:`pip` de instalar o projeto em outras " +#~ "versões do Python. Por exemplo, se seu pacote for apenas para Python 3+, " +#~ "escreva::" + +#~ msgid "" +#~ "If your package is for Python 2.6, 2.7, and all versions of Python 3 " +#~ "starting with 3.3, write::" +#~ msgstr "" +#~ "Se o seu pacote for para Python 2.6, 2.7 e todas as versões do Python 3 " +#~ "começando com 3.3, escreva::" + +#~ msgid "And so on." +#~ msgstr "E por aí vai." + +#~ msgid "" +#~ "Support for this feature is relatively recent. Your project's source " +#~ "distributions and wheels (see :ref:`Packaging Your Project`) must be " +#~ "built using at least version 24.2.0 of :ref:`setuptools` in order for the " +#~ "``python_requires`` argument to be recognized and the appropriate " +#~ "metadata generated." +#~ msgstr "" +#~ "O suporte para esse recurso é relativamente recente. As distribuições de " +#~ "código-fonte e wheels do seu projeto (veja :ref:`Empacotando seu projeto " +#~ "`) devem ser construídas usando pelo menos a " +#~ "versão 24.2.0 do :ref:`setuptools` para que o argumento " +#~ "``python_requires`` seja reconhecido e os metadados apropriados gerados." + +#~ msgid "" +#~ "In addition, only versions 9.0.0 and higher of :ref:`pip` recognize the " +#~ "``python_requires`` metadata. Users with earlier versions of pip will be " +#~ "able to download & install projects on any Python version regardless of " +#~ "the projects' ``python_requires`` values." +#~ msgstr "" +#~ "Além disso, apenas as versões 9.0.0 e superiores do :ref:`pip` reconhecem " +#~ "os metadados de ``python_requires``. Usuários com versões anteriores do " +#~ "pip serão capazes de baixar e instalar projetos em qualquer versão do " +#~ "Python, independentemente dos valores de ``python_requires`` dos projetos." + +#~ msgid "``entry_points``" +#~ msgstr "``entry_points``" + +#~ msgid "" +#~ "Use this keyword to specify any plugins that your project provides for " +#~ "any named entry points that may be defined by your project or others that " +#~ "you depend on." +#~ msgstr "" +#~ "Use esta palavra-chave para especificar quaisquer plugins que seu projeto " +#~ "fornece para quaisquer pontos de entrada nomeados que podem ser definidos " +#~ "por seu projeto ou outros dos quais você depende." + +#~ msgid "" +#~ "For more information, see the section on :ref:`Advertising Behavior " +#~ "` from " +#~ "the :ref:`setuptools` docs." +#~ msgstr "" +#~ "Para obter mais informações, consulte a seção sobre :ref:`Comportamento " +#~ "de Publicidade ` da " +#~ "documentação do :ref:`setuptools`." + +#~ msgid "" +#~ "The most commonly used entry point is \"console_scripts\" (see below)." +#~ msgstr "" +#~ "O ponto de entrada mais comumente usado é \"console_scripts\" (veja " +#~ "abaixo)." + +#, fuzzy +#~ msgid "``console_scripts``" +#~ msgstr "console_scripts" + +#~ msgid "" +#~ "Use ``console_script`` :ref:`entry points ` to register your script interfaces. You can " +#~ "then let the toolchain handle the work of turning these interfaces into " +#~ "actual scripts [2]_. The scripts will be generated during the install of " +#~ "your :term:`distribution `." +#~ msgstr "" +#~ "Use :ref:`pontos de entrada ` de ``console_script`` para registrar suas interfaces de script. " +#~ "Você pode então deixar o conjunto de ferramentas lidar com o trabalho de " +#~ "transformar essas interfaces em scripts reais [2]_. Os scripts serão " +#~ "gerados durante a instalação do seu :term:`distribuição `." + +#~ msgid "" +#~ "For more information, see :doc:`Entry Points ` from the :doc:`setuptools docs `." +#~ msgstr "" +#~ "Para mais informações, veja :doc:`Entry Points ` (pontos de entrada, em português) da :doc:`documentação do " +#~ "setuptools `." + +#~ msgid "" +#~ "Specifically, the \"console_script\" approach generates ``.exe`` files on " +#~ "Windows, which are necessary because the OS special-cases ``.exe`` files. " +#~ "Script-execution features like ``PATHEXT`` and the :pep:`Python Launcher " +#~ "for Windows <397>` allow scripts to be used in many cases, but not all." +#~ msgstr "" +#~ "Especificamente, a abordagem \"console_script\" gera arquivos ``.exe`` no " +#~ "Windows, que são necessários por causa dos arquivos ``.exe`` de casos " +#~ "especiais do sistema operacional. Recursos de execução de script como " +#~ "``PATHEXT`` e o :pep:`Inicializador do Python para Windows <397>` " +#~ "permitem que scripts sejam usados em muitos casos, mas não em todos." + +#~ msgid "" +#~ "The binary distribution format (:term:`wheel `) was originally " +#~ "defined in :pep:`427`. The current version of the specification is here." +#~ msgstr "" +#~ "O formato de distribuição binária (:term:`wheel `) foi " +#~ "originalmente definido na :pep:`427`. A versão atual da especificação " +#~ "está aqui." + +#~ msgid "Abstract" +#~ msgstr "Abstrato" + +#~ msgid "" +#~ "This PEP describes a built-package format for Python called \"wheel\"." +#~ msgstr "" +#~ "Esta PEP descreve um formato de pacote construído para Python chamado " +#~ "\"wheel\"." + +#~ msgid "PEP Acceptance" +#~ msgstr "Aceitação da PEP" + +#~ msgid "" +#~ "This PEP was accepted, and the defined wheel version updated to 1.0, by " +#~ "Nick Coghlan on 16th February, 2013 [1]_" +#~ msgstr "" +#~ "Esta PEP foi aceita, e a versão do wheel definida foi atualizada para " +#~ "1.0, por Nick Coghlan em 16 de fevereiro de 2013 [1]_" + +#~ msgid "Rationale" +#~ msgstr "Justificativa" + +#~ msgid "" +#~ "Python needs a package format that is easier to install than sdist. " +#~ "Python's sdist packages are defined by and require the distutils and " +#~ "setuptools build systems, running arbitrary code to build-and-install, " +#~ "and re-compile, code just so it can be installed into a new virtualenv. " +#~ "This system of conflating build-install is slow, hard to maintain, and " +#~ "hinders innovation in both build systems and installers." +#~ msgstr "" +#~ "Python precisa de um formato de pacote mais fácil de instalar do que " +#~ "sdist. Os pacotes sdist do Python são definidos e requerem os sistemas de " +#~ "construção distutils e setuptools, executando código arbitrário para " +#~ "construir e instalar e recompilar o código apenas para que possa ser " +#~ "instalado em um novo virtualenv. Este sistema de combinação entre " +#~ "construção e instalação é lento, difícil de manter e impede a inovação " +#~ "tanto nos sistemas de construção quanto nos instaladores." + +#~ msgid "" +#~ "Wheel attempts to remedy these problems by providing a simpler interface " +#~ "between the build system and the installer. The wheel binary package " +#~ "format frees installers from having to know about the build system, saves " +#~ "time by amortizing compile time over many installations, and removes the " +#~ "need to install a build system in the target environment." +#~ msgstr "" +#~ "O wheel tenta remediar esses problemas fornecendo uma interface mais " +#~ "simples entre o sistema de compilação e o instalador. O formato do pacote " +#~ "binário wheel libera os instaladores de ter que saber sobre o sistema de " +#~ "compilação, economiza tempo amortizando o tempo de compilação em muitas " +#~ "instalações e elimina a necessidade de instalar um sistema de compilação " +#~ "no ambiente de destino." + +#~ msgid "Comparison to .egg" +#~ msgstr "Comparação com .egg" + +#~ msgid "" +#~ "Wheel is an installation format; egg is importable. Wheel archives do " +#~ "not need to include .pyc and are less tied to a specific Python version " +#~ "or implementation. Wheel can install (pure Python) packages built with " +#~ "previous versions of Python so you don't always have to wait for the " +#~ "packager to catch up." +#~ msgstr "" +#~ "Wheel é um formato de instalação; ovo é importável. Os arquivos wheel não " +#~ "precisam incluir .pyc e estão menos vinculados a uma versão ou " +#~ "implementação específica do Python. O Wheel pode instalar pacotes (puro " +#~ "Python) construídos com versões anteriores do Python, portanto, você nem " +#~ "sempre precisa esperar que o empacotador os atualize." + +#~ msgid "" +#~ "Wheel uses .dist-info directories; egg uses .egg-info. Wheel is " +#~ "compatible with the new world of Python packaging and the new concepts it " +#~ "brings." +#~ msgstr "" +#~ "O Wheel usa diretórios .dist-info; egg usa .egg-info. Wheel é compatível " +#~ "com o novo mundo da empacotamento de Python e os novos conceitos que ele " +#~ "traz." + +#~ msgid "" +#~ "Wheel has a richer file naming convention for today's multi-" +#~ "implementation world. A single wheel archive can indicate its " +#~ "compatibility with a number of Python language versions and " +#~ "implementations, ABIs, and system architectures. Historically the ABI " +#~ "has been specific to a CPython release, wheel is ready for the stable ABI." +#~ msgstr "" +#~ "O Wheel tem uma convenção de nomenclatura de arquivo mais rica para o " +#~ "mundo de múltiplas implementações de hoje. Um único arquivo de wheel pode " +#~ "indicar sua compatibilidade com várias versões e implementações de " +#~ "linguagem Python, ABIs e arquiteturas de sistema. Historicamente, a ABI " +#~ "tem sido específica para uma versão do CPython, o wheel estando pronto " +#~ "para a ABI estável." + +#~ msgid "" +#~ "Wheel is lossless. The first wheel implementation bdist_wheel always " +#~ "generates egg-info, and then converts it to a .whl. It is also possible " +#~ "to convert existing eggs and bdist_wininst distributions." +#~ msgstr "" +#~ "O wheel não causa perdas. A implementação do primeiro wheel, bdist_wheel, " +#~ "sempre gera egg-info e, então, as converte em .whl. Também é possível " +#~ "converter eggs existentes e distribuições de bdist_wininst." + +#~ msgid "" +#~ "Wheel is versioned. Every wheel file contains the version of the wheel " +#~ "specification and the implementation that packaged it. Hopefully the next " +#~ "migration can simply be to Wheel 2.0." +#~ msgstr "" +#~ "Wheel é versionado. Cada arquivo wheel contém a versão da especificação " +#~ "wheel e a implementação que a empacotou. Esperançosamente, a próxima " +#~ "migração pode ser simplesmente para Wheel 2.0." + +#~ msgid "Wheel is a reference to the other Python." +#~ msgstr "Wheel é uma referência a outro Python." + +#~ msgid "Since :pep:`427`, this specification has changed as follows:" +#~ msgstr "Desde a :pep:`427`, esta especificação mudou da seguinte forma:" + +#~ msgid "" +#~ "PEP acceptance (https://mail.python.org/pipermail/python-dev/2013-" +#~ "February/124103.html)" +#~ msgstr "" +#~ "Aceitação da PEP (https://mail.python.org/pipermail/python-dev/2013-" +#~ "February/124103.html)" + +#~ msgid "This document has been placed into the public domain." +#~ msgstr "Este documento foi colocado em domínio público." + +#~ msgid "``python -m twine check``" +#~ msgstr "``python -m twine check``" + +#~ msgid "``python -m twine register``" +#~ msgstr "``python -m twine register``" + +#~ msgid "``python -m twine upload``" +#~ msgstr "``python -m twine upload``" + +#~ msgid "``python -m setuptools-scm``" +#~ msgstr "``python -m setuptools-scm``" + +#~ msgid "" +#~ "a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth); " +#~ "see :doc:`Declaring project metadata ` for more detail" +#~ msgstr "" +#~ "uma tabela ``[project]`` contendo os :doc:`Metadados Principais ` (nome, versão, autor e assim por diante) " +#~ "do projeto; veja :doc:`Declarando os metadados do projeto ` para mais detalhes" + +#~ msgid "a ``[tool]`` table containing tool-specific configuration options" +#~ msgstr "" +#~ "uma tabela ``[tool]`` contendo opções de configuração específicas da " +#~ "ferramenta" + +#~ msgid "" +#~ "A `content type `_ can be specified with the " +#~ "``long_description_content_type`` argument, which can be one of ``text/" +#~ "plain``, ``text/x-rst``, or ``text/markdown``, corresponding to no " +#~ "formatting, `reStructuredText (reST) `_, and the GitHub-" +#~ "flavored Markdown dialect of `Markdown `_ respectively." +#~ msgstr "" +#~ "Um `tipo de conteúdo `_ pode ser especificado com " +#~ "o argumento ``long_description_content_type``, que pode ser um de ``text/" +#~ "plain``, ``text/x-rst`` ou ``text/markdown``, correspondendo a nenhuma " +#~ "formatação, `reStructuredText (reST) `_, e o dialeto " +#~ "Markdown com sabor do GitHub de `Markdown `_ respectivamente." + +#~ msgid "You can learn more about pipx at https://pypa.github.io/pipx/." +#~ msgstr "Você pode aprender mais sobre pipx em https://pypa.github.io/pipx/." + +#~ msgid ":ref:`declaring-build-dependencies`" +#~ msgstr ":ref:`declaring-build-dependencies`" + +#~ msgid "" +#~ "Read :ref:`declaring-project-metadata` for the full specification of the " +#~ "content allowed in the ``[project]`` table." +#~ msgstr "" +#~ "Leia :ref:`declaring-project-metadata` para a especificação completa do " +#~ "conteúdo permitido na tabela ``[project]``." + +#~ msgid ":ref:`declaring-project-metadata`" +#~ msgstr ":ref:`declaring-project-metadata`" + +#~ msgid "" +#~ "`Docs `__ | `GitHub `__ | `PyPI `__" +#~ msgstr "" +#~ "`Documentação `__ | `GitHub `__ | `PyPI `__" + +#~ msgid "" +#~ ":doc:`Docs ` | `Issues `__ | `GitHub `__" +#~ msgstr "" +#~ ":doc:`Documentação ` | `Issues `__ | `GitHub `__" + +#~ msgid "" +#~ "trove-classifiers is the canonical source for `classifiers on PyPI " +#~ "`_, which project maintainers use to " +#~ "`systematically describe their projects `_ so that users " +#~ "can better find projects that match their needs on the PyPI." +#~ msgstr "" +#~ "trove-classifiers é a fonte canônica para `classificadores no PyPI " +#~ "`_, que os mantenedores de projetos usam " +#~ "para `descrever sistematicamente seus projetos `_ para que os usuários possam encontrar melhor os projetos que " +#~ "correspondem às suas necessidades no PyPI." + +#, fuzzy +#~ msgid "" +#~ "The ``pyproject.toml`` file is written in `TOML `_. " +#~ "Among other metadata (such as :ref:`project metadata `), it declares any Python level dependencies that must be " +#~ "installed in order to run the project's build system successfully." +#~ msgstr "" +#~ "`pyproject.toml` é um formato de arquivo independente do sistema de " +#~ "construção definido na :pep:`518` que os projetos podem fornecer para " +#~ "declarar quaisquer dependências de nível Python que devem ser instaladas " +#~ "para executar o sistema de construção do projeto com sucesso." + +#~ msgid "" +#~ ":pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for packaging-related tools to " +#~ "consume. It defines the following specification as the canonical source " +#~ "for the format used." +#~ msgstr "" +#~ "A :pep:`621` especifica como escrever :ref:`metadados principais ` de um projeto em um arquivo ``pyproject.toml`` para " +#~ "ferramentas relacionadas ao empacotamento consumirem. Ele define a " +#~ "seguinte especificação como a fonte canônica para o formato usado." + +#, fuzzy +#~ msgid "" +#~ "The keys defined in this specification MUST be in a table named " +#~ "``[project]`` in ``pyproject.toml``. No tools may add keys to this table " +#~ "which are not defined by this specification. For tools wishing to store " +#~ "their own settings in ``pyproject.toml``, they may use the ``[tool]`` " +#~ "table as defined in the :ref:`build dependency declaration specification " +#~ "`. The lack of a ``[project]`` table " +#~ "implicitly means the :term:`build backend ` will " +#~ "dynamically provide all keys." +#~ msgstr "" +#~ "As chaves definidas nesta especificação DEVEM estar em uma tabela chamada " +#~ "``[project]`` no arquivo ``pyproject.toml``. Nenhuma ferramenta pode " +#~ "adicionar chaves a esta tabela que não sejam definidas por esta " +#~ "especificação. Para ferramentas que desejam armazenar suas próprias " +#~ "configurações em ``pyproject.toml``, elas podem usar a tabela ``[tool]`` " +#~ "conforme definido na :ref:`especificação da declaração de dependências de " +#~ "construção `. A falta de uma tabela " +#~ "``[project]`` implicitamente significa que o backend da construção " +#~ "fornecerá dinamicamente todas as chaves." + +#~ msgid "" +#~ "A ``.tar.gz`` source distribution (sdist) contains a single top-level " +#~ "directory called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the " +#~ "source files of the package. The name and version MUST match the metadata " +#~ "stored in the file. This directory must also contain " +#~ "a :file:`pyproject.toml` in the format defined in :ref:`declaring-build-" +#~ "dependencies`, and a ``PKG-INFO`` file containing metadata in the format " +#~ "described in the :ref:`core-metadata` specification. The metadata MUST " +#~ "conform to at least version 2.2 of the metadata specification." +#~ msgstr "" +#~ "Uma distribuição fonte ``.tar.gz`` (sdist) contém um único diretório de " +#~ "nível superior chamado ``{name}-{version}`` (por exemplo, ``foo-1.0``), " +#~ "contendo os arquivos fonte do pacote. O nome e a versão DEVEM " +#~ "corresponder aos metadados armazenados no arquivo. Este diretório também " +#~ "deve conter um :file:`pyproject.toml` no formato definido " +#~ "em :ref:`declaring-build-dependencies` e um arquivo ``PKG-INFO`` contendo " +#~ "metadados no formato descrito na especificação :ref:`core-metadata`. Os " +#~ "metadados DEVEM estar em conformidade com pelo menos a versão 2.2 da " +#~ "especificação de metadados." + +#~ msgid "" +#~ "Read :pep:`517` and :pep:`518` for background and details on build tool " +#~ "configuration." +#~ msgstr "" +#~ "Leia a :pep:`517` e a :pep:`518` para um informações e detalhes sobre a " +#~ "configuração de ferramenta de construção." + +#~ msgid "Read about :doc:`/guides/packaging-binary-extensions`." +#~ msgstr "Leia sobre :doc:`/guides/packaging-binary-extensions`." + +#, fuzzy +#~ msgid "Current recommendation" +#~ msgstr "Recomendações de ferramentas" + +#~ msgid "" +#~ "`distribute`_ was a fork of setuptools that was merged back into " +#~ "setuptools (in v0.7), thereby making setuptools the primary choice for " +#~ "Python packaging." +#~ msgstr "" +#~ "`distribute`_ era um fork do setuptools que foi mesclado no setuptools " +#~ "(na v0.7), tornando assim setuptools a escolha primária para o " +#~ "empacotamento Python." + +#~ msgid "" +#~ "When building a :term:`source distribution ` for your package, by default only a minimal set of files are " +#~ "included. You may find yourself wanting to include extra files in the " +#~ "source distribution, such as an authors/contributors file, a :file:`docs/" +#~ "` directory, or a directory of data files used for testing purposes. " +#~ "There may even be extra files that you *need* to include; for example, if " +#~ "your :file:`setup.py` computes your project's ``long_description`` by " +#~ "reading from both a README and a changelog file, you'll need to include " +#~ "both those files in the sdist so that people that build or install from " +#~ "the sdist get the correct results." +#~ msgstr "" +#~ "Ao construir uma :term:`distribuição fonte ` para o seu pacote, por padrão apenas um conjunto mínimo de " +#~ "arquivos é incluído. Você pode querer incluir arquivos extras na " +#~ "distribuição, como um arquivo de autores/contribuidores, um " +#~ "diretório :file:`docs/` ou um diretório de arquivos de dados usado para " +#~ "fins de teste. Pode até haver arquivos extras que você *precisa* incluir; " +#~ "por exemplo, se o seu :file:`setup.py` calcula a ``long_description`` do " +#~ "seu projeto lendo um arquivo README e um changelog, você precisará " +#~ "incluir ambos os arquivos no sdist para que as pessoas que construam ou " +#~ "instalar a partir do sdist obtém os resultados corretos." + +#~ msgid "" +#~ "Adding & removing files to & from the source distribution is done by " +#~ "writing a :file:`MANIFEST.in` file at the project root." +#~ msgstr "" +#~ "Adicionar e remover arquivos para e da distribuição fonte é feito " +#~ "escrevendo um arquivo :file:`MANIFEST.in` na raiz do projeto." + +#~ msgid "How files are included in an sdist" +#~ msgstr "Como os arquivos são incluídos em um sdist" + +#~ msgid "" +#~ "The following files are included in a source distribution by default:" +#~ msgstr "" +#~ "Os seguintes arquivos são incluídos em uma distribuição fonte por padrão:" + +#~ msgid "" +#~ "all Python source files implied by the ``py_modules`` and ``packages`` " +#~ "``setup()`` arguments" +#~ msgstr "" +#~ "todos os arquivos fonte Python implícitos pelos argumentos ``py_modules`` " +#~ "e ``packages`` do ``setup()``" + +#~ msgid "" +#~ "all C source files mentioned in the ``ext_modules`` or ``libraries`` " +#~ "``setup()`` arguments" +#~ msgstr "" +#~ "todos os arquivos fonte C mencionados nos argumentos ``ext_modules`` ou " +#~ "``libraries`` do ``setup()``" + +#~ msgid "scripts specified by the ``scripts`` ``setup()`` argument" +#~ msgstr "scripts especificados pelo argumento ``scripts`` do ``setup()``" + +#~ msgid "" +#~ "all files specified by the ``package_data`` and ``data_files`` " +#~ "``setup()`` arguments" +#~ msgstr "" +#~ "todos os arquivos especificados pelos argumentos ``package_data`` e " +#~ "``data_files`` do ``setup()``" + +#~ msgid "" +#~ "the file specified by the ``license_file`` option in :file:`setup.cfg` " +#~ "(setuptools 40.8.0+)" +#~ msgstr "" +#~ "o arquivo especificado pela opção ``license_file`` em :file:`setup.cfg` " +#~ "(setuptools 40.8.0+)" + +#~ msgid "" +#~ "all files specified by the ``license_files`` option in :file:`setup.cfg` " +#~ "(setuptools 42.0.0+)" +#~ msgstr "" +#~ "todos os arquivos especificados pela opção ``license_files`` " +#~ "em :file:`setup.cfg` (setuptools 42.0.0+)" + +#~ msgid "all files matching the pattern :file:`test/test*.py`" +#~ msgstr "todos os arquivos correspondendo ao padrão :file:`test/test*.py`" + +#~ msgid ":file:`setup.py` (or whatever you called your setup script)" +#~ msgstr "" +#~ ":file:`setup.py` (ou o que quer que você tenha chamado de seu script de " +#~ "configuração)" + +#~ msgid ":file:`setup.cfg`" +#~ msgstr ":file:`setup.cfg`" + +#~ msgid ":file:`README`" +#~ msgstr ":file:`README`" + +#~ msgid ":file:`README.txt`" +#~ msgstr ":file:`README.txt`" + +#~ msgid ":file:`README.rst` (Python 3.7+ or setuptools 0.6.27+)" +#~ msgstr ":file:`README.rst` (Python 3.7+ ou setuptools 0.6.27+)" + +#~ msgid ":file:`README.md` (setuptools 36.4.0+)" +#~ msgstr ":file:`README.md` (setuptools 36.4.0+)" + +#~ msgid ":file:`pyproject.toml` (setuptools 43.0.0+)" +#~ msgstr ":file:`pyproject.toml` (setuptools 43.0.0+)" + +#~ msgid ":file:`MANIFEST.in`" +#~ msgstr ":file:`MANIFEST.in`" + +#~ msgid "" +#~ "After adding the above files to the sdist, the commands " +#~ "in :file:`MANIFEST.in` (if such a file exists) are executed in order to " +#~ "add and remove further files to and from the sdist. Default files can " +#~ "even be removed from the sdist with the appropriate :file:`MANIFEST.in` " +#~ "command." +#~ msgstr "" +#~ "Depois de adicionar os arquivos acima ao sdist, os comandos " +#~ "em :file:`MANIFEST.in` (se tal arquivo existir) são executados para " +#~ "adicionar e remover outros arquivos para e do sdist. Os arquivos padrão " +#~ "podem até mesmo ser removidos do sdist com o comando apropriado " +#~ "de :file:`MANIFEST.in`." + +#~ msgid "" +#~ "After processing the :file:`MANIFEST.in` file, setuptools removes " +#~ "the :file:`build/` directory as well as any directories " +#~ "named :file:`RCS`, :file:`CVS`, or :file:`.svn` from the sdist, and it " +#~ "adds a :file:`PKG-INFO` file and an :file:`*.egg-info` directory. This " +#~ "behavior cannot be changed with :file:`MANIFEST.in`." +#~ msgstr "" +#~ "Após processar o arquivo :file:`MANIFEST.in`, setuptools remove o " +#~ "diretório :file:`build/` bem como quaisquer diretórios " +#~ "chamados :file:`RCS`, :file:`CVS` ou :file:`.svn` do sdist, e adiciona um " +#~ "arquivo :file:`PKG-INFO` e um diretório :file:`*.egg-info`. Este " +#~ "comportamento não pode ser alterado com :file:`MANIFEST.in`." + +#~ msgid ":file:`MANIFEST.in` commands" +#~ msgstr "Comandos do :file:`MANIFEST.in`" + +#~ msgid "" +#~ "A :file:`MANIFEST.in` file consists of commands, one per line, " +#~ "instructing setuptools to add or remove some set of files from the " +#~ "sdist. The commands are:" +#~ msgstr "" +#~ "Um arquivo :file:`MANIFEST.in` consiste em comandos, um por linha, " +#~ "instruindo o setuptools a adicionar ou remover algum conjunto de arquivos " +#~ "do sdist. Os comandos são:" + +#~ msgid "Command" +#~ msgstr "Comando" + +#~ msgid ":samp:`include {pat1} {pat2} ...`" +#~ msgstr ":samp:`include {padrão1} {padrão2} ...`" + +#~ msgid "" +#~ "Add all files matching any of the listed patterns (Files must be given as " +#~ "paths relative to the root of the project)" +#~ msgstr "" +#~ "Adicione todos os arquivos que correspondam a qualquer um dos padrões " +#~ "listados (os arquivos devem ser fornecidos como caminhos relativos à raiz " +#~ "do projeto)" + +#~ msgid ":samp:`exclude {pat1} {pat2} ...`" +#~ msgstr ":samp:`exclude {padrão1} {padrão2} ...`" + +#~ msgid "" +#~ "Remove all files matching any of the listed patterns (Files must be given " +#~ "as paths relative to the root of the project)" +#~ msgstr "" +#~ "Remove todos os arquivos correspondendo a qualquer um dos padrões " +#~ "listados (Arquivos devem ser fornecidos como caminhos relativos à raiz do " +#~ "projeto)" + +#~ msgid ":samp:`recursive-include {dir-pattern} {pat1} {pat2} ...`" +#~ msgstr ":samp:`recursive-include {padrão-dir} {padrão1} {padrão2} ...`" + +#~ msgid "" +#~ "Add all files under directories matching ``dir-pattern`` that match any " +#~ "of the listed patterns" +#~ msgstr "" +#~ "Adiciona todos os arquivos sob diretórios correspondendo a ``padrão-dir`` " +#~ "que correspondem a qualquer um dos padrões listados" + +#~ msgid ":samp:`recursive-exclude {dir-pattern} {pat1} {pat2} ...`" +#~ msgstr ":samp:`recursive-exclude {padrão-dir} {padrão1} {padrão2} ...`" + +#~ msgid "" +#~ "Remove all files under directories matching ``dir-pattern`` that match " +#~ "any of the listed patterns" +#~ msgstr "" +#~ "Remove todos os arquivos sob diretórios correspondendo a ``padrão-dir`` " +#~ "que correspondem a qualquer um dos padrões listados" + +#~ msgid ":samp:`global-include {pat1} {pat2} ...`" +#~ msgstr ":samp:`global-include {padrão1} {padrão2} ...`" + +#~ msgid "" +#~ "Add all files anywhere in the source tree matching any of the listed " +#~ "patterns" +#~ msgstr "" +#~ "Adiciona todos os arquivos em qualquer lugar na árvore de fontes que " +#~ "correspondam a qualquer um dos padrões listados" + +#~ msgid ":samp:`global-exclude {pat1} {pat2} ...`" +#~ msgstr ":samp:`global-exclude {padrão1} {padrão2} ...`" + +#~ msgid "" +#~ "Remove all files anywhere in the source tree matching any of the listed " +#~ "patterns" +#~ msgstr "" +#~ "Remove todos os arquivos de qualquer lugar na árvore de fontes que " +#~ "correspondam a qualquer um dos padrões listados" + +#~ msgid ":samp:`graft {dir-pattern}`" +#~ msgstr ":samp:`graft {padrão-dir}`" + +#~ msgid "Add all files under directories matching ``dir-pattern``" +#~ msgstr "" +#~ "Adiciona todos os arquivos sob diretórios correspondendo a ``padrão-dir``" + +#~ msgid ":samp:`prune {dir-pattern}`" +#~ msgstr ":samp:`prune {padrão-dir}`" + +#~ msgid "Remove all files under directories matching ``dir-pattern``" +#~ msgstr "" +#~ "Remove todos os arquivos sob diretórios correspondendo a ``padrão-dir``" + +#~ msgid "" +#~ "The patterns here are glob-style patterns: ``*`` matches zero or more " +#~ "regular filename characters (on Unix, everything except forward slash; on " +#~ "Windows, everything except backslash and colon); ``?`` matches a single " +#~ "regular filename character, and ``[chars]`` matches any one of the " +#~ "characters between the square brackets (which may contain character " +#~ "ranges, e.g., ``[a-z]`` or ``[a-fA-F0-9]``). Setuptools also has " +#~ "undocumented support for ``**`` matching zero or more characters " +#~ "including forward slash, backslash, and colon." +#~ msgstr "" +#~ "Os padrões aqui são padrões do estilo glob: ``*`` corresponde a zero ou " +#~ "mais caracteres de nome de arquivo regulares (no Unix, tudo exceto barra; " +#~ "no Windows, tudo exceto barra invertida e dois pontos); ``?`` corresponde " +#~ "a um único caractere de nome de arquivo regular, e ``[chars]`` " +#~ "corresponde a qualquer um dos caracteres entre os colchetes (que podem " +#~ "conter intervalos de caracteres, por exemplo, ``[az]`` ou ``[ a-fA-" +#~ "F0-9]``). Setuptools também oferece suporte não documentado a ``**`` " +#~ "correspondendo a zero ou mais caracteres, incluindo barra, barra " +#~ "invertida e dois pontos." + +#~ msgid "" +#~ "Directory patterns are relative to the root of the project directory; " +#~ "e.g., ``graft example*`` will include a directory named :file:`examples` " +#~ "in the project root but will not include :file:`docs/examples/`." +#~ msgstr "" +#~ "Os padrões de diretório são relativos à raiz do diretório do projeto; por " +#~ "exemplo, ``graft exemplo*`` incluirá um diretório " +#~ "chamado :file:`exemplos` na raiz do projeto, mas não incluirá :file:`docs/" +#~ "exemplos/`." + +#~ msgid "" +#~ "File & directory names in :file:`MANIFEST.in` should be ``/``-separated; " +#~ "setuptools will automatically convert the slashes to the local platform's " +#~ "appropriate directory separator." +#~ msgstr "" +#~ "Nomes de arquivos e diretórios em :file:`MANIFEST.in` devem ser separados " +#~ "por ``/``; setuptools irá converter automaticamente as barras para o " +#~ "separador de diretório apropriado da plataforma local." + +#~ msgid "" +#~ "Commands are processed in the order they appear in " +#~ "the :file:`MANIFEST.in` file. For example, given the commands:" +#~ msgstr "" +#~ "Os comandos são processados na ordem em que aparecem no " +#~ "arquivo :file:`MANIFEST.in`. Por exemplo, dados os comandos:" + +#~ msgid "" +#~ "the contents of the directory tree :file:`tests` will first be added to " +#~ "the sdist, and then after that all files in the sdist with a ``.pyc``, " +#~ "``.pyo``, or ``.pyd`` extension will be removed from the sdist. If the " +#~ "commands were in the opposite order, then ``*.pyc`` files etc. would be " +#~ "only be removed from what was already in the sdist before " +#~ "adding :file:`tests`, and if :file:`tests` happened to contain any " +#~ "``*.pyc`` files, they would end up included in the sdist because the " +#~ "exclusion happened before they were included." +#~ msgstr "" +#~ "o conteúdo da árvore de diretórios :file:`tests` será primeiro adicionado " +#~ "ao sdist, e depois disso todos os arquivos no sdist com uma extensão " +#~ "``.pyc``, ``.pyo`` ou ``.pyd`` será removidos do sdist. Se os comandos " +#~ "estivessem na ordem oposta, então os arquivos ``*.pyc`` etc. seriam " +#~ "removidos apenas do que já estava no sdist antes de " +#~ "adicionar :file:`tests`, e se :file:`tests` contivesse quaisquer arquivos " +#~ "``*.pyc``, eles acabariam incluídos no sdist porque a exclusão aconteceu " +#~ "antes de serem incluídos." + +#~ msgid "" +#~ "Use `pkgutil-style namespace packages`_. This is recommended for new " +#~ "packages that need to support Python 2 and 3 and installation via both " +#~ "``pip`` and ``python setup.py install``." +#~ msgstr "" +#~ "Usar `pacotes de espaço de nomes no estilo pkgutil`_. Isso é recomendado " +#~ "para novos pacotes que precisam oferecer suporte a Python 2 e 3 e à " +#~ "instalação via ``pip`` e ``python setup.py install``." + +#~ msgid "" +#~ "Use `pkg_resources-style namespace packages`_. This method is recommended " +#~ "if you need compatibility with packages already using this method or if " +#~ "your package needs to be zip-safe." +#~ msgstr "" +#~ "Usar `pacotes de espaço de nomes no estilo pkg_resources`_. Este método é " +#~ "recomendado se você precisa de compatibilidade com pacotes que já usam " +#~ "este método ou se seu pacote precisa ser seguro para uso de zip." + +#~ msgid "" +#~ "Because ``mynamespace`` doesn't contain " +#~ "an :file:`__init__.py`, :func:`setuptools.find_packages` won't find the " +#~ "sub-package. You must use :func:`setuptools.find_namespace_packages` " +#~ "instead or explicitly list all packages in your :file:`setup.py`. For " +#~ "example:" +#~ msgstr "" +#~ "Porque ``mynamespace`` não contém " +#~ "um :file:`__init__.py`, :func:`setuptools.find_packages` não encontrará o " +#~ "subpacote. Você deve usar :func:`setuptools.find_namespace_packages` ou " +#~ "listar explicitamente todos os pacotes em seu :file:`setup.py`. Por " +#~ "exemplo:" + +#~ msgid "You can make sure that pip is up-to-date by running:" +#~ msgstr "Você pode ter certeza de que o pip está atualizado executando:" + +#~ msgid "" +#~ "This guide discusses how to install packages using :ref:`pip` and a " +#~ "virtual environment manager: either :ref:`venv` for Python 3 " +#~ "or :ref:`virtualenv` for Python 2. These are the lowest-level tools for " +#~ "managing Python packages and are recommended if higher-level tools do not " +#~ "suit your needs." +#~ msgstr "" +#~ "Este guia discute como instalar pacotes usando :ref:`pip` e um " +#~ "gerenciador de ambiente virtual: ou :ref:`venv` para Python 3 " +#~ "ou :ref:`virtualenv` para Python 2 Estas são as ferramentas de nível mais " +#~ "baixo para gerenciar pacotes Python e são recomendadas se as ferramentas " +#~ "de nível mais alto não atenderem às suas necessidades." + +#~ msgid "Installing pip" +#~ msgstr "Instalando pip" + +#~ msgid "" +#~ "Debian and most other distributions include a `python-pip`_ package; if " +#~ "you want to use the Linux distribution-provided versions of pip, " +#~ "see :doc:`/guides/installing-using-linux-tools`." +#~ msgstr "" +#~ "O Debian e a maioria das outras distribuições incluem um pacote `python-" +#~ "pip`_; se você deseja usar as versões fornecidas pela distribuição Linux " +#~ "do pip, consulte :doc:`/guides/installing-using-linux-tools`." + +#~ msgid "" +#~ "You can also install pip yourself to ensure you have the latest version. " +#~ "It's recommended to use the system pip to bootstrap a user installation " +#~ "of pip:" +#~ msgstr "" +#~ "Você também pode instalar o pip por conta própria para garantir que " +#~ "possui a versão mais recente. É recomendado usar o sistema pip para " +#~ "inicializar uma instalação de usuário do pip:" + +#~ msgid "Installing virtualenv" +#~ msgstr "Instalando virtualenv" + +#~ msgid "" +#~ "If you are using Python 3.3 or newer, the :mod:`venv` module is the " +#~ "preferred way to create and manage virtual environments. venv is included " +#~ "in the Python standard library and requires no additional installation. " +#~ "If you are using venv, you may skip this section." +#~ msgstr "" +#~ "Se você estiver usando o Python 3.3 ou mais recente, o módulo :mod:`venv` " +#~ "é a forma preferida de criar e gerenciar ambientes virtuais. venv está " +#~ "incluído na biblioteca padrão Python e não requer instalação adicional. " +#~ "Se você estiver usando venv, pode pular esta seção." + +#~ msgid "" +#~ ":ref:`virtualenv` is used to manage Python packages for different " +#~ "projects. Using virtualenv allows you to avoid installing Python packages " +#~ "globally which could break system tools or other projects. You can " +#~ "install virtualenv using pip." +#~ msgstr "" +#~ ":ref:`virtualenv` é usado para gerenciar pacotes Python para diferentes " +#~ "projetos. O uso do virtualenv permite que você evite instalar pacotes " +#~ "Python globalmente, o que poderia quebrar as ferramentas do sistema ou " +#~ "outros projetos. Você pode instalar virtualenv usando pip." + +#~ msgid "It should be in the ``env`` directory:" +#~ msgstr "Deve estar no diretório ``env``:" + +#~ msgid "Leaving the virtual environment" +#~ msgstr "Saindo do ambiente virtual" + +#~ msgid "Installing specific versions" +#~ msgstr "Instalando versões específicas" + +#~ msgid "pip can install a package directly from source, for example:" +#~ msgstr "" +#~ "pip pode instalar um pacote diretamente do código-fonte, por exemplo:" + +#~ msgid "Installing Packages:" +#~ msgstr "Instalando pacotes:" + +#~ msgid "Miscellaneous:" +#~ msgstr "Diversos:" + +#~ msgid "The version of the project as supported by :pep:`440`." +#~ msgstr "A versão do projeto conforme suportado pela :pep:`440`." + +#~ msgid "" +#~ "Version numbering requirements and the semantics for specifying " +#~ "comparisons between versions are defined in :pep:`440`." +#~ msgstr "" +#~ "Os requisitos de numeração de versão e a semântica para especificar " +#~ "comparações entre as versões são definidos na :pep:`440`." + +#~ msgid "" +#~ "The version specifiers section in this PEP supersedes the version " +#~ "specifiers section in :pep:`345`." +#~ msgstr "" +#~ "A seção de especificadores de versão nesta PEP substitui a seção de " +#~ "especificadores de versão na :pep:`345`." + +#~ msgid "FIXME" +#~ msgstr "FIXME" + +#~ msgid "mention the stable ABI (3.2+, link to the CPython C API docs)" +#~ msgstr "" +#~ "mencionar a ABI estável (3.2+, link para os documentos da API CPython C)" + +#~ msgid "mention the implications of the GIL for extension modules" +#~ msgstr "mencionar as implicações do GIL para módulos de extensão" + +#~ msgid "" +#~ "For interim guidance on this topic, see the discussion in :issue:`this " +#~ "issue <284>`." +#~ msgstr "" +#~ "Para obter orientações provisórias sobre este tópico, consulte a " +#~ "discussão :issue:`neste relatório de problema <284>`." + +#~ msgid "cover publishing as wheel files on PyPI or a custom index server" +#~ msgstr "" +#~ "cobrir a publicação como arquivos wheel no PyPI ou um servidor de " +#~ "indexação personalizado" + +#~ msgid "cover creation of Windows and macOS installers" +#~ msgstr "cobrir a criação de instaladores do Windows e do macOS" + +#~ msgid "" +#~ "mention the fact that Linux distros have a requirement to build from " +#~ "source in their own build systems, so binary-only releases are strongly " +#~ "discouraged" +#~ msgstr "" +#~ "mencionar o fato de que as distribuições Linux têm um requisito para " +#~ "construir a partir da fonte em seus próprios sistemas de construção, " +#~ "portanto, versões somente binárias são fortemente desencorajadas" + +#~ msgid "" +#~ "This section covers the basics of how to create documentation using " +#~ "`Sphinx`_ and host the documentation for free in `Read The Docs`_." +#~ msgstr "" +#~ "Esta seção cobre o básico de como criar documentação usando `Sphinx`_ e " +#~ "hospedar a documentação gratuitamente em `Read The Docs`_." + +#~ msgid "Installing Sphinx" +#~ msgstr "Instalando o Sphinx" + +#~ msgid "Use ``pip`` to install Sphinx:" +#~ msgstr "Use ``pip`` para instalar o Sphinx:" + +#~ msgid "" +#~ "For other installation methods, see this :doc:`installation guide " +#~ "` by Sphinx." +#~ msgstr "" +#~ "Para outros métodos de instalação, veja esta :doc:`guia de instalação " +#~ "` do Sphinx." + +#~ msgid "Getting Started With Sphinx" +#~ msgstr "Primeiros passos com Sphinx" + +#~ msgid "" +#~ "Create a ``docs`` directory inside your project to hold your " +#~ "documentation:" +#~ msgstr "" +#~ "Crie um diretório ``docs`` dentro de seu projeto para conter sua " +#~ "documentação:" + +#~ msgid "Run ``sphinx-quickstart`` inside the ``docs`` directory:" +#~ msgstr "Execute ``sphinx-quickstart`` dentro do diretório ``docs``:" + +#~ msgid "" +#~ "This sets up a source directory, walks you through some basic " +#~ "configurations, and creates an ``index.rst`` file as well as a " +#~ "``conf.py`` file." +#~ msgstr "" +#~ "Isso configura um diretório fonte, orienta você por algumas configurações " +#~ "básicas e cria um arquivo ``index.rst``, bem como um arquivo ``conf.py``." + +#~ msgid "" +#~ "You can add some information about your project in ``index.rst``, then " +#~ "build them:" +#~ msgstr "" +#~ "Você pode adicionar algumas informações sobre o seu projeto em " +#~ "``index.rst`` e, em seguida, construí-las:" + +#~ msgid "" +#~ "For more details on the build process, see this `guide`_ by Read The Docs." +#~ msgstr "" +#~ "Para mais detalhes sobre o processo de construção, veja o `guia`_ do Read " +#~ "The Docs." + +#~ msgid "" +#~ "For a more detailed guide on how to use Sphinx and reStructuredText, " +#~ "please see this `documentation tutorial`_ on Hitchhiker's Guide to Python." +#~ msgstr "" +#~ "Para um guia mais detalhado sobre como usar o Sphinx e o " +#~ "reStructuredText, consulte este `tutorial de documentação`_ no Guia do " +#~ "Mochileiro para Python." + +#~ msgid "" +#~ "Essential tools and concepts for working within the Python development " +#~ "ecosystem are covered in our :doc:`tutorials/index` section:" +#~ msgstr "" +#~ "Ferramentas e conceitos essenciais para trabalhar dentro do ecossistema " +#~ "de desenvolvimento do Python são abordados em nossa seção " +#~ "de :doc:`tutorials/index`:" + +#~ msgid "" +#~ "To get an overview of packaging options for Python libraries and " +#~ "applications, see the :doc:`Overview of Python Packaging `" +#~ msgstr "" +#~ "Para obter uma visão geral das opções de empacotamento para bibliotecas e " +#~ "aplicações Python, veja a :doc:`Visão geral de empacotamento no Python " +#~ "`" + +#~ msgid "Learn more" +#~ msgstr "Saiba mais" + +#~ msgid "" +#~ "Beyond our :doc:`tutorials/index`, this guide has several other resources:" +#~ msgstr "" +#~ "Além de nossos :doc:`tutorials/index`, este guia possui vários outros " +#~ "recursos:" + +#~ msgid "" +#~ "The :doc:`guides/index` section for walk throughs, such as :doc:`guides/" +#~ "installing-using-linux-tools` or :doc:`guides/packaging-binary-" +#~ "extensions`." +#~ msgstr "" +#~ "A seção :doc:`guides/index` para passos a passos, tal como :doc:`guides/" +#~ "installing-using-linux-tools` ou :doc:`guides/packaging-binary-" +#~ "extensions`." + +#~ msgid "" +#~ "The :doc:`discussions/index` section for in-depth references on topics " +#~ "such as :doc:`discussions/deploying-python-applications` " +#~ "or :doc:`discussions/pip-vs-easy-install`." +#~ msgstr "" +#~ "A seção :doc:`discussions/index` para referências detalhadas sobre " +#~ "tópicos como :doc:`discussions/deploying-python-applications` " +#~ "ou :doc:`discussions/pip-vs-easy-install`." + +#~ msgid "" +#~ "``requires`` is a list of packages that are needed to build your package. " +#~ "You don't need to install them; build frontends like :ref:`pip` will " +#~ "install them automatically in a temporary, isolated virtual environment " +#~ "for use during the build process." +#~ msgstr "" +#~ "``requires`` é uma lista de pacotes que são necessários para construir " +#~ "seu pacote. Você não precisa instalá-los; frontends de construção " +#~ "como :ref:`pip` irá instalá-los automaticamente em um ambiente virtual " +#~ "isolado temporário para uso durante o processo de compilação." + +#~ msgid "" +#~ "`Docs `__ | `Issues " +#~ "`__" +#~ msgstr "" +#~ "`Documentação `__ " +#~ "| `Issues `__" + +#~ msgid "Saving credentials on GitHub" +#~ msgstr "Salvando credenciais no GitHub" + +#~ msgid "" +#~ "In this guide, we'll demonstrate uploading to both PyPI and TestPyPI, " +#~ "meaning that we'll have two separate sets of credentials. And we'll need " +#~ "to save them in the GitHub repository settings." +#~ msgstr "" +#~ "Neste guia, demonstraremos o envio para o PyPI e TestPyPI, o que " +#~ "significa que teremos dois conjuntos separados de credenciais. E " +#~ "precisaremos salvá-los nas configurações do repositório do GitHub." + +#~ msgid "" +#~ "Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +#~ "token`_. If you have the project on PyPI already, limit the token scope " +#~ "to just that project. You can call it something like ``GitHub Actions CI/" +#~ "CD — project-org/project-repo`` in order for it to be easily " +#~ "distinguishable in the token list. **Don't close the page just yet — you " +#~ "won't see that token again.**" +#~ msgstr "" +#~ "Vá para https://pypi.org/manage/account/#api-tokens e crie um novo `token " +#~ "de API`_. Se você já tem o projeto no PyPI, limite o escopo do token " +#~ "apenas a esse projeto. Você pode chamá-lo de algo como ``GitHub Actions " +#~ "CI/CD — project-org/project-repo`` para que seja facilmente distinguível " +#~ "na lista de tokens. **Não feche a página ainda -- você não verá esse " +#~ "token novamente.**" + +#~ msgid "" +#~ "In a separate browser tab or window, go to the ``Settings`` tab of your " +#~ "target repository and then click on `Secrets`_ in the left sidebar." +#~ msgstr "" +#~ "Em uma guia ou janela separada do navegador, vá para a aba " +#~ "``Configurações`` do seu repositório de destino e clique em `Secrets`_ na " +#~ "barra lateral esquerda." + +#~ msgid "" +#~ "Create a new secret called ``PYPI_API_TOKEN`` and copy-paste the token " +#~ "from the first step." +#~ msgstr "" +#~ "Crie um novo segredo chamado ` PYPI_API_TOKEN`` e copie e cole o token da " +#~ "primeira etapa." + +#~ msgid "" +#~ "Now, let's add initial setup for our job. 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:" +#~ msgstr "" +#~ "Agora, vamos adicionar a configuração inicial para nosso trabalho. É um " +#~ "processo que executará comandos que definiremos mais tarde. Neste guia, " +#~ "usaremos a versão estável mais recente do Ubuntu LTS fornecido pelo " +#~ "GitHub Actions:" + +#~ msgid "Then, add the following under the ``build-n-publish`` section:" +#~ msgstr "Então, adicione o seguinte sob a seção ``build-n-publish``:" + +#, fuzzy +#~ msgid "" +#~ "You can use any other method for building distributions as long as it " +#~ "produces ready-to-upload artifacts saved into the ``dist/`` folder. You " +#~ "can even use ``actions/upload-artifact`` and ``actions/download-" +#~ "artifact`` to transfer files between jobs or make them accessible for " +#~ "download from the web CI interface." +#~ msgstr "" +#~ "Você pode usar qualquer outro método para construir distribuições, desde " +#~ "que produza artefatos prontos para enviar, salvos na pasta ``dist/``. " +#~ "Você pode até mesmo usar ``actions/upload-artifact`` e ``actions/download-" +#~ "artifact`` para transferir arquivos entre trabalhos ou torná-los " +#~ "acessíveis para download a partir da interface web de CI." + +#~ msgid "So add this to the steps list:" +#~ msgstr "Então, adicione isso à lista de etapas:" + +#~ msgid "" +#~ "These two steps use the `pypa/gh-action-pypi-publish`_ GitHub Action: the " +#~ "first one uploads contents of the ``dist/`` folder into TestPyPI " +#~ "unconditionally and the second does that to PyPI, but only if the current " +#~ "commit is tagged. It is recommended you use the latest release tag; a " +#~ "tool like GitHub's dependabot can keep these updated regularly." +#~ msgstr "" +#~ "Essas duas etapas usam a GitHub Action `pypa/gh-action-pypi-publish`_: a " +#~ "primeira carrega o conteúdo da pasta ``dist /`` para TestPyPI " +#~ "incondicionalmente e a segunda faz isso para PyPI, mas apenas se o commit " +#~ "atual estiver marcado. É recomendado que você use a tag de lançamento " +#~ "mais recente; uma ferramenta como o dependabot do GitHub pode mantê-los " +#~ "atualizados regularmente." + +#~ msgid "" +#~ "`Docs `__ | `GitHub `__ | " +#~ "`PyPI `__" +#~ msgstr "" +#~ "`Documentação `__ | `GitHub `__ | " +#~ "`PyPI `__" + +#~ msgid "_`https://bazaar.canonical.com` *(Not responding as of 5/2023)*" +#~ msgstr "_`https://bazaar.canonical.com` *(Não responde desde 5/2023)*" + +#~ 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 "" +#~ "Esta é uma lista de especificações de interoperabilidade atualmente " +#~ "ativas mantidas pela Python Packaging Authority. O processo de " +#~ "atualização desses padrões e de proposição de novos está documentado em " +#~ "`pypa.io `__." + +#~ msgid "" +#~ "It may also be known that project A follows semantic versioning, and that " +#~ "v2 of 'A' will indicate a break in compatibility, so it makes sense to " +#~ "not allow v2:" +#~ msgstr "" +#~ "Também pode ser sabido que o projeto A segue versionamento semântico, e " +#~ "que a v2 de \"A\" irá indicar uma quebra na compatibilidade, então faz " +#~ "sentido não permitir a v2:" + +#~ msgid ":term:`Wheel` has an :pep:`official PEP <427>`. :term:`Egg` did not." +#~ msgstr "" +#~ ":term:`Wheel` tem uma :pep:`PEP oficial <427>`. :term:`Egg` não tinha." + +#~ msgid "" +#~ "Circumstantially, in some cases, wheels can be used as an importable " +#~ "runtime format, although :pep:`this is not officially supported at this " +#~ "time <427#is-it-possible-to-import-python-code-directly-from-a-wheel-" +#~ "file>`." +#~ msgstr "" +#~ "Circunstancialmente, em alguns casos, wheels podem ser usados como um " +#~ "formato de tempo de execução importável, embora :pep:`não haja suporte " +#~ "oficial a isso no momento <427#is-it-possible-to-import-python-code-" +#~ "directly-from-a-wheel-file>`." + +#~ msgid "" +#~ "Note that the rows are stored in a partitioned, which helps limit the " +#~ "cost of queries. These example queries analyze downloads from recent " +#~ "history by filtering on the ``timestamp`` column." +#~ msgstr "" +#~ "Observe que as linhas são armazenadas em uma partição particionada, o que " +#~ "ajuda a limitar o custo das consultas. Essas consultas de exemplo " +#~ "analisam downloads do histórico recente filtrando na coluna ``timestamp``." + +#~ msgid "" +#~ "To only count downloads from pip, filter on the " +#~ "``details.installer.name`` column." +#~ msgstr "" +#~ "Para contar apenas os downloads do pip, filtre na coluna " +#~ "``details.installer.name``." + +#~ msgid "For CentOS, see here: https://www.softwarecollections.org/en/" +#~ msgstr "Para CentOS, veja aqui: https://www.softwarecollections.org/en/" + +#~ msgid "Debian/Ubuntu" +#~ msgstr "Debian/Ubuntu" + +#~ msgid "" +#~ "This will download your repository into the CI runner and then install " +#~ "and activate Python 3.10." +#~ msgstr "" +#~ "Isso fará o download do seu repositório no executor de CI e, em seguida, " +#~ "instalará e ativará o Python 3.10." + +#~ 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 `bottle.py `_ " +#~ "and :doc:`boltons `." +#~ msgstr "" +#~ "Isso é ótimo para compartilhar scripts e trechos simples entre pessoas " +#~ "que possuem versões Python compatíveis (como via e-mail, StackOverflow ou " +#~ "gists do GitHub). Existem até algumas bibliotecas Python inteiras que " +#~ "oferecem isso como uma opção, como `bottle.py `_ e :doc:`boltons `." + +#~ msgid "" +#~ "Computing as we know it is defined by the ability to execute programs. " +#~ "Every operating system natively supports one or more formats of program " +#~ "they can natively execute." +#~ msgstr "" +#~ "A computação como a conhecemos é definida pela capacidade de executar " +#~ "programas. Cada sistema operacional oferece suporte nativamente a um ou " +#~ "mais formatos de programa que eles podem executar nativamente." + +#~ msgid "" +#~ "These techniques are mostly reserved for larger scale deployments in data " +#~ "centers, though certain complex applications can benefit from this " +#~ "packaging. Technologies are Python agnostic, and include:" +#~ msgstr "" +#~ "Essas técnicas são reservadas principalmente para implantações em grande " +#~ "escala em datacenters, embora algumas aplicativas complexas possam se " +#~ "beneficiar desse pacote. As tecnologias são agnósticas ao Python e " +#~ "incluem:" + +#, fuzzy +#~ msgid "https://bazaar.canonical.com" +#~ msgstr "https://bazaar.canonical.com/" + +#~ msgid "" +#~ "It's the command line interface for running various commands that relate " +#~ "to packaging tasks. To get a listing of available commands, run ``python " +#~ "setup.py --help-commands``." +#~ msgstr "" +#~ "É a interface de linha de comando para executar vários comandos " +#~ "relacionados a tarefas de empacotamento. Para obter uma lista dos " +#~ "comandos disponíveis, execute ``python setup.py --help-commands``." + +#~ msgid "" +#~ "A variation on the above which pre-builds the installation files for the " +#~ "requirements using :ref:`python -m pip wheel `:" +#~ msgstr "" +#~ "Uma variação acima, que pré-constrói os arquivos de instalação para os " +#~ "requisitos usando :ref:`python -m pip wheel `:" + +#~ 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 ``python -c ''`` to invoke the " +#~ "application's main entry point directly." +#~ msgstr "" +#~ "Isso pode ser contornado definindo todas as dependências em ``__main__.__ " +#~ "require__`` antes de importar ``pkg_resources`` pela primeira vez, mas " +#~ "essa abordagem significa que as invocações de linha de comando padrão das " +#~ "ferramentas afetadas não podem ser usadas -- é necessário escrever um " +#~ "script wrapper personalizado ou usar ``python -c ''`` para " +#~ "invocar o ponto de entrada principal da aplicação diretamente." + +#, fuzzy +#~ 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 `bottle.py `_ and :doc:`boltons `." +#~ msgstr "" +#~ "Isso é ótimo para compartilhar scripts e trechos simples entre pessoas " +#~ "que possuem versões Python compatíveis (como via e-mail, StackOverflow ou " +#~ "gists do GitHub). Existem até algumas bibliotecas Python inteiras que " +#~ "oferecem isso como uma opção, como `bottle.py `_ e :doc:`boltons `." + +#~ msgid "" +#~ "This guide *assumes* that you already have a project that you know how to " +#~ "build distributions for and *it lives on GitHub*." +#~ msgstr "" +#~ "Este guia *presume* que você já tem um projeto para o qual sabe como " +#~ "construir distribuições e *ele reside no GitHub*." + +#~ msgid "" +#~ "And now we can build dists from source. In this example, we'll use " +#~ "``build`` package, assuming that your project has a ``pyproject.toml`` " +#~ "properly set up (see :pep:`517`/:pep:`518`)." +#~ msgstr "" +#~ "E agora podemos construir dists a partir da fonte. Neste exemplo, " +#~ "usaremos o pacote ``build``, presumindo que seu projeto tem um " +#~ "``pyproject.toml`` configurado corretamente (veja :pep:`517` /:pep:`518`)." + +#~ msgid "" +#~ "You can use any other method for building distributions as long as it " +#~ "produces ready-to-upload artifacts saved into the ``dist/`` folder." +#~ msgstr "" +#~ "Você pode usar qualquer outro método para construir distribuições, desde " +#~ "que produza artefatos prontos para enviar, salvos na pasta ``dist/``." + +#~ msgid "" +#~ "This JSON file MUST be a dictionary, compliant with :rfc:`8259` and UTF-8 " +#~ "encoded." +#~ msgstr "" +#~ "Este arquivo JSON DEVE ser um dicionário compatível com :rfc:`8259` e " +#~ "codificado em UTF-8." + +#~ msgid "Example direct_url.json" +#~ msgstr "Exemplo de direct_url.json" + +#~ msgid "" +#~ "The platform compatibility tagging model used for the ``wheel`` " +#~ "distribution format is defined in :pep:`425`." +#~ msgstr "" +#~ "O modelo de tag de compatibilidade de plataforma usado para o formato de " +#~ "distribuição ``wheel`` é definido em :pep:`425`." + +#~ msgid "Platform tags for Windows" +#~ msgstr "Tags de plataforma para Windows" + +#~ msgid "" +#~ "The scheme defined in :pep:`425` covers public distribution of wheel " +#~ "files to systems running Windows." +#~ msgstr "" +#~ "O esquema definido em :pep:`425` cobre a distribuição pública de arquivos " +#~ "wheel para sistemas executando Windows." + +#~ msgid "Platform tags for macOS (Mac OS X)" +#~ msgstr "Tags de plataforma para macOS (Mac OS X)" + +#~ msgid "" +#~ "The scheme defined in :pep:`425` covers public distribution of wheel " +#~ "files to systems running macOS (previously known as Mac OS X)." +#~ msgstr "" +#~ "O esquema definido em :pep:`425` cobre a distribuição pública de arquivos " +#~ "wheel para sistemas que executam macOS (anteriormente conhecido como Mac " +#~ "OS X)." + +#~ msgid "Platform tags for common Linux distributions" +#~ msgstr "Tags de plataforma para distribuições Linux comuns" + +#~ msgid "Platform tags for other \\*nix platforms" +#~ msgstr "Tags de plataforma para outras plataformas \\*nix" + +#~ msgid "" +#~ "The scheme defined in :pep:`425` is not generally sufficient for public " +#~ "distribution of wheel files to other \\*nix platforms. Efforts are " +#~ "currently (albeit intermittently) under way to define improved " +#~ "compatibility tagging schemes for AIX and for Alpine Linux." +#~ msgstr "" +#~ "O esquema definido na :pep:`425` geralmente não é suficiente para a " +#~ "distribuição pública de arquivos wheel para outras plataformas \\*nix. " +#~ "Esforços estão atualmente (embora de forma intermitente) em andamento " +#~ "para definir esquemas de marcação de compatibilidade aprimorados para AIX " +#~ "e Alpine Linux." + +#~ msgid "" +#~ "For projects which don't provide their own Windows installers (and even " +#~ "some which do), Christoph Gohlke at the University of California provides " +#~ "a `collection of Windows installers `__. Many Python users on Windows have reported a positive " +#~ "experience with these prebuilt versions." +#~ msgstr "" +#~ "Para projetos que não fornecem seus próprios instaladores para Windows (e " +#~ "até mesmo alguns que oferecem), Christoph Gohlke da Universidade da " +#~ "Califórnia fornece uma `coleção de instaladores para Windows `__. Muitos usuários do Python no " +#~ "Windows relataram uma experiência positiva com essas versões pré-" +#~ "construídas." + +#~ msgid "" +#~ "Earlier versions of setuptools implemented the ``attr:`` directive by " +#~ "importing the module, but setuptools 46.4.0 added rudimentary AST " +#~ "analysis so that ``attr:`` can function without having to import any of " +#~ "the package's dependencies." +#~ msgstr "" +#~ "Versões anteriores de setuptools implementavam a diretiva ``attr:`` " +#~ "importando o módulo, mas setuptools 46.4.0 adicionou uma análise de AST " +#~ "rudimentar para que ``attr:`` possa funcionar sem ter que importar " +#~ "nenhuma das dependências do pacote." + +#~ msgid "" +#~ ":doc:`Setuptools ` provides :doc:`special support " +#~ "` for plugins. By providing the " +#~ "``entry_points`` argument to :func:`setup` in :file:`setup.py` plugins " +#~ "can register themselves for discovery." +#~ msgstr "" +#~ ":doc:`Setuptools ` fornece :doc:`suporte especial " +#~ "` para plugins. Fornecendo o argumento " +#~ "``entry_points`` para :func:`setup` em :file:`setup.py`, os plugins podem " +#~ "se registrar para serem descobertos." + +#~ msgid "" +#~ "A corresponding :ref:`core metadata ` field does not exist" +#~ msgstr "" +#~ "Não há um campo correspondente dos :ref:`metadados principais `" + +#~ msgid "" +#~ "To build the guide, run the following bash command in the source folder:" +#~ msgstr "" +#~ "Para construir o guia, execute o seguinte comando bash na pasta do código-" +#~ "fonte:" + +#~ msgid "" +#~ "`GitHub and Docs `__ | `PyPI " +#~ "`__" +#~ msgstr "" +#~ "`GitHub e documentação `__ | " +#~ "`PyPI `__" + +#~ msgid "" +#~ ":doc:`Docs ` | `Issues `__ | `Bitbucket `__ | `PyPI `__" +#~ msgstr "" +#~ ":doc:`Documentação ` | `Issues `__ | `Bitbucket `__ | `PyPI `__" + +#~ msgid "" +#~ "For more information, see `Automatic Script Creation `_ from the :doc:`setuptools docs " +#~ "`." +#~ msgstr "" +#~ "Para obter mais informações, consulte `Automatic Script Creation `_ da `documentação do setuptools " +#~ "`." + +#~ msgid "Install `setuptools extras`_." +#~ msgstr "Instale `setuptools extras`_." + +#~ msgid "" +#~ "This tutorial uses a simple project named ``example_package``. We " +#~ "recommend following this tutorial as-is using this project, before " +#~ "packaging your own project." +#~ msgstr "" +#~ "Este tutorial usa um projeto simples chamado ``example_package``. " +#~ "Recomendamos seguir este tutorial como está usando este projeto, antes de " +#~ "empacotar seu próprio projeto." + +#~ msgid "" +#~ "``build-system.requires`` gives a list of packages that are needed to " +#~ "build your package. Listing something here will *only* make it available " +#~ "during the build, not after it is installed." +#~ msgstr "" +#~ "``build-system.requires`` fornece uma lista de pacotes que são " +#~ "necessários para construir seu pacote. Listar algo aqui *apenas* o " +#~ "tornará disponível durante a construção, não depois de instalado." + +#~ msgid "" +#~ "``build-system.build-backend`` is the name of Python object that will be " +#~ "used to perform the build. If you were to use a different build system, " +#~ "such as :ref:`flit` or :ref:`poetry`, those would go here, and the " +#~ "configuration details would be completely different than " +#~ "the :ref:`setuptools` configuration described below." +#~ msgstr "" +#~ "``build-system.build-backend`` é o nome do objeto Python que será usado " +#~ "para realizar a construção. Se você fosse usar um sistema de construção " +#~ "diferente, como :ref:`flit` ou :ref:`poetry`, eles iriam aqui, e os " +#~ "detalhes de configuração seriam completamente diferentes da configuração " +#~ "do :ref:`setuptools` descrita abaixo." + +#~ msgid "There are two types of metadata: static and dynamic." +#~ msgstr "Há dois tipos de metadados: estáticos e dinâmicos." + +#~ msgid "" +#~ "Static metadata (:file:`setup.cfg`): guaranteed to be the same every " +#~ "time. This is simpler, easier to read, and avoids many common errors, " +#~ "like encoding errors." +#~ msgstr "" +#~ "Metadados estáticos (:file:`setup.cfg`): garantidamente os mesmos sempre. " +#~ "Isso é mais simples, fácil de ler e evita muitos erros comuns, como erros " +#~ "de codificação." + +#~ msgid "" +#~ "Dynamic metadata (:file:`setup.py`): possibly non-deterministic. Any " +#~ "items that are dynamic or determined at install-time, as well as " +#~ "extension modules or extensions to setuptools, need to go " +#~ "into :file:`setup.py`." +#~ msgstr "" +#~ "Metadados dinâmicos (:file:`setup.py`): possivelmente não " +#~ "determinísticos. Quaisquer itens que são dinâmicos ou determinados no " +#~ "momento da instalação, bem como módulos de extensão ou extensões para " +#~ "setuptools, precisam ir para :file:`setup.py`." + +#~ msgid "" +#~ "Static metadata (:file:`setup.cfg`) should be preferred. Dynamic metadata " +#~ "(:file:`setup.py`) should be used only as an escape hatch when absolutely " +#~ "necessary. :file:`setup.py` used to be required, but can be omitted with " +#~ "newer versions of setuptools and pip." +#~ msgstr "" +#~ "Metadados estáticos (:file:`setup.cfg`) devem ser preferidos. Metadados " +#~ "dinâmicos (:file:`setup.py`) devem ser usados apenas como uma saída de " +#~ "emergência quando for absolutamente necessário. :file:`setup.py` " +#~ "costumava ser necessário, mas pode ser omitido com as versões mais " +#~ "recentes de setuptools e pip." + +#~ msgid "" +#~ ":file:`setup.cfg` is the configuration file for :ref:`setuptools`. It " +#~ "tells setuptools about your package (such as the name and version) as " +#~ "well as which code files to include. Eventually much of this " +#~ "configuration may be able to move to :file:`pyproject.toml`." +#~ msgstr "" +#~ ":file:`setup.cfg` é o arquivo de configuração para :ref:`setuptools`. Ele " +#~ "informa ao setuptools sobre o seu pacote (como o nome e a versão), bem " +#~ "como os arquivos de código a serem incluídos. Eventualmente, grande parte " +#~ "desta configuração pode ser movida para :file:`pyproject.toml`." + +#~ msgid "" +#~ "There are a `variety of metadata and options `_ " +#~ "supported here. This is in :doc:`configparser ` format; do not place quotes around values. This example " +#~ "package uses a relatively minimal set of ``metadata``:" +#~ msgstr "" +#~ "Há uma `variedade de metadados e opções `_ " +#~ "suportados aqui. Isso está no formato :doc:`configparser `; não coloque aspas em torno dos valores. Este pacote de " +#~ "exemplo usa um conjunto relativamente mínimo de ``metadata``:" + +#~ msgid "" +#~ "``author`` and ``author_email`` are used to identify the author of the " +#~ "package." +#~ msgstr "" +#~ "``author`` e ``author_email`` são usados para identificar o autor do " +#~ "pacote." + +#~ msgid "" +#~ "``long_description_content_type`` tells the index what type of markup is " +#~ "used for the long description. In this case, it's Markdown." +#~ msgstr "" +#~ "``long_description_content_type`` diz ao índice que tipo de marcação é " +#~ "usado para a descrição longa. Neste caso, é Markdown." + +#~ msgid "" +#~ "``url`` is the URL for the homepage of the project. For many projects, " +#~ "this will just be a link to GitHub, GitLab, Bitbucket, or similar code " +#~ "hosting service." +#~ msgstr "" +#~ "``url`` é a URL da página inicial do projeto. Para muitos projetos, será " +#~ "apenas um link para GitHub, GitLab, Bitbucket ou serviço de hospedagem de " +#~ "código semelhante." + +#~ msgid "In the ``options`` category, we have controls for setuptools itself:" +#~ msgstr "" +#~ "Na categoria ``options``, temos controles para o próprio setuptools:" + +#~ msgid "" +#~ "``package_dir`` is a mapping of package names and directories. An empty " +#~ "package name represents the \"root package\" --- the directory in the " +#~ "project that contains all Python source files for the package --- so in " +#~ "this case the ``src`` directory is designated the root package." +#~ msgstr "" +#~ "``package_dir`` é um mapeamento de nomes e diretórios de pacotes. Um nome " +#~ "de pacote vazio representa o \"pacote raiz\" -- o diretório no projeto " +#~ "que contém todos os arquivos fonte Python para o pacote -- então, neste " +#~ "caso, o diretório ``src`` é designado o pacote raiz." + +#~ msgid "" +#~ "``packages`` is a list of all Python :term:`import packages ` that should be included in the :term:`distribution package " +#~ "`. Instead of listing each package manually, we can " +#~ "use the ``find:`` directive to automatically discover all packages and " +#~ "subpackages and ``options.packages.find`` to specify the ``package_dir`` " +#~ "to use. In this case, the list of packages will be ``example_package`` as " +#~ "that's the only package present." +#~ msgstr "" +#~ "``packages`` é uma lista de todos os Python :term:`pacotes de importação " +#~ "` que devem ser incluídos no :term:`pacote de " +#~ "distribuição `. Em vez de listar cada pacote " +#~ "manualmente, podemos usar a diretiva ``find:`` para descobrir " +#~ "automaticamente todos os pacotes e subpacotes e ``options.packages.find`` " +#~ "para especificar o ``package_dir`` a ser usado. Neste caso, a lista de " +#~ "pacotes será ``example_package`` visto que é o único pacote presente." + +#~ msgid "" +#~ "There are many more than the ones mentioned here. See :doc:`/guides/" +#~ "distributing-packages-using-setuptools` for more details." +#~ msgstr "" +#~ "Existem muitos mais do que os mencionados aqui. Veja :doc:`/guides/" +#~ "distributing-packages-using-setuptools` para mais detalhes." + +#~ msgid "" +#~ ":file:`setup.py` is the build script for :ref:`setuptools`. It tells " +#~ "setuptools about your package (such as the name and version) as well as " +#~ "which code files to include." +#~ msgstr "" +#~ ":file:`setup.py` é o script de construção para :ref:`setuptools`. Ele " +#~ "informa ao setuptools sobre o seu pacote (como o nome e a versão), bem " +#~ "como os arquivos de código a serem incluídos." + +#~ msgid "" +#~ "Open :file:`setup.py` and enter the following content. Change the " +#~ "``name`` to include your username; this ensures that you have a unique " +#~ "package name and that your package doesn't conflict with packages " +#~ "uploaded by other people following this tutorial." +#~ msgstr "" +#~ "Abra :file:`setup.py` e insira o seguinte conteúdo. Mude o ``name`` para " +#~ "incluir seu nome de usuário; isso garante que você tenha um nome de " +#~ "pacote exclusivo e que seu pacote não entre em conflito com os pacotes " +#~ "carregados por outras pessoas que seguem este tutorial." + +#~ msgid "" +#~ ":func:`setup` takes several arguments. This example package uses a " +#~ "relatively minimal set:" +#~ msgstr "" +#~ ":func:`setup` recebe vários argumentos. Este pacote de exemplo usa um " +#~ "conjunto relativamente mínimo:" + +#~ msgid "" +#~ "``version`` is the package version. See :pep:`440` for more details on " +#~ "versions." +#~ msgstr "" +#~ "``version`` é a versão do pacote. Consulte :pep:`440` para obter mais " +#~ "detalhes sobre as versões." + +#~ msgid "" +#~ "``long_description`` is a detailed description of the package. This is " +#~ "shown on the package detail page on the Python Package Index. In this " +#~ "case, the long description is loaded from :file:`README.md`, which is a " +#~ "common pattern." +#~ msgstr "" +#~ "``long_description`` é uma descrição detalhada do pacote. Isso é mostrado " +#~ "na página de detalhes do pacote no Índice do Pacotes do Python. Neste " +#~ "caso, a descrição longa é carregada de :file:`README.md`, que é um padrão " +#~ "comum." + +#~ msgid "" +#~ "``package_dir`` is a dictionary with package names for keys and " +#~ "directories for values. An empty package name represents the \"root " +#~ "package\" --- the directory in the project that contains all Python " +#~ "source files for the package --- so in this case the ``src`` directory is " +#~ "designated the root package." +#~ msgstr "" +#~ "``package_dir`` é um dicionário com nomes de pacotes para chaves e " +#~ "diretórios para valores. Um nome de pacote vazio representa o \"pacote " +#~ "raiz\" -- o diretório no projeto que contém todos os arquivos fonte " +#~ "Python para o pacote -- então, neste caso, o diretório ``src`` é " +#~ "designado o pacote raiz." + +#~ msgid "" +#~ "``packages`` is a list of all Python :term:`import packages ` that should be included in the :term:`distribution package " +#~ "`. Instead of listing each package manually, we can " +#~ "use :func:`find_packages` to automatically discover all packages and " +#~ "subpackages under ``package_dir``. In this case, the list of packages " +#~ "will be ``example_package`` as that's the only package present." +#~ msgstr "" +#~ "``packages`` é uma lista de todos os :term:`pacotes de importação ` do Python que devem ser incluídos no :term:`pacote de " +#~ "distribuição `. Em vez de listar cada pacote " +#~ "manualmente, podemos usar :func:`find_packages` para descobrir " +#~ "automaticamente todos os pacotes e subpacotes em ``package_dir``. Neste " +#~ "caso, a lista de pacotes será ``example_package`` visto que é o único " +#~ "pacote presente." + +#~ msgid "" +#~ "``python_requires`` gives the versions of Python supported by your " +#~ "project. Installers like :ref:`pip` will look back though older versions " +#~ "of packages until it finds one that has a matching Python version." +#~ msgstr "" +#~ "``python_requires`` fornece as versões do Python suportadas pelo seu " +#~ "projeto. Instaladores como :ref:`pip` olharão para as versões anteriores " +#~ "dos pacotes até encontrar um que tenha uma versão correspondente do " +#~ "Python." + +#~ msgid "" +#~ "You may see some existing projects or other Python packaging tutorials " +#~ "that import their ``setup`` function from ``distutils.core`` rather than " +#~ "``setuptools``. This is a legacy approach that installers support for " +#~ "backwards compatibility purposes [1]_, but using the legacy ``distutils`` " +#~ "API directly in new projects is strongly discouraged, since ``distutils`` " +#~ "is deprecated as per :pep:`632` and will be removed from the standard " +#~ "library in Python 3.12." +#~ msgstr "" +#~ "Você pode ver alguns projetos existentes ou outros tutoriais de " +#~ "empacotamento Python que importam sua função ``setup`` de " +#~ "``distutils.core`` em vez de ``setuptools``. Esta é uma abordagem legada " +#~ "que os instaladores oferece suporte a compatibilidade com versões " +#~ "anteriores [1]_, mas usar a API legada do ``distutils`` diretamente em " +#~ "novos projetos é fortemente desencorajado, uma vez que ``distutils`` foi " +#~ "descontinuado de acordo com :pep:`632 `e será removido da biblioteca " +#~ "padrão em Python 3.12." + +#~ msgid "" +#~ "Because our configuration loads :file:`README.md` to provide a " +#~ "``long_description``, :file:`README.md` must be included along with your " +#~ "code when you :ref:`generate a source distribution `. Newer versions of :ref:`setuptools` will do this " +#~ "automatically." +#~ msgstr "" +#~ "Porque nossa configuração carrega :file:`README.md` para fornecer um " +#~ "``long_description``, :file:`README.md` deve ser incluído junto com seu " +#~ "código quando você :ref:`gerar uma distribuição fonte `. Versões mais recentes de :ref:`setuptools` farão isso " +#~ "automaticamente." + +#~ msgid "" +#~ "The final :term:`built distribution ` will have the " +#~ "Python files in the discovered or listed Python packages. If you want to " +#~ "control what goes here, such as to add data files, see :doc:`Including " +#~ "Data Files ` from the :doc:`setuptools " +#~ "docs `." +#~ msgstr "" +#~ "A :term:`distribuição construída ` final terá os " +#~ "arquivos Python nos pacotes descobertos ou listados Python. Se você " +#~ "deseja controlar o que acontece aqui, como adicionar arquivos de dados, " +#~ "consulte :doc:`Incluindo Arquivos de Dados ` da :doc:`documentação do setuptools `." + +#~ msgid "" +#~ "Note that the :term:`import package ` is " +#~ "``example_package`` regardless of what ``name`` you gave " +#~ "your :term:`distribution package ` " +#~ "in :file:`setup.cfg` or :file:`setup.py` (in this case, ``example-package-" +#~ "YOUR-USERNAME-HERE``)." +#~ msgstr "" +#~ "Note que o :term:`pacote de importação ` é " +#~ "``example_package`` independente de qual ``name`` você deu ao " +#~ "seu :term:`pacote de distribuição ` " +#~ "no :file:`setup.cfg` ou :file:`setup.py` (neste caso, ``example-package-" +#~ "YOUR-USERNAME-HERE``)." + +#~ msgid "" +#~ "Read more about using :ref:`setuptools` to package libraries in :doc:`/" +#~ "guides/distributing-packages-using-setuptools`." +#~ msgstr "" +#~ "Leia mais sobre como usar :ref:`setuptools` para empacotar bibliotecas " +#~ "em :doc:`/guides/distributing-packages-using-setuptools`." + +#~ msgid "" +#~ "Consider alternatives to :ref:`setuptools` such " +#~ "as :ref:`flit`, :ref:`hatch`, and :ref:`poetry`." +#~ msgstr "" +#~ "Considere alternativas ao :ref:`setuptools`, tal " +#~ "como :ref:`flit`, :ref:`hatch` e :ref:`poetry`." + +#~ msgid "" +#~ "Some legacy Python environments may not have ``setuptools`` pre-" +#~ "installed, and the operators of those environments may still be requiring " +#~ "users to install packages by running ``setup.py install`` commands, " +#~ "rather than providing an installer like ``pip`` that automatically " +#~ "installs required build dependendencies. These environments will not be " +#~ "able to use many published packages until the environment is updated to " +#~ "provide an up to date Python package installation client (e.g. by running " +#~ "``python -m ensurepip``)." +#~ msgstr "" +#~ "Alguns ambientes Python legados podem não ter o ``setuptools`` pré-" +#~ "instalado, e os operadores desses ambientes ainda podem exigir que os " +#~ "usuários instalem pacotes executando comandos ``setup.py install``, em " +#~ "vez de fornecer um instalador como o ``pip`` que instala automaticamente " +#~ "as dependências de compilação necessárias. Esses ambientes não serão " +#~ "capazes de usar muitos pacotes publicados até que o ambiente seja " +#~ "atualizado para fornecer um cliente de instalação de pacote Python " +#~ "atualizado (por exemplo, executando ``python -m ensurepip``)." + +#~ msgid "" +#~ "Use :ref:`pipenv` to manage library dependencies when developing Python " +#~ "applications. See :doc:`../tutorials/managing-dependencies` for more " +#~ "details on using ``pipenv``." +#~ msgstr "" +#~ "Use :ref:`pipenv` para gerenciar as dependências da biblioteca ao " +#~ "desenvolver aplicações Python. Veja :doc:`../tutorials/managing-" +#~ "dependencies` para mais detalhes sobre como usar o ``pip env``." + +#~ msgid "" +#~ "When ``pipenv`` does not meet your use case, consider other tools like:" +#~ msgstr "" +#~ "Quando ``pipenv`` não atende ao seu caso de uso, considere outras " +#~ "ferramentas como:" + +#~ msgid "`pip-tools `_" +#~ msgstr "`pip-tools `_" + +#~ msgid "`Poetry `_" +#~ msgstr "`Poetry `_" + +#, fuzzy +#~ msgid "" +#~ "https://self-issued.info/docs/draft-ietf-jose-json-web-signature.html" +#~ msgstr "" +#~ "http://self-issued.info/docs/draft-ietf-jose-json-web-signature.html" + +#, fuzzy +#~ msgid "https://self-issued.info/docs/draft-ietf-jose-json-web-key.html" +#~ msgstr "http://self-issued.info/docs/draft-ietf-jose-json-web-key.html" + +#~ msgid "" +#~ "Developers of Python libraries, or of applications that support " +#~ "distribution as Python libraries, should also consider the `poetry " +#~ "`_ project as an alternative " +#~ "dependency management solution." +#~ msgstr "" +#~ "Desenvolvedores de bibliotecas Python, ou de aplicações que oferece " +#~ "suporte a distribuição como bibliotecas Python, também devem considerar o " +#~ "projeto `poetry `_ como uma " +#~ "solução alternativa de gerenciamento de dependências." + +#~ msgid "" +#~ "`pip-tools `_ to build your own " +#~ "custom workflow from lower level pieces like ``pip-compile`` and ``pip-" +#~ "sync``" +#~ msgstr "" +#~ "`pip-tools `_ para construir seu " +#~ "próprio fluxo de trabalho personalizado a partir de peças de nível " +#~ "inferior como ``pip-compile`` e ``pip-sync``" + +#~ msgid "" +#~ "`Docs `__ | `Issues `__ | `PyPI `__" +#~ msgstr "" +#~ "`Documentação `__ | `Issues " +#~ "`__ | `PyPI `__" + +#~ msgid "" +#~ "Flit provides a simple way to 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 "" +#~ "O Flit fornece uma maneira simples de enviar pacotes e módulos puro " +#~ "Python para o PyPI. Ele se concentra em `facilitar as coisas fáceis `_ para empacotar. O Flit pode gerar um arquivo de " +#~ "configuração para configurar rapidamente um projeto simples, construir " +#~ "distribuições fonte e wheels e enviá-los para PyPI." + +#~ msgid "2014-11-11" +#~ msgstr "2014-11-11" + +#~ msgid "" +#~ "For an example, see the `MANIFEST.in `_ from the `PyPA sample project " +#~ "`_." +#~ msgstr "" +#~ "Para obter um exemplo, consulte o `MANIFEST.in `_ do `projeto de exemplo PyPA " +#~ "`_." + +#~ msgid "description" +#~ msgstr "description" + +#~ msgid "license" +#~ msgstr "license" + +#~ msgid "keywords" +#~ msgstr "keywords" + +#~ msgid "" +#~ "Although not required, it's common to locally install your project in " +#~ "\"editable\" or \"develop\" mode while you're working on it. This allows " +#~ "your project to be both installed and editable in project form." +#~ msgstr "" +#~ "Embora não seja obrigatório, é comum instalar localmente seu projeto no " +#~ "modo \"editável\" ou \"desenvolvimento\" enquanto você trabalha nele. " +#~ "Isso permite que seu projeto seja instalado e editável na forma de " +#~ "projeto." + +#~ msgid "Assuming you're in the root of your project directory, then run:" +#~ msgstr "" +#~ "Supondo que você esteja na raiz do diretório do seu projeto, execute:" + +#~ msgid "" +#~ "For more information, see the `Development Mode `_ " +#~ "section of the `setuptools docs `_." +#~ msgstr "" +#~ "Para obter mais informações, consulte a seção `Development Mode `_ " +#~ "da `documentação do setuptools `_." + +#~ msgid "2015-09-17" +#~ msgstr "2015-09-17" + +#~ msgid "Fedora 21:" +#~ msgstr "Fedora 21:" + +#~ msgid "Python 3: ``sudo yum install python3 python3-wheel``" +#~ msgstr "Python 3: ``sudo yum install python3 python3-wheel``" + +#~ msgid "Fedora 22:" +#~ msgstr "Fedora 22:" + +#~ msgid "Python 3: ``sudo dnf install python3 python3-wheel``" +#~ msgstr "Python 3: ``sudo dnf install python3 python3-wheel``" + +#~ msgid "" +#~ "To get newer versions of pip, setuptools, and wheel for Python 2, you can " +#~ "enable the `PyPA Copr Repo `_ using the `Copr Repo instructions `__, and then run::" +#~ msgstr "" +#~ "Para obter versões mais novas do pip, setuptools e wheel para Python 2, " +#~ "você pode habilitar o `PyPA Copr Repo `_ usando as `instruções do Copr Repo `__ e então executar::" + +#~ msgid "On EPEL 7 (but not EPEL 6), you can install wheel like so::" +#~ msgstr "" +#~ "No EPEL 7 (mas não no EPEL 6), você pode instalar wheel desta forma::" + +#~ msgid "Python 3::" +#~ msgstr "Python 3::" + +#~ msgid "" +#~ "Python 2.7 used Visual Studio 2008, Python 3.3 and 3.4 used Visual Studio " +#~ "2010, and Python 3.5+ uses Visual Studio 2015 or later. Unfortunately, " +#~ "older versions of Visual Studio are no longer easily available from " +#~ "Microsoft, so for versions of Python prior to 3.5, the compilers must be " +#~ "obtained differently if you do not already have a copy of the relevant " +#~ "version of Visual Studio." +#~ msgstr "" +#~ "Python 2.7 usou Visual Studio 2008, Python 3.3 e 3.4 usou Visual Studio " +#~ "2010 e Python 3.5+ usa Visual Studio 2015 ou posterior. Infelizmente, as " +#~ "versões mais antigas do Visual Studio não estão mais facilmente " +#~ "disponíveis na Microsoft, portanto, para versões do Python anteriores a " +#~ "3.5, os compiladores devem ser obtidos de forma diferente se você ainda " +#~ "não tiver uma cópia da versão relevante do Visual Studio." + +#~ msgid "" +#~ "To set up a build environment for binary extensions, the steps are as " +#~ "follows:" +#~ msgstr "" +#~ "Para configurar um ambiente de construção para extensões binárias, as " +#~ "etapas são as seguintes:" + +#~ msgid "For Python 2.7" +#~ msgstr "Para Python 2.7" + +#~ msgid "" +#~ "Install \"Visual C++ Compiler Package for Python 2.7\", which is " +#~ "available from `Microsoft's website `__." +#~ msgstr "" +#~ "Instale \"Visual C++ Compiler Package for Python 2.7\", que está " +#~ "disponível no `site da Microsoft `__." + +#~ msgid "" +#~ "Use (a recent version of) setuptools in your setup.py (pip will do this " +#~ "for you, in any case)." +#~ msgstr "" +#~ "Use (uma versão recente de) setuptools em seu setup.py (pip fará isso por " +#~ "você, em qualquer caso)." + +#~ msgid "Done." +#~ msgstr "Pronto." + +#~ msgid "For Python 3.4" +#~ msgstr "Para Python 3.4" + +#~ msgid "" +#~ "Install \"Windows SDK for Windows 7 and .NET Framework 4\" (v7.1), which " +#~ "is available from `Microsoft's website `__." +#~ msgstr "" +#~ "Instale \"Windows SDK for Windows 7 and .NET Framework 4\" (v7.1), que " +#~ "está disponível no `site da Microsoft `__." + +#~ msgid "" +#~ "Work from an SDK command prompt (with the environment variables set, and " +#~ "the SDK on PATH)." +#~ msgstr "" +#~ "Trabalhe em um prompt de comando do SDK (com as variáveis de ambiente " +#~ "definidas e o SDK no PATH)." + +#~ msgid "Set DISTUTILS_USE_SDK=1" +#~ msgstr "Defina DISTUTILS_USE_SDK=1" + +#~ msgid "For Python 3.5" +#~ msgstr "Para Python 3.5" + +#~ msgid "" +#~ "Install `Visual Studio 2015 Community Edition `__ " +#~ "(or any later version, when these are released)." +#~ msgstr "" +#~ "Instale `Visual Studio 2015 Community Edition `__ " +#~ "(ou qualquer versão posterior, quando estas tiverem sido lançadas)." + +#~ msgid "" +#~ "Note that from Python 3.5 onwards, Visual Studio works in a backward " +#~ "compatible way, which means that any future version of Visual Studio will " +#~ "be able to build Python extensions for all Python versions from 3.5 " +#~ "onwards." +#~ msgstr "" +#~ "Observe que a partir do Python 3.5 em diante, o Visual Studio funciona de " +#~ "maneira compatível com versões anteriores, o que significa que qualquer " +#~ "versão futura do Visual Studio será capaz de construir extensões Python " +#~ "para todas as versões Python de 3.5 em diante." + +#~ msgid "" +#~ "Building with the recommended compiler on Windows ensures that a " +#~ "compatible C library is used throughout the Python process." +#~ msgstr "" +#~ "Construir com o compilador recomendado no Windows garante que uma " +#~ "biblioteca C compatível seja usada em todo o processo do Python." + +#~ msgid "" +#~ "Use the ``bdist_wheel`` :ref:`setuptools` extension available from " +#~ "the :ref:`wheel project ` to create :term:`wheels `. This " +#~ "is especially beneficial, if your project contains binary extensions." +#~ msgstr "" +#~ "Use a extensão ``bdist_wheel`` :ref:`setuptools` disponível no :ref: " +#~ "`projeto wheel ` para criar :term:`wheels `. Isso é " +#~ "especialmente benéfico se o seu projeto contiver extensões binárias." + +#~ msgid "Add all files matching any of the listed patterns" +#~ msgstr "" +#~ "Adiciona todos os arquivos correspondendo a qualquer um dos padrões " +#~ "listados" + +#~ msgid "bento" +#~ msgstr "bento" + +#~ msgid "" +#~ "`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +#~ msgstr "" +#~ "`Documentação `__ | `Issues `__ | `GitHub `__ | `PyPI `__" + +#~ msgid "" +#~ "Bento is a packaging tool solution for Python software, targeted as an " +#~ "alternative to :ref:`distutils`, :ref:`setuptools`, etc.... Bento's " +#~ "philosophy is reproducibility, extensibility and simplicity (in that " +#~ "order)." +#~ msgstr "" +#~ "Bento é uma solução de ferramenta de empacotamento para software Python, " +#~ "direcionada como uma alternativa ao :ref:`distutils`, :ref:`setuptools `, " +#~ "etc. A filosofia do Bento é reprodutibilidade, extensibilidade e " +#~ "simplicidade (nesta ordem)." + +#~ msgid "`Docs `__" +#~ msgstr "`Documentação `__" + +#~ msgid "`Enthought Canopy `_" +#~ msgstr "`Enthought Canopy `_" + +#~ msgid "" +#~ "`bbFreeze `_ - Windows, Linux, Python " +#~ "2 only" +#~ msgstr "" +#~ "`bbFreeze `_ - Windows, Linux, Python " +#~ "2 apenas" + +#~ msgid "" +#~ "RFC 822 Long Header Fields: http://www.freesoft.org/CIE/RFC/822/7.htm" +#~ msgstr "" +#~ "\"Long Header Fields\" do RFC 822: http://www.freesoft.org/CIE/RFC/" +#~ "822/7.htm" + +#~ msgid "Using `venv`_:" +#~ msgstr "Usando `venv`_:" + +#~ msgid "" +#~ "If present, it MUST contain at least two fields. The first one is " +#~ "``url``, with type ``string``. Depending on what ``url`` refers to, the " +#~ "second field MUST be one of ``vcs_info`` (if ``url`` is a VCS reference), " +#~ "``archive_info`` (if ``url`` is a source archives or a wheel), or " +#~ "``dir_info`` (if ``url`` is a local directory). These info fields have a " +#~ "(possibly empty) subdictionary as value, with the possible keys defined " +#~ "below." +#~ msgstr "" +#~ "Se presente, DEVE conter pelo menos dois campos. O primeiro é ``url``, " +#~ "com tipo ``string``. Dependendo de qual ``url`` se refere, o segundo " +#~ "campo DEVE ser um de ``vcs_info`` (se ``url`` é uma referência de VCS), " +#~ "``archive_info`` (se ``url`` é um arquivo de código-fonte ou um wheel) ou " +#~ "``dir_info`` (se ``url`` é um diretório local). Estes campos " +#~ "informacionais têm um subdicionário (possivelmente vazio) como valor, com " +#~ "as chaves possíveis definidas abaixo." + +#~ msgid "" +#~ "``url`` MUST be stripped of any sensitive authentication information, for " +#~ "security reasons." +#~ msgstr "" +#~ "``url`` DEVE ser podado a fim de retirar qualquer informação de " +#~ "autenticação sensível, por razões de segurança." + +#~ msgid "" +#~ "A ``commit_id`` key (type ``string``) MUST be present, containing the " +#~ "exact commit/revision number that was installed. If the VCS supports " +#~ "commit-hash based revision identifiers, such commit-hash MUST be used as " +#~ "``commit_id`` in order to reference the immutable version of the source " +#~ "code that was installed." +#~ msgstr "" +#~ "Uma chave ``commit_id`` (tipo ``string``) DEVE estar presente, contendo o " +#~ "número exato de commit/revisão que foi instalado. Se o VCS oferecer " +#~ "suporte a identificadores de revisão baseados em hash de commit, tal hash " +#~ "de commit DEVE ser usado como ``commit_id`` para referenciar a versão " +#~ "imutável do código-fonte que foi instalado." + +#~ msgid "" +#~ "``editable`` (type: ``boolean``): ``true`` if the distribution was " +#~ "installed in editable mode, ``false`` otherwise. If absent, default to " +#~ "``false``." +#~ msgstr "" +#~ "``editable`` (tipo: ``boolean``): ``true`` se a distribuição foi " +#~ "instalada em modo editável, ``false`` caso contrário. Se ausente, é usado " +#~ "o padrão ``false``." + +#~ msgid "" +#~ "When ``url`` refers to a local directory, it MUST have the ``file`` sheme " +#~ "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 "" +#~ "Quando ``url`` se refere a um diretório local, ele DEVE ter o esquema " +#~ "``file`` e ser compatível com :rfc:`8089` Em particular, o componente do " +#~ "caminho deve ser absoluto. Links simbólicos DEVERIAM ser preservados ao " +#~ "tornar os caminhos relativos absolutos." + +#~ msgid "" +#~ "Installers 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 "" +#~ "Os instaladores podem usar os comandos ``git show-ref`` e ``git symbolic-" +#~ "ref`` para determinar se o ``required_revision`` corresponde a um ref " +#~ "Git. Por sua vez, um ref começando com ``refs/tags/`` corresponde a uma " +#~ "tag, e um ref começando com ``refs/remotes/origin/`` após a clonagem " +#~ "corresponde a um branch." + +#~ msgid "Local directory installed in editable mode:" +#~ msgstr "Diretório local instalado em modo editável:" + +#~ msgid "" +#~ "January 2023: Added the ``archive_info.hashes`` key (`discussion `__)." +#~ msgstr "" +#~ "Janeiro de 2023: Adicionada a chave ``archive_info.hashes`` (`discussão " +#~ "`__)." + +#~ 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. Dynamic metadata is listed via the " +#~ "``dynamic`` key (defined later in this specification) and represents " +#~ "metadata that a tool will later provide." +#~ msgstr "" +#~ "Existem dois tipos de metadados: *estáticos* e *dinâmicos*. Metadados " +#~ "estáticos são especificados diretamente no arquivo ``pyproject.toml`` e " +#~ "não podem ser especificados ou alterados por uma ferramenta. Os metadados " +#~ "dinâmicos são listados por meio da chave ``dynamic`` (definido " +#~ "posteriormente nesta especificação) e representam os metadados que uma " +#~ "ferramenta fornecerá posteriormente." diff --git a/locales/ro/LC_MESSAGES/messages.po b/locales/ro/LC_MESSAGES/messages.po new file mode 100644 index 000000000..93288efa2 --- /dev/null +++ b/locales/ro/LC_MESSAGES/messages.po @@ -0,0 +1,26797 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# GUILHERME FERNANDES NETO , 2021. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: 2021-08-20 01:32+0000\n" +"Last-Translator: GUILHERME FERNANDES NETO \n" +"Language-Team: Romanian \n" +"Language: ro\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=n==1 ? 0 : (n==0 || (n%100 > 0 && n%100 < " +"20)) ? 1 : 2;\n" +"X-Generator: Weblate 4.8-dev\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "" + +#: ../source/contribute.rst:14 +msgid "Translating the guide" +msgstr "" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "" + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "" + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "" + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "" + +#: ../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 +msgid "What is a source distribution?" +msgstr "" + +#: ../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 +msgid "What about eggs?" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python setup.py install``" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python -m pip install --editable .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:104 +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr "" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +msgid "Complete" +msgstr "" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +msgid "Versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +msgid "Calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +msgid "Other schemes" +msgstr "" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 ../source/flow.rst:143 +msgid "" +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../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 :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +msgid "Installed Project" +msgstr "" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "Pe Indexul Proiectului" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +msgid "Project Root Directory" +msgstr "" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "Modul Pur" + +#: ../source/glossary.rst:257 +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:260 +msgid "Pyproject Metadata" +msgstr "" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +msgid "Pyproject Metadata Key" +msgstr "" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "Specificator Cerință" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "" + +#: ../source/glossary.rst:344 +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:348 +msgid "Root License Directory" +msgstr "" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +#, fuzzy +#| msgid "Per Project Index" +msgid "Wheel Project" +msgstr "Pe Indexul Proiectului" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "" +"https://files.pythonhosted.org/packages/eb/" +"45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" +"sampleproject-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "" +"https://files.pythonhosted.org/packages/56/0a/" +"178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" +"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +msgid "" +"https://files.pythonhosted.org/packages/" +"63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" +"sampleproject_nomura-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +msgid "Creating the package" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +msgid "``pyproject.toml``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +msgid "Installing the package with ``pipx``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +msgid "Conclusion" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +msgid "1. Install twine" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +msgid "Dropping a Python version" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:108 +msgid "openSUSE" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:118 +msgid "Debian/Ubuntu and derivatives" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +msgid "Install packages in a virtual environment using pip and venv" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +msgid "Install packages using pip" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +msgid "Install extras" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +#, fuzzy +#| msgid "Requirement Specifier" +msgid "Using a requirements file" +msgstr "Specificator Cerință" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +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/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python -m build``" +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:126 +msgid "``python -m build --no-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:127 +msgid "``python -m pip install --no-build-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../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 "" +"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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +msgid "Installation" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:233 +msgid "``appveyor-sample/build.cmd``" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:5 +msgid "Tool recommendations" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +msgid "Installing packages" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +msgid "Building distributions" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:313 +msgid "setuptools" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:317 +msgid "uv-build" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +msgid "`Kivy `_" +msgstr "" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "Subdirectory name" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +msgid "``licenses``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*object*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Schema version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "examples" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "version\\_info" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*number*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**implementation**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**flags**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**headers**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +msgid "Package Building" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +msgid ":ref:`Version `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +msgid "``toml``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +msgid "``dependency_groups``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +msgid "Installers" +msgstr "" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +msgid "Reference implementation in Python" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +msgid "Names and normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +msgid "Name normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +msgid "Project Status Markers" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +msgid "Installer semantics: none." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +msgid "Installer semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +msgid "``deprecated``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +msgid "``pylock.toml`` Specification" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +msgid "``lock-version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +msgid "**Required?**: yes" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +msgid "``environments``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +msgid "``dependency-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +msgid "``[[packages]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +msgid "``packages.version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +msgid "The version of the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +msgid "``[[packages.dependencies]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +msgid "The time the file was uploaded." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +msgid "``packages.index``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +msgid "``import-names``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +msgid "Legacy specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +msgid "Examples:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +msgid "Example:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +msgid "PyPA schemas" +msgstr "" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +msgid "Python Description Formats" +msgstr "" + +#: ../source/specifications/section-reproducible-environments.rst:3 +msgid "Reproducible Environments" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +msgid "Normalized Names" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +msgid "HTML Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +msgid "Project List" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +msgid "Project Detail" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +msgid "JSON Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +msgid "Content-Types" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +msgid "Version + Format Selection" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +msgid "Definitions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +msgid "Version scheme" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +msgid "Pre-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +msgid "Version epochs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +msgid "Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +msgid "Integer Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +msgid "Version exclusion" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +msgid "Well-known Project URLs in Metadata" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +msgid "Label normalization" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +msgid "Normalized" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"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/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "" + +#: ../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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "" + +#: ../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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" diff --git a/locales/ru/LC_MESSAGES/messages.po b/locales/ru/LC_MESSAGES/messages.po new file mode 100644 index 000000000..c74a06140 --- /dev/null +++ b/locales/ru/LC_MESSAGES/messages.po @@ -0,0 +1,37565 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# Mingun , 2021. +# Vita Markova , 2021, 2022. +# МАН69К , 2022. +# Vik , 2022. +# Alex , 2023. +# gfbdrgng , 2023, 2024, 2025. +# Andrey Rybakov , 2023. +# Nikita , 2024. +# gfbdrgn , 2025. +# da070116 , 2025. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: 2025-06-07 08:01+0000\n" +"Last-Translator: da070116 \n" +"Language-Team: Russian \n" +"Language: ru\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2);\n" +"X-Generator: Weblate 5.12-dev\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "Внесите вклад в это руководство" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "" +"|PyPUG| приветствует участников! Существует множество способов нам помочь, в " +"том числе:" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "Чтение руководства и предоставление обратной связи" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "Проверка новых вкладов" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "Пересмотр существующего материала" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "Написание нового материала" + +#: ../source/contribute.rst:14 +msgid "Translating the guide" +msgstr "Перевод руководства" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" +"Большая часть работы над |PyPUG| происходит на «проектном хранилище " +"GitHub`__. Чтобы начать, проверьте список `open issues`__ и `pull " +"requests`__. Если вы планируете писать или редактировать руководство, " +"пожалуйста, прочитайте :ref:`style guide `." + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" +"Внося свой вклад в |PyPUG|, вы должны следовать `Нормам поведения `__ PSF." + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "Типы документации" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" +"Этот проект состоит из четырех различных типов документации с конкретными " +"целями. Проект стремится следовать «процессу Diátaxis» для создания " +"качественной документации. При предложении новых дополнений к проекту, " +"пожалуйста, выберите соответствующий тип документации." + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "Учебники" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" +"Учебники нацелены на обучение читателя новым понятиям путем достижения цели. " +"Они представляют собой пошаговые руководства, основанные на мнениях. Они не " +"содержат лишних предупреждений или информации. `Пример документа в стиле " +"учебника`_." + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "Руководства" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" +"Руководства ориентированы на выполнение конкретной задачи и могут " +"предполагать наличие определенного уровня предварительных знаний. Они похожи " +"на учебники, но имеют узкую и четкую направленность и могут содержать много " +"предостережений и дополнительной информации, если это необходимо. В них " +"также может обсуждаться несколько подходов к выполнению задачи. :doc:`пример " +"документа в стиле руководства `." + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "Обсуждения" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" +"Дискуссии нацелены на понимание и получение информации. В них изучается " +"конкретная тема без определенной цели. :doc:`пример документа в стиле " +"дискуссии `." + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "Спецификации" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" +"Спецификации - это справочная документация, сосредоточенная на всестороннем " +"документировании согласованного интерфейса для взаимодействия между " +"упаковочными инструментами. :doc:`example Specification-style document " +"`." + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "Переводы" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" +"Для управления переводами этого проекта мы используем `Weblate`_. " +"Пожалуйста, посетите проект `packaging.python.org`_ на Weblate для участия в " +"переводе." + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" +"Если у вас возникли проблемы во время работы над переводами, откройте вопрос " +"(issue) на `Github`_." + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" +"Любые переводы этого проекта должны соответствовать `reStructuredText " +"syntax`_." + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "Добавление языка" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" +"Если ваш язык не указан на «упаковке». python.org`_, нажмите " +"кнопку :guilabel: «Начните новый перевод» внизу языкового списка и добавьте " +"язык, который вы хотите перевести." + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "После Текстовый синтаксис" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" +"Если вы не знакомы с с синтаксисом reStructuredText (RST), пожалуйста, " +"прочитайте «это руководство» перед переводом на Weblate." + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "**Не переводите текст в ссылке напрямую**" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "При переводе текста ссылки, пожалуйста, не переводите его напрямую." + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "Неправильно: Переведить следующий текст напрямую:" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" +"Правильно: Переведить следующий текст на свой язык и добавить оригинальную " +"ссылку:" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "Локальная сборка руководства" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" +"Хотя это не требуется для внесения вклада, может быть полезно построить это " +"руководство на местном уровне, чтобы проверить ваши изменения. Чтобы " +"построить это руководство на местном уровне, вам нужно:" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" +":doc:`Nox `. Вы можете установить или обновить nox с помощью " +"``pip``:" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" +"Python 3.11. Наши сценарии создания обычно тестируются только с Python 3.11. " +"См. :doc:`Hitchhiker's Guide to Pythoninstall instructions ` для установки Python 3.11 на вашей " +"операционной системе." + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" +"Для сборки руководства выполните следующую команду shell в корневом каталоге " +"проекта:" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" +"После завершения процесса вы можете найти выход HTML в каталоге ``./build/" +"html``. Вы можете открыть файл ``index.html`` для просмотра руководства в " +"веб-браузере, но рекомендуется обслуживать руководство с помощью сервера " +"HTTP." + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" +"Вы можете собрать руководство и обслуживать его через сервер HTTP, используя " +"следующую команду:" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "" +"Руководство будет доступно для просмотра по адресу http://localhost:8000." + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "Где развёрнуто руководство" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" +"Руководство развернуто через ReadTheDocs, и конфигурация живет на https://" +"readthedocs.org/projects/python-packaging-user-guide/. Он подается из " +"пользовательского домена и перед ним Fast.ly." + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "Стиль руководство" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" +"Это руководство по стилю имеет рекомендации о том, как вы должны писать |" +"PyPUG|. Прежде чем начать писать, пожалуйста, просмотрите его. Следуя " +"руководству по стилю, ваш вклад поможет добавить в единое целое и облегчит " +"принятие вашего вклада в проект." + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "Цель" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" +"Цель |PyPUG| - быть авторитетным ресурсом о том, как упаковать, опубликовать " +"и установить Python проекты с использованием современных инструментов." + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "Область действия" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" +"Руководство предназначено для ответа на вопросы и решения проблем с помощью " +"точных и целенаправленных рекомендаций." + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" +"Руководство не должно быть всеобъемлющим, и оно не предназначено для замены " +"документации отдельных проектов. Например, pip имеет десятки команд, опций и " +"настроек. Документация pip описывает каждую из них в деталях, в то время как " +"в этом руководстве описываются только те части pip, которые необходимы для " +"выполнения конкретных задач, описанных в настоящем руководстве." + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "Аудитория" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "Аудитория этого руководства - любой, кто использует Python с пакетами." + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" +"Не забывайте, что сообщество Python является большим и приветственным. " +"Читатели могут не делить свой возраст, пол, образование, культуру и многое " +"другое, но они заслуживают того, чтобы узнать о упаковке так же, как и вы." + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" +"В частности, имейте в виду, что не все люди, которые используют Python, " +"считают себя программистами. Аудитория этого руководства включает в себя " +"астрономов или художников или студентов, а также профессиональных " +"разработчиков программного обеспечения." + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "Голос и тон" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" +"При написании этого руководства старайтесь писать голосом, который подходит " +"и скромен, даже если у вас есть все ответы." + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" +"Представьте, что вы работаете над проектом Python с кем-то, кого вы знаете, " +"чтобы быть умным и квалифицированным. Вам нравится работать с ними, и им " +"нравится работать с вами. Этот человек задал вам вопрос, и вы знаете ответ. " +"Как ты реагируешь? * Вот как вы должны написать это руководство." + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" +"Вот быстрая проверка: попробуйте читать вслух, чтобы понять голос и тон " +"вашего письма. Это звучит как что-то, что вы скажете или звучит так, будто " +"вы играете роль или произносите речь? Почувствуйте себя свободно в " +"использовании схваток и не волнуйтесь о том, чтобы придерживаться безумных " +"правил грамматики. Настоящим вам предоставляется разрешение на завершение " +"предложения в предположении, если это то, с чем вы хотите покончить." + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" +"При написании руководства корректируйте свой тон на серьезность и сложность " +"темы. Если вы пишете вводный учебник, это нормально, чтобы шутить, но если " +"вы покрываете чувствительные рекомендации по безопасности, вы можете " +"избежать шуток в целом." + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "Соглашения и механики" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "**Пишите читателю**" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" +"Давая рекомендации или расписывая шаги, обращайтесь к читателю на *вы* или " +"используйте повелительное наклонение." + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "Неправильно: Чтобы установить его, пользователь запускает…" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "Правильно: Вы можете установить его, запустив…" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "Правильно: Чтобы установить его, запустите…" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "**Государственные предположения**" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" +"Избегайте делать негласные предположения. Чтение в Интернете означает, что " +"любая страница руководства может быть первой страницей руководства, которое " +"читатель когда-либо видел. Если вы собираетесь делать предположения, то " +"скажите, какие предположения вы собираетесь делать." + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "**Кросс-ссылки щедро**" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" +"В первый раз, когда вы упоминаете инструмент или практику, обратитесь к той " +"части руководства, которая его охватывает, или обратитесь к соответствующему " +"документу в другом месте. Сохраните читателю поиск." + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "**Следуйте правилам именования**" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" +"При указании названий инструментов, сайтов, имён людей и других собственных " +"существительных используйте их предпочтительную капитализацию." + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "Неправильно: Pip использует…" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "Правильно: pip использует…" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "Неправильно: …размещён на github." + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "Правильно: …размещён на GitHub." + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "**Используйте гендерно-нейтральный стиль**" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" +"Часто вы будете обращаться к читателю напрямую с *ты*, *ваш* и *ваш*. В " +"противном случае используйте гендерно-нейтральные местоимения *они *, * их * " +"и * их * или полностью избегайте местоимений." + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "Неправильно: Сопровождающий загружает файл. Затем он…" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "Правильно: Сопровождающий загружает файл. Затем они…" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "Правильно: Сопровождающий загружает файл. Затем сопровождающий…" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "**Заголовки**" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" +"Пишите заголовки, в которых используются слова, которые читатель ищет. " +"Хорошим способом сделать это является то, чтобы ваш заголовок завершал " +"подразумеваемый вопрос. Например, читатель может захотеть узнать *Как " +"установить MyLibrary?*, поэтому хорошим заголовком будет *Установить " +"MyLibrary*." + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" +"В заголовках разделов используйте падеж предложения. Другими словами, пишите " +"заголовки так, как вы бы написали обычное предложение." + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "Неправильно: Всё, Что Вам Нужно Знать О Python'е" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "Правильно: Всё, что вам нужно знать о Python'е" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "**Числа**" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" +"В основном тексте пишите числа от 1 до 9 как слова. Для остальных чисел или " +"чисел в таблицах используйте цифры." + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "Развёртывание приложений на Python'е" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "Статус страницы" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "Незавершено" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "Последняя проверка" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "2021-8-24" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "Обзор" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "Поддержка нескольких аппаратных платформ" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "Упаковка и инсталляторы ОС" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "Windows" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "Pynsist" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" +"`Pynsist `__ - это инструмент, который " +"упаковывает программы на Python вместе с Python-интерпретатором в единый " +"инсталлятор, основанный на NSIS. В большинстве случаев упаковка требует от " +"пользователя только выбора версии Python-интерпретатора и объявления " +"зависимостей программы. Утилита загружает указанный Python-интерпретатор для " +"Windows и упаковывает его вместе со всеми зависимостями в единый Windows-" +"исполняемый инсталлятор." + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" +"Установленная программа может быть запущена из короткого пути, который " +"установщик добавляет к start-menu. Он использует интерпретатор Python, " +"установленный в его каталоге приложений, независимо от любой другой " +"установки Python на компьютере." + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" +"Большим преимуществом Pynsist является то, что пакеты Windows могут быть " +"построены на Linux. Существует несколько примеров для различных видов " +"программ (консоль, GUI) в :any:`documentation `. Инструмент " +"выпущен под лицензией MIT." + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "Комплекты приложений" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" +"`__ Это расширение отключения, которое " +"позволяет создавать автономные Windows исполняемые программы (32-битные и 64-" +"битные) от Python. Python версии, включенные в официальный цикл разработки, " +"поддерживаются (относится к `Status of Python branches`__). py2exe может " +"создавать исполняемые консоли и исполняемые окна (GUI). Сервисы по " +"строительству окон и серверы DLL/EXE COM могут работать, но они не " +"поддерживаются активно. Расширение Distutils выпущено под лицензией MIT и " +"публичной лицензией Mozilla 2.0." + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" +"`py2app `__ - это команда Python " +"setuptools, которая позволит вам создавать автономные пакеты приложений и " +"плагинов для macOS из скриптов Python. Обратите внимание, что py2app ДОЛЖЕН " +"использоваться на macOS для создания приложений, он не может создавать Mac-" +"приложения на других платформах. py2app выпускается под MIT-лицензией." + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "Unix (включая Linux и macOS)" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "pex" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" +"pex `__ - это библиотека для создания " +"файлов .pex (Python EXecutable), которые являются исполняемыми окружениями " +"Python в духе virtualenvs. pex является расширением идей, изложенных " +"в :pep:`441`, и делает развертывание приложений Python таким же простым, как " +"cp. Файлы pex могут даже включать несколько дистрибутивов Python, " +"специфичных для конкретной платформы, что означает, что один файл pex может " +"быть переносимым в Linux и macOS. pex выпущен в соответствии с Apache " +"License 2.0." + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "Управление конфигурацией" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "Пакет распределения против пакета импорта" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" +"Словом \"пакет\" обычно обозначают несколько различных понятий. Эта страница " +"объясняет различия между двумя разными, но связанными значениями в упаковке " +"Python, \"дистрибутивный пакет\" и \"пакет импорта\"." + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "Что такое дистрибутивный пакет?" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" +"Дистрибутив - это часть программного обеспечения, которую вы можете " +"установить. В большинстве случаев это синоним слова \"проект\". Когда вы " +"набираете ``pip install pkg``, или когда вы пишете ``dependencies = " +"[\"pkg\"]`` в вашем ``pyproject.toml``, ``pkg`` - это имя дистрибутивного " +"пакета. Когда вы ищете или просматриваете PyPI_, наиболее известный " +"централизованный источник для установки библиотек и инструментов Python, вы " +"видите список дистрибутивных пакетов. Кроме того, термин \"дистрибутивный " +"пакет\" может использоваться для обозначения конкретного файла, содержащего " +"определенную версию проекта." + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" +"Обратите внимание, что в мире Linux \"дистрибутивный пакет\", чаще всего " +"сокращаемый как \"дистропакет\" или просто \"пакет\", - это нечто, " +"предоставляемое системным менеджером пакетов дистрибутива `_, что " +"имеет другое значение." + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "Что такое пакет импорта?" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" +"Импортный пакет - это модуль Python. Таким образом, когда вы пишете ``import " +"pkg`` или ``from pkg import func`` в вашем коде Python, ``pkg`` - это имя " +"пакета импорта. Точнее, импортные пакеты - это специальные модули Python, " +"которые могут содержать подмодули. Например, пакет ``numpy`` содержит такие " +"модули, как ``numpy.linalg`` и ``numpy.fft``. Обычно пакет импорта " +"представляет собой каталог в файловой системе, содержащий модули в виде " +"файлов ``.py`` и подпакеты в виде подкаталогов." + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" +"Вы можете использовать пакет импорта, как только установите дистрибутив, " +"который его предоставляет." + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "Какие связи существуют между дистрибутивными и импортными пакетами?" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" +"Чаще всего дистрибутив предоставляет один единственный импортный пакет (или " +"непакетный модуль) с соответствующим именем. Например, ``pip install numpy`` " +"позволяет вам ``импортировать numpy``." + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" +"Однако это лишь условность. PyPI и другие указатели пакетов *не обеспечивают " +"никакой связи* между именем дистрибутивного пакета и пакетами импорта, " +"которые он предоставляет. (Следствием этого является то, что вы не можете " +"вслепую установить пакет PyPI ``foo``, если вы видите ``import foo``; это " +"может привести к установке непреднамеренного и потенциально даже " +"вредоносного пакета)" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" +"Дистрибутив может предоставлять пакет импорта с другим именем. Примером " +"может служить популярная библиотека Pillow_ для обработки изображений. Имя " +"ее дистрибутивного пакета - ``Pillow``, но она предоставляет пакет импорта " +"``PIL``. Это объясняется историческими причинами: Pillow начиналась как форк " +"библиотеки PIL, поэтому она сохранила имя импорта ``PIL``, чтобы " +"существующие пользователи PIL могли перейти на Pillow без особых усилий. В " +"целом, форк существующей библиотеки - это распространенная причина различия " +"имен в дистрибутивном и импортном пакетах." + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" +"В определенном индексе пакетов (например, в PyPI) имена дистрибутивных " +"пакетов должны быть уникальными. С другой стороны, импортные пакеты не имеют " +"такого требования. Импортные пакеты с одним и тем же именем могут " +"предоставляться несколькими дистрибутивными пакетами. Опять же, частой " +"причиной этого являются форки." + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" +"И наоборот, дистрибутивный пакет может предоставлять несколько пакетов " +"импорта, хотя это встречается реже. Примером может служить дистрибутивный " +"пакет attrs_, который предоставляет как пакет импорта ``attrs`` с более " +"новым API, так и пакет импорта ``attr`` со старым, но поддерживаемым API." + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "Как соотносятся имена дистрибутивных и импортных пакетов?" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" +"Импортируемые пакеты должны иметь в качестве имени корректные идентификаторы " +"Python (точные правила ` можно найти в документации " +"Python) [#non-identifier-mod-name]_. В частности, они используют " +"подчеркивание ``_`` в качестве разделителя слов и чувствительны к регистру." + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" +"С другой стороны, распределительные пакеты могут использовать дефисы ``-`` " +"или подчеркивает ``_``. Они также могут содержать точки ``.``, которые " +"иногда используются для упаковки подпаковки :ref:`namespace package " +"`. Для большинства целей они нечувствительны к " +"делу и к ``-`` против ``_`` различий, например, ``pip установить " +"Awesome_Package`` - это то же самое, что ``pip установить потрясающий " +"пакет`` (точные правила даны в :ref:`name normalization Спецификация `)." + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" +"Хотя технически возможно импортировать пакеты/модули, не имеющие в качестве " +"имени действительного идентификатора Python, используя :doc:`importlib " +"`, это происходит крайне редко и настоятельно не " +"рекомендуется." + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "Поддержка последующей упаковки" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "Черновик" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "2025-?" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" +"Хотя PyPI и инструменты для упаковки Python, такие как :ref:`pip`, являются " +"основными средствами распространения пакетов Python, они также часто " +"становятся доступными в рамках других экосистем упаковки. Эти усилия по " +"переупаковке в совокупности называются *downstream* упаковкой (ваши " +"собственные усилия называются *upstream* упаковкой), и включают такие " +"проекты, как дистрибутивы Linux, Conda, Homebrew и MacPorts. Как правило, " +"они направлены на улучшение поддержки тех случаев, которые не могут быть " +"решены только средствами упаковки Python, например, интеграция с конкретной " +"операционной системой или обеспечение совместимости с определенными версиями " +"программ, не относящихся к Python." + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" +"В этом обсуждении мы попытаемся объяснить, как обычно выполняется " +"последующая упаковка, и с какими дополнительными проблемами обычно " +"сталкиваются разработчики последующей упаковки. Цель обсуждения - " +"предоставить некоторые необязательные рекомендации, которым могут следовать " +"сопровождающие проекта, чтобы облегчить *значительно* процесс последующей " +"упаковки (не налагая при этом никаких серьезных проблем с обслуживанием на " +"upstream-проект). Обратите внимание, что это не предложение \"все или " +"ничего\" - все, что могут сделать сопровождающие upstream, будет полезно, " +"даже если это лишь малая часть. Нисходящие сопровождающие также готовы " +"подготовить патчи для решения этих проблем. Слияние этих патчей может быть " +"очень полезным, так как это избавит разные нисходящие потоки от " +"необходимости нести и постоянно переиздавать одни и те же патчи, а также от " +"риска применения непоследовательных решений одной и той же проблемы." + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" +"Установление хороших отношений между разработчиками программного обеспечения " +"и разработчиками пакетов может принести взаимную выгоду. Поставщики часто " +"готовы поделиться своим опытом, временем и оборудованием для улучшения " +"вашего пакета. Иногда они лучше видят, как ваш пакет используется на " +"практике, и могут предоставить информацию о его связях с другими пакетами, " +"получение которой в противном случае потребовало бы значительных усилий. " +"Упаковщики часто могут найти ошибки до того, как ваши пользователи начнут их " +"использовать в производстве, предоставляют отчеты об ошибках хорошего " +"качества и поставляют исправления, когда это возможно. Например, они " +"регулярно следят за тем, чтобы пакеты, которые они распространяют, " +"обновлялись для решения проблем совместимости, возникающих при выходе новой " +"версии Python." + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" +"Обратите внимание, что последующие сборки включают в себя не только " +"распространение бинарных файлов, но и сборки исходного кода на " +"пользовательских системах (в дистрибутивах с исходным кодом, таких как " +"Gentoo Linux, например)." + +#: ../source/discussions/downstream-packaging.rst:51 +#, fuzzy +#| msgid "Python source distributions" +msgid "Provide complete source distributions" +msgstr "Дистрибутивы с исходным кодом Python" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "Почему?" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +#, fuzzy +#| msgid "Declaring build system dependencies" +msgid "Support building against system dependencies" +msgstr "Объявление зависимостей системы сборки" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +#, fuzzy +#| msgid "Final releases" +msgid "Aim for stable releases" +msgstr "Финальные релизы" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" +"**Дискуссии** направлены на предоставление исчерпывающей информации по " +"определенной теме. Если вы просто хотите сделать что-то, смотрите :doc:`/" +"guides/index`." + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "Файл :file:`install_requires` против файла :file:`requirements`" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "install_requires" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" +"``install_requires`` - это ключевое " +"слово :ref:`setuptools` :file:`setup.py`, которое должно использоваться для " +"указания того, что проекту **минимально** необходимо для корректной работы. " +"Когда проект устанавливается с помощью :ref:`pip`, это спецификация, которая " +"используется для установки его зависимостей." + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" +"Например, если проект требует A и B, ваш ``install_requires`` будет " +"выглядеть так:" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" +"Кроме того, лучше всего указать все известные нижние и верхние границы." + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" +"Например, может быть известно, что ваш проект требует по крайней мере v1 'A' " +"и v2 'B', так что это было бы так:" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" +"Также может быть известно, что проект «A» ввел изменение в его v2, которое " +"нарушает совместимость вашего проекта с v2 «A», а затем, поэтому имеет смысл " +"не разрешать v2:" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" +"Не считается лучшей практикой использовать ``install_requires`` для " +"определения зависимостей к конкретным версиям или для указания " +"подзависимости (т.е. зависимости от ваших зависимостей). Это чрезмерно " +"ограничено и не позволяет пользователю получать выгоду от обновления " +"зависимости." + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" +"Наконец, важно понимать, что ``install_requires`` - это список " +"\"Абстрактных\" требований, т.е. просто имена и ограничения версий, которые " +"не определяют, откуда будут выполняться зависимости (т.е. из какого индекса " +"или источника). Где (т.е. как они должны быть сделаны \"конкретными\"), " +"определяется во время установки с помощью опций :ref:`pip`. [1]_" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "Файлы требований" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" +":ref:`Requirements Files `, описанный проще всего, - " +"это всего лишь список :ref:`pip:pip install` аргументов, помещенных в файл." + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" +"В то время как ``install_requires`` определяет зависимости для одного " +"проекта, :ref:`Requirements Files ` часто " +"используются для определения требований для полной Python среды." + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" +"В то время как требования ``install_requires`` являются минимальными, файлы " +"требований часто содержат исчерпывающий список пинированных версий для " +"достижения :ref:`repeatable installations ` полной среды." + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" +"В то время как ``install_requires`` требования являются \"Abstract\", т.е. " +"не связаны с каким-либо конкретным индексом, файлы требований часто содержат " +"pip опции, такие как ``--index-url`` или ``--find-links``, чтобы сделать " +"требования \"Concrete\", т.е. связанные с конкретным индексом или каталогом " +"пакетов. [1]_" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" +"В то время как метаданные ``install_requires`` автоматически анализируются " +"pip во время установки, файлы требований не являются и используются только " +"тогда, когда пользователь специально устанавливает их с помощью ``python -m " +"pip install -r``." + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" +"Подробнее о требованиях \"Абстрактные\" и \"Конкретные\" см. на сайте " +"https://caremad.io/posts/2013/07/setup-vs-requirement/." + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "Форматы пакетов" + +#: ../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 "" +"На этой странице обсуждаются форматы файлов, которые используются для " +"распространения пакетов Python, и различия между ними." + +#: ../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 "" +"На индексах пакетов, таких как PyPI_, вы найдете файлы в двух форматах: " +"**исходные дистрибутивы**, или сокращенно **sdists**, и **бинарные " +"дистрибутивы**, обычно называемые **wheels**. Например, `PyPI-страница для " +"pip 23.3.1 `_ позволяет вам скачать два файла, " +"``pip-23.3.1.tar.gz`` и ``pip-23.3.1-py3-none-any.whl``. Первый " +"представляет собой sdist, второй - wheel. Как объясняется ниже, они служат " +"для разных целей. Публикуя пакет на PyPI (или где-либо еще), вы всегда " +"должны загружать как sdist, так и один или несколько wheel." + +#: ../source/discussions/package-formats.rst:21 +msgid "What is a source distribution?" +msgstr "Что такое исходный дистрибутив?" + +#: ../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 "" +"Концептуально, дистрибутив исходного кода - это архив с исходным кодом в " +"сыром виде. Конкретно, sdist - это архив ``.tar.gz``, содержащий исходный " +"код плюс дополнительный специальный файл ``PKG-INFO``, который содержит " +"метаданные проекта. Наличие этого файла помогает инструментам упаковки быть " +"более эффективными, поскольку им не нужно самим вычислять метаданные. Файл " +"``PKG-INFO`` имеет формат, указанный в :ref:`core-metadata`` и не " +"предназначен для написания вручную [#core-metadata-format]_." + +#: ../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 "" +"Таким образом, вы можете проверить содержимое sdist, распаковав его с " +"помощью стандартных инструментов для работы с tar-архивами, таких как ``tar " +"-xvf`` на платформах UNIX (например, Linux и macOS), или :ref:``интерфейс " +"командной строки модуля Python's tarfile ` на " +"любой платформе." + +#: ../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 "" +"Sdists служат нескольким целям в экосистеме упаковки. Когда :ref:`pip`, " +"стандартная программа установки пакетов Python, не может найти колесо для " +"установки, она прибегает к загрузке исходного дистрибутива, компиляции " +"колеса из него и установке колеса. Кроме того, sdists часто используются в " +"качестве источника пакетов последующими упаковщиками (например, " +"дистрибутивами Linux, Conda, Homebrew и MacPorts для macOS, ...), которые по " +"разным причинам могут предпочесть их, например, извлечению из Git-" +"репозитория." + +#: ../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:`{имя_пакета}-{версия}.tar.gz`, например, ``pip-23.3.1.tar.gz``." + +#: ../source/discussions/package-formats.rst:50 +msgid "" +"If you want technical details on the sdist format, read the :ref:`sdist " +"specification `." +msgstr "" +"Если вам нужны технические подробности о формате sdist, прочитайте " +"спецификацию :ref:`sdist `." + +#: ../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 "" +"Существует большая разница между sdists и wheels для пакетов с : " +"термин:``модули расширения <модуль расширения>`, написанных на компилируемых " +"языках, таких как C, C++ и Rust, которые должны быть скомпилированы в " +"машинный код, зависящий от платформы. Для таких пакетов колеса содержат не " +"исходный код (например, исходные файлы на C), а скомпилированный, " +"исполняемый код (например, файлы ``.so`` в Linux или DLL в Windows)." + +#: ../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 "" +"Более того, хотя для каждой версии проекта существует только один sdist, " +"колес может быть много. Опять же, это наиболее актуально в контексте модулей " +"расширения. Скомпилированный код модуля расширения привязан к операционной " +"системе и архитектуре процессора, а зачастую и к версии интерпретатора " +"Python (если только не используется : ссылка:`Python стабильный ABI `)." + +#: ../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 "" +"Для пакетов чистого Python разница между sdists и wheels менее заметна. " +"Обычно существует одно единственное колесо для всех платформ и версий " +"Python. Python - интерпретируемый язык, которому не нужна опережающая " +"компиляция, поэтому колеса содержат файлы ``.py``, как и sdists." + +#: ../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 "" +"Если вы задаетесь вопросом о файлах байткода ``.pyc``: они не включены в " +"колеса, поскольку их генерация обходится дешево, и их включение без " +"необходимости заставило бы огромное количество пакетов распространять по " +"одному колесу для каждой версии Python вместо одного колеса. Вместо этого " +"такие программы установки, как :ref:`pip`, генерируют их во время установки " +"пакета." + +#: ../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 "" +"Тем не менее, между sdists и wheels все еще есть важные различия, даже для " +"проектов на чистом Python. Колеса должны содержать именно то, что должно " +"быть установлено, и ничего больше. В частности, колеса никогда не должны " +"включать тесты и документацию, в то время как sdists обычно содержат их. " +"Кроме того, формат колеса сложнее, чем sdist. Например, он включает " +"специальный файл ``RECORD``, который перечисляет все файлы в колесе вместе с " +"хэшем их содержимого для проверки целостности загрузки." + +#: ../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 "" +"На первый взгляд, вы можете задаться вопросом, действительно ли колеса нужны " +"для \"простых и базовых\" проектов на чистом Python. Имейте в виду, что из-" +"за гибкости sdist'ов такие программы установки, как pip, не могут " +"устанавливать из sdist'ов напрямую - им нужно сначала собрать колесо, " +"вызвав :term:`build backend`, указанный в sdist'е (build backend может " +"выполнять всевозможные преобразования при создании колеса, например, " +"компилировать расширения C). По этой причине, даже для чисто Python-проекта, " +"вы всегда должны загружать *обои* sdist и wheel в PyPI или другие индексы " +"пакетов. Это значительно ускорит установку для ваших пользователей, так как " +"колесо можно установить напрямую. Включая только те файлы, которые должны " +"быть установлены, колеса также уменьшают объем загружаемых файлов." + +#: ../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 "" +"С технической точки зрения, колесо - это ZIP-архив (в отличие от sdists, " +"которые являются TAR-архивами). Вы можете проверить его содержимое, " +"распаковав его как обычный ZIP-архив, например, с помощью ``unzip`` на UNIX " +"платформах, таких как Linux и macOS, ``Expand-архив`` в Powershell на " +"Windows, или : ссылка:``интерфейс командной строки модуля zipfile в Python " +"`. Это может быть очень полезно для " +"проверки того, что колесо включает все необходимые файлы." + +#: ../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 "" +"Внутри колеса вы найдете файлы пакета, а также дополнительный каталог под " +"названием :samp:`{имя_пакета}-{версия}.dist-info`. Этот каталог содержит " +"различные файлы, включая файл ``METADATA``, который является эквивалентом " +"``PKG-INFO`` в sdists, а также ``RECORD``. Это может быть полезно для того, " +"чтобы убедиться, что в ваших колесах нет недостающих файлов." + +#: ../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 "" +"Имя файла колеса (без учета некоторых редко используемых функций) выглядит " +"так: :samp:`{имя_пакета}-{версия}-{python_tag}-{abi_tag}-" +"{платформа_tag}.whl`. Это соглашение об именовании определяет, с какими " +"платформами и версиями Python совместимо колесо. Например, имя ``pip-23.3.1-" +"py3-none-any.whl`` означает, что:" + +#: ../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 "" +"(``py3``) Это колесо может быть установлено на любую реализацию Python 3, " +"будь то CPython, наиболее широко используемая реализация Python, или " +"альтернативная реализация, например PyPy_;" + +#: ../source/discussions/package-formats.rst:124 +msgid "(``none``) It does not depend on the Python version;" +msgstr "(``нет``) Не зависит от версии Python;" + +#: ../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 "" +"Шаблон ``py3-none-any`` характерен для проектов на чистом Python. Пакеты с " +"модулями расширения обычно поставляют несколько колес с более сложными " +"тегами." + +#: ../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 +msgid "What about eggs?" +msgstr "А как насчет яиц?" + +#: ../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 "" +"\"Egg\" - это старый формат пакетов, который был заменен форматом wheel. " +"Его больше не следует использовать. С августа 2023 года PyPI `отклоняет " +"яичные загрузки `_." + +#: ../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 "" +"Формат яйца был представлен :ref:`setuptools` в 2004 году, а формат колеса " +"был представлен :pep:`427` в 2012 году." + +#: ../source/discussions/package-formats.rst:149 +msgid "" +"Wheel has an :doc:`official standard specification `. Egg did not." +msgstr "" +"У колеса есть : документ:`официальная стандартная спецификация `. У Egg ее нет." + +#: ../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 "" +"Колесо - это : термин:`дистрибутив <дистрибутивный пакет>`, т.е. формат " +"упаковки. [#колесо-импортируемое]_ Egg был одновременно и форматом " +"дистрибутива, и форматом установки во время выполнения (если его оставить " +"запечатанным), и был разработан для импорта." + +#: ../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 "" +"Архивы колеса не содержат файлов ``.pyc``. Поэтому, если дистрибутив " +"содержит только файлы Python (т.е. не содержит скомпилированных расширений) " +"и совместим с Python 2 и 3, то колесо может быть \"универсальным\", " +"подобно :term:`sdist <Источник дистрибутива (или \"sdist\")>`." + +#: ../source/discussions/package-formats.rst:161 +msgid "" +"Wheel uses standard :ref:`.dist-info directories `. Egg used ``.egg-info``." +msgstr "" +"Колесо использует стандартные : ссылка:``.dist-info директории <запись-" +"установленных-пакетов>`. Egg использует ``.egg-info``." + +#: ../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 "" +"Колесо имеет соглашение об именовании файлов `. Один " +"архив колес может указывать на свою совместимость с несколькими версиями и " +"реализациями языка Python, ABI и системными архитектурами." + +#: ../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 "" +"Wheel версионирован. Каждый файл wheel содержит версию спецификации wheel и " +"реализации, в которую он упакован." + +#: ../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 "" +"Wheel внутренне организовано по типу `sysconfig path `_, что " +"облегчает его преобразование в другие форматы." + +#: ../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 "" +"Этот формат основан на электронной почте. Хотя сегодня его вряд ли выберут, " +"соображения обратной совместимости заставляют оставить его в качестве " +"канонического формата. С точки зрения пользователя это практически " +"незаметно, так как метаданные указываются пользователем в виде, понятном " +"бэкенду сборки, обычно ``[ проект]`` в ``pyproject.toml``, и транслируются " +"бэкендом сборки в ``PKG-INFO``." + +#: ../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:`это не поддерживается официально в " +"настоящее время `." + +#: ../source/discussions/pip-vs-easy-install.rst:6 +msgid "pip vs easy_install" +msgstr "pip против easy_install" + +#: ../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 `, теперь `deprecated`_, был выпущен в 2004 " +"как часть :ref:`setuptools`. Он был примечателен в то время для " +"установки :term:`packages ` из :term:`PyPI `Python Индекса пакетов (PyPI)>` с использованием " +"спецификаторов требований и автоматической установки зависимостей." + +#: ../source/discussions/pip-vs-easy-install.rst:14 +#, fuzzy +#| 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." +msgid "" +":ref:`pip` came later in 2008, as an 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:`pip` появился позже в 2008, в качестве альтернативы :ref:`easy_install " +"`, хотя все еще в значительной степени построен " +"на :ref:`setuptools` компонентах. Это было примечательно в то время для *не* " +"установки пакетов как :term:`Eggs ` или от :term:`Eggs ` (но, " +"скорее, просто как «плоские» пакеты от :term:`sdists `), и введение идеи :ref:`Requirements Files " +"`, которая давала пользователям возможность легко " +"реплицировать среды." + +#: ../source/discussions/pip-vs-easy-install.rst:22 +msgid "" +"Here's a breakdown of the important differences between pip and the " +"deprecated easy_install:" +msgstr "Вот разбивка важных различий между pip и обесцененным easy_install:" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "**pip**" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "**easy_install**" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "Установка из :term:`колёс `" + +#: ../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:`Файлы требований `)" + +#: ../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`` и ``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 "Формат инкапсулированного яйца" + +#: ../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 "Да, через :file:`setup.cfg`" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +#, fuzzy +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" +"https://setuptools.readthedocs.io/en/latest/easy_install.html#natural-script-" +"launcher" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "Является ли ``setup.py`` обесцененным?" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "Нет, :термин:`setup.py` и :ref:`setuptools' не амортизируются." + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" +"Setuptools вполне можно использовать в качестве :term:`build backend` для " +"упаковки Python-проектов. А :file:`setup.py` - это правильный " +"конфигурационный файл для :ref:`setuptools`, который, к примеру, написан на " +"Python, а не на *TOML* (подобная практика используется и в других " +"инструментах, таких как *nox* и его конфигурационный " +"файл :file:`noxfile.py`, или *pytest* и :file:`conftest.py`)." + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" +"Однако ``python setup.py`` и использование :file:`setup.py' в качестве " +"инструмента командной строки обесцениваются." + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" +"Это означает, что команды, такие как следующий **MUST NO**, будут " +"выполняться больше:" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +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]_" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" +"Это требует :ref:`build' зависимости. Рекомендуется всегда строить и " +"публиковать как распределение источника, так и колесо проекта, что и делает " +"``python -m build``. При необходимости опции ``-sdist`` и ``--wheel`` могут " +"быть использованы для создания только одного или другого." + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" +"Для установки проекта, основанного на setuptools, обычно выполнялась команда " +"``install`` от :file:``setup.py``, например: ``python setup.py install``. В " +"настоящее время рекомендуется использовать :ref:`pip` напрямую с командой, " +"подобной этой: ``python -m pip install .``. Где точка ``.`` на самом деле " +"является путем к файловой системе, это обозначение пути к текущему каталогу. " +"Действительно, *pip* принимает путь к каталогу дерева исходников проекта в " +"локальной файловой системе в качестве аргумента своей подкоманды " +"``install``. Таким образом, это также будет правильной командой: ``python -m " +"pip install path/to/project``." + +#: ../source/discussions/setup-py-deprecated.rst:65 +msgid "" +"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 "" +"Что касается установки в режиме *develop* aka *editable*, то вместо ``python " +"setup.py develop`` можно использовать опцию ``--editable`` в подкоманде pip " +"*install*: ``python -m pip install --editable .``." + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" +"Один из рекомендуемых, простых и понятных методов сборки :term:`source " +"дистрибутивов ` и :term:`wheels " +"` заключается в использовании инструмента :ref:`build` с командой " +"типа ``python -m build``, которая запускает генерацию обоих форматов " +"дистрибутивов. При необходимости опции ``--sdist`` и ``--wheel`` могут быть " +"использованы для генерации только одного или другого. Обратите внимание, что " +"инструмент сборки должен быть установлен отдельно." + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" +"Команда ``python setup.pyinstall`` была обесценена в setuptools версии " +"*58.3.0*." + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "Как насчет других команд?" + +#: ../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/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "``python setup.py test``" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" +"Рекомендация заключается в использовании тестового бегуна, такого как " +"pytest_." + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" +"``python setup.py check``, ``python setup.py register`` и ``python setup.py " +"upload``" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "Доверенная замена:ref:`twine':" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "``python -m twine check --strict dist/*``" + +#: ../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/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "``python -m twine upload dist/*``" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" +"Не требуется и не поддерживается на:term:`PyPI `. Но может потребоваться и в других :термин:`package index>` " +"(например:ref:`devpi`)." + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "``python setup.py --version``" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" +"Возможное заменяющее решение (среди прочих) - полагаться на setuptools-scm_:" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "``python -m setuptools-scm``" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "Оставшиеся команды" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" +"В настоящем руководстве не предлагаются решения для замены этих команд:" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "``alias``" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "``bdist``" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "``bdist_dumb``" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "``bdist_egg``" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "``bdist_rpm``" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "``build``" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "``build_clib``" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "``build_ext``" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "``build_py``" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "``build_scripts``" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "``clean``" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "``dist_info``" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "**easy_install**" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "``editable_wheel``" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "``egg_info``" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "``install_data``" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "``install_egg_info``" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "``install_headers``" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "``install_lib``" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "``install_scripts``" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "``rotate``" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "``saveopts``" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "``setopt``" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "``upload_docs``" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "Что насчет пользовательских команд?" + +#: ../source/discussions/setup-py-deprecated.rst:158 +msgid "" +"Likewise, custom :file:`setup.py` commands are deprecated. The " +"recommendation is to migrate those custom commands to a task runner tool or " +"any other similar tool. Some examples of such tools are: chuy, make, nox or " +"tox, pydoit, pyinvoke, taskipy, and thx." +msgstr "" +"Аналогично, пользовательские :file:`setup.py' команды депрецируются. " +"Рекомендация состоит в том, чтобы перенести эти пользовательские команды на " +"инструмент для выполнения задач или любой другой аналогичный инструмент. " +"Некоторые примеры таких инструментов: chuy, make, nox или tox, pydoit, " +"pyinvoke, taskipy и thx." + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "Как насчет пользовательских шагов?" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" +"Настроить шаги, которые, например, либо переписать существующие шаги, такие " +"как ``build_py``, ``build_ext`` и ``bdist_wheel`` или добавить новые шаги " +"сборки, не обесцениваются. Они будут автоматически называться, как и " +"ожидалось." + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "Следует ли исключить ``setup.py``?" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" +"Хотя использование :file:`setup.py' в качестве исполняемого скрипта " +"депрецируется, его использование в качестве файла конфигурации для " +"setuptools абсолютно нормально. :file:`setup.py`, вероятно, не требуется " +"никаких изменений." + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "Является ли ``pyproject.toml`` обязательным?" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" +"Хотя это еще не технически необходимо, это **STRONGLY RECOMMENDED** для " +"проекта иметь :file:`pyproject. toml' файл в корне своего исходного дерева с " +"таким контентом:" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" +"Руководство:ref: \" Modernize-setup-py-project \" имеет больше деталей об " +"этом." + +#: ../source/discussions/setup-py-deprecated.rst:198 +msgid "" +"The standard fallback behavior for a :term:`build frontend ` " +"in the absence of a :file:`pyproject.toml` file and its ``[build-system]`` " +"table is to assume that the :term:`build backend ` is " +"setuptools." +msgstr "" +"Стандартное обратное поведение для :term:`build frontend ` в " +"отсутствие :file:`pyproject.toml' файла и его ``[build-system]`` таблица " +"предполагает, что :term:`build backend ` является setuptools." + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "Почему? Что все это значит?" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" +"Один из способов взглянуть на это заключается в том, что сфера setuptools " +"теперь была сведена к роли опоры." + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "Где почитать об этом?" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" +"`Почему не следует вызывать setup.py напрямую `__ by Paul Ganssle" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr ":doc:`setuptools:deprecated/commands`" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "Единая версия проекта" + +#: ../source/discussions/single-source-version.rst:7 +msgid "Complete" +msgstr "Выполнено" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "2024-10-07" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" +"Многие Python :term:`distribution packages ` публикуют " +"один Python :term:`import package `, где желательно, чтобы " +"атрибут runtime ``__version__`` на импортном пакете сообщал тот же " +"спецификатор версии, что и :func:`importlib.metadata.version` сообщает для " +"дистрибутивного пакета (как описано в :ref:`runtime-version-access`)." + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" +"Также часто бывает желательно, чтобы эта информация о версии была получена " +"из *метки* системы контроля версий (например, ``v1.2.3``), а не обновлялась " +"вручную в исходном коде." + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" +"Некоторые проекты могут просто смириться с дублированием ввода данных и " +"полагаться на автоматизированное тестирование, чтобы убедиться, что " +"различные значения не расходятся." + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" +"В качестве альтернативы, выбранная проектом система сборки может предложить " +"способ определения единого источника истины для номера версии." + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "В общем, возможны следующие варианты:" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" +"Если код находится в системе контроля версий (VCS), например Git, то версию " +"можно извлечь из VCS." + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" +"Версия может быть жестко задана в файле :file:`pyproject.toml`, а система " +"сборки может скопировать ее в другие места, которые могут потребоваться." + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" +"Строка версии может быть жестко закодирована в исходном коде - либо в " +"специальном файле, таком как :file:`_version.txt` (который затем должен " +"поставляться как часть пакета распространения исходного кода проекта), либо " +"как атрибут в определенном модуле, таком как :file:`__init__.py`. Тогда " +"система сборки может извлечь его из места выполнения во время сборки." + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" +"Обратитесь к документации вашей системы сборки, чтобы узнать о рекомендуемом " +"методе." + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" +"Если предполагается, что дистрибутив и связанный с ним пакет импорта имеют " +"одну и ту же версию, рекомендуется включить в проект автоматизированный " +"тестовый пример, который гарантирует, что ``import_name.__version__`` и " +"``importlib.metadata.version(\"dist-name\")`` сообщают одно и то же значение " +"(примечание: для многих проектов ``import_name`` и ``dist-name`` будут иметь " +"одно и то же имя)." + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "Обработка версий системы сборки" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" +"Ниже приведены ссылки на документацию некоторых систем сборки по работе со " +"строками версий." + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "`Flit `_" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "`Hatchling `_" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" +"`PDM `_" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" +"`Setuptools `_" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "`setuptools_scm `_" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "src-макет против плоского макета" + +#: ../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 "" +"«плоский макет» относится к организации файлов проекта в папке или " +"репозитории, так что различные файлы конфигурации и :термин: «импортные " +"пакеты ` все в директории верхнего уровня." + +#: ../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:`import packages `), перемещается в подкаталог. " +"Этот подкаталог обычно называется ``rc/``, отсюда и \"src раскладка\"." + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" +"Вот разбивка важных различий в поведении между макетом дуги и плоской " +"компоновкой:" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" +"Схема арки требует установки проекта, чтобы иметь возможность запустить его " +"код, а плоской планировки нет." + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" +"Это означает, что планировка дуги включает в себя дополнительный шаг в " +"процессе разработки проекта (как правило, :doc: «отредактируемая установка " +"` используется для разработки и для " +"тестирования используется регулярная установка)." + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" +"Схема кружево помогает предотвратить случайное использование копии кода в " +"разработке." + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" +"Это актуально, поскольку интерпретатор Python включает текущий рабочий " +"каталог в качестве первого пункта на пути импорта. Это означает, что если " +"пакет импорта существует в текущем рабочем каталоге с тем же названием, что " +"и установленный пакет импорта, будет использоваться вариант из текущего " +"рабочего каталога. Это может привести к тонкой неправильной настройке " +"инструментов упаковки проекта, что может привести к тому, что файлы не будут " +"включены в распределение." + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" +"Схема src помогает избежать этого, сохраняя импортные пакеты в каталоге " +"отдельно от корневого каталога проекта, обеспечивая использование " +"установленной копии." + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" +"Схема src помогает обеспечить, чтобы :doc:`editableinstall " +"` смог импортировать только файлы, " +"которые должны были быть импортированы." + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" +"Это особенно актуально, когда редактируемая установка реализована с помощью " +"файла `_ это добавляет каталог " +"к пути импорта." + +#: ../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/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" +"Запуск интерфейса командной строки из исходного текста с помощью src-layout" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" +"В связи с первой из упомянутых особенностей компоновки src, интерфейс " +"командной строки не может быть запущен непосредственно из :term:`source tree " +"`, а требует установки пакета в :doc:`Development Mode " +"` для целей тестирования. Поскольку " +"это может быть непрактично в некоторых ситуациях, обходным решением может " +"быть добавление папки пакета к :py:data:`sys.path` при вызове через " +"файл :file:`__main__.py`:" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +msgid "Versioning" +msgstr "Версионирование" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" +"В этой статье рассматриваются все аспекты версионирования пакетов Python." + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "Допустимые номера версий" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" +"Различные Python-проекты могут использовать различные схемы версионирования " +"в зависимости от потребностей конкретного проекта, но для совместимости с " +"такими инструментами, как :ref:`pip`, все они должны соответствовать гибкому " +"формату идентификаторов версий, для которого авторитетной ссылкой " +"является :ref:`specification of version specifiers `. " +"Вот несколько примеров номеров версий [#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``" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "Альфа-версия: ``1.2.0a1``" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "Бета-версия: ``1.2.0b1``" + +#: ../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 "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +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``" + +#: ../source/discussions/versioning.rst:30 +#, fuzzy +#| msgid "A version with an epoch: ``1!1.0``" +msgid "A version with an epoch (discouraged): ``1!1.0``" +msgstr "Версия с эпохой: ``1!1.0``" + +#: ../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/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/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/versioning.rst:49 +#, fuzzy +#| 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." +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" +"Наконец, эпохи, редко используемая функция, служат для фиксации порядка " +"сортировки при изменении схемы версионирования. Например, если проект " +"использует календарную версификацию, с версиями типа 23.12, и переходит на " +"семантическую версификацию, с версиями типа 1.0, то сравнение между 1.0 и " +"23.12 будет идти в неправильном направлении. Чтобы исправить это, новые " +"номера версий должны иметь явную эпоху, как в \"1!1.0\", чтобы считаться " +"более новыми, чем старые номера версий." + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" +"Семантическое версионирование по сравнению с календарным версионированием" + +#: ../source/discussions/versioning.rst:62 +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:69 +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:75 +#, fuzzy +#| 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." +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" +"Известны исключения при выборе номера следующей версии. Сопровождающие могут " +"сознательно решить нарушить предположение, что последний сегмент версии " +"содержит только обратно-совместимые изменения. Один из таких случаев - " +"необходимость устранения уязвимости в системе безопасности. Релизы " +"безопасности часто выпускаются в виде патчей, но неизбежно содержат ломающие " +"изменения." + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "Семантическая версификация" + +#: ../source/discussions/versioning.rst:87 +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:90 +msgid "*major* when they make incompatible API changes," +msgstr "*главное*, когда они вносят несовместимые изменения в API," + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" +"*незначительные*, когда они добавляют функциональность, совместимую с " +"обратным развитием, и" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" +"*патчи*, когда они исправляют ошибки, совместимые с обратными версиями." + +#: ../source/discussions/versioning.rst:94 +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 используют схему, напоминающую семантическое " +"версионирование. Однако большинство проектов, особенно крупных, не строго " +"придерживаются семантического версионирования, поскольку многие изменения " +"являются технически разрушающими, но затрагивают лишь небольшую часть " +"пользователей. Такие проекты склонны увеличивать основной номер, когда " +"несовместимость высока или сигнализирует о сдвигах в проекте, а не для любой " +"крошечной несовместимости [#semver-strictness]_. И наоборот, увеличение " +"номера основной версии иногда используется, чтобы сообщить о значительных, " +"но обратно совместимых новых возможностях." + +#: ../source/discussions/versioning.rst:104 +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 "" +"Для тех проектов, которые используют строгую семантическую версионность, " +"этот подход позволяет использовать спецификаторы версий : " +"ссылка:`совместимых релизов <Спецификаторы версий-совместимых релизов>`, с " +"помощью оператора ``~=``. Например, ``имя ~= X.Y`` примерно эквивалентно " +"``имя >= X.Y, == X.*``, то есть требует как минимум релиза X.Y, и допускает " +"любой более поздний релиз с большим Y при условии, что X тот же самый. " +"Аналогично, ``имя ~= X.Y.Z`` примерно эквивалентно ``имя >= X.Y.Z, == " +"X.Y.*``, то есть требует не менее X.Y.Z и допускает более поздний выпуск с " +"теми же X и Y, но более высоким Z." + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" +"Python-проекты, использующие семантическое версионирование, должны следовать " +"пунктам 1-8 спецификации `Семантическое версионирование 2.0.0 `_." + +#: ../source/discussions/versioning.rst:116 +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 "" +"Популярный генератор документации : документ:`Sphinx <сфинкс:индекс>` - " +"пример проекта, использующего строгое семантическое версионирование " +"(:документ:`сфинкс политика версионирования <сфинкс: внутренние/процесс " +"выпуска>`). Известный пакет для научных вычислений :doc:`NumPy " +"` явно использует \"свободное\" семантическое версионирование, " +"где релизы, увеличивающие минорную версию, могут содержать обратно-" +"несовместимые изменения API (:doc:`NumPy версионная политика `)." + +#: ../source/discussions/versioning.rst:125 +msgid "Calendar versioning" +msgstr "Версионирование календаря" + +#: ../source/discussions/versioning.rst:127 +#, fuzzy +#| 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." +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" +"Семантическое версионирование подходит не для всех проектов, например, для " +"тех, которые имеют регулярную периодичность выпуска релизов и процесс " +"обесценивания, предусматривающий предупреждения за несколько релизов до " +"удаления функции." + +#: ../source/discussions/versioning.rst:131 +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:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" +"Календарные номера версий обычно имеют вид *год.месяц* (например, 23.12 для " +"декабря 2023 года)." + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" +": документ:`Pip `, стандартная программа установки пакетов " +"Python, использует календарную версификацию." + +#: ../source/discussions/versioning.rst:143 +msgid "Other schemes" +msgstr "Другие схемы" + +#: ../source/discussions/versioning.rst:145 +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:151 +#, fuzzy +#| 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." +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 "" +"Возможны комбинации описанных выше схем. Например, проект может сочетать " +"версионирование по дате с серийным версионированием, чтобы создать схему " +"нумерации *год.серия*, которая легко передает приблизительный возраст " +"релиза, но в остальном не обязывает к определенной периодичности выпуска в " +"течение года." + +#: ../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 "" +"Идентификаторы публичных версий предназначены для поддержки распространения " +"через : термин:`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_, " +"плагином setuptools, который считывает версию из данных Git. В Git-" +"репозитории с некоторыми фиксациями после последнего релиза setuptools-scm " +"генерирует версию типа \"0.5.dev1+gd00980f\", или, если в репозитории есть " +"неотслеживаемые изменения, типа \"0.5.dev1+gd00980f.d20231217\"." + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "Доступ к информации о версии во время выполнения" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" +"Информация о версии всех :term:`distribution packages `, локально доступных в текущем окружении, может быть получена во " +"время выполнения с помощью функции :func:`importlib.metadata.version` " +"стандартной библиотеки::" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" +"Многие проекты также выбирают версионирование своего верхнего " +"уровня :term:`import packages `, предоставляя атрибут " +"``__version__`` на уровне пакета::" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" +"Эта техника может быть особенно ценной для приложений CLI, которые хотят " +"обеспечить максимально быстрое выполнение запросов версий (например, ``pip " +"-V``)." + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" +"Издатели пакетов, желающие обеспечить соответствие версий дистрибутивного и " +"импортного пакетов, могут ознакомиться с обсуждением :ref:`single-source-" +"version` для потенциальных подходов к решению этой задачи." + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" +"Поскольку импортные пакеты и модули не *обязаны* публиковать информацию о " +"версии во время выполнения таким образом (см. отозванное предложение " +"в :pep:`PEP 396 <396>`), атрибут ``__version__`` должен запрашиваться только " +"в интерфейсах, которые, как известно, его предоставляют (например, проект " +"запрашивает свою собственную версию или версию одной из своих прямых " +"зависимостей), или же код запроса должен быть разработан для обработки " +"случая, когда атрибут отсутствует [#fallback-to-dist-version]_." + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" +"Некоторым проектам может потребоваться опубликовать информацию о версии " +"внешних API, которая не является версией самого модуля. Такие проекты должны " +"определить свои собственные, специфичные для проекта способы получения " +"соответствующей информации во время выполнения. Например, модуль :mod:`ssl` " +"стандартной библиотеки предлагает несколько способов доступа к версии " +"библиотеки OpenSSL::" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" +"Еще несколько примеров необычных номеров версий приведены в `блоговом посте " +"<версии-Сет-Ларсон_>`_ Сета Ларсона." + +#: ../source/discussions/versioning.rst:229 +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 "" +"Некоторые личные точки зрения на этот вопрос см. в этих статьях блога: Гинек " +"Шлавак `_, Дональд Стаффт `_, " +"Бернат Габор `_, Бретт Кэннон `_. Для юмористического восприятия читайте о ZeroVer_." + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" +"Полный список, отображающий имена верхнего уровня, доступные для импорта, на " +"дистрибутивы, которые предоставляют эти импортируемые пакеты и модули, можно " +"получить с помощью функции стандартной " +"библиотеки :func:`importlib.metadata.packages_distributions`. Это означает, " +"что даже код, пытающийся определить версию для сообщения для всех " +"импортируемых имен верхнего уровня, имеет возможность вернуться к сообщению " +"информации о версии дистрибутива, если атрибут ``__version__`` не определен. " +"Только стандартные библиотечные модули и модули, добавленные другими " +"способами, кроме установки пакета Python, в этом случае не будут сообщать " +"информацию о версии." + +#: ../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 "" +"Цель этого документа - описать процесс публикации/" +"распространения :term:`распространяемого пакета <Распространяемый пакет>`, " +"обычно в `Индекс пакетов Python (PyPI)`_. Он написан для издателей пакетов, " +"которые, как предполагается, являются авторами пакетов." + +#: ../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 существует только одно общее колесо." + +#: ../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 "" +"Эти два последних шага обычно выполняются :ref:`pip`, когда конечный " +"пользователь запускает ``pip install``." + +#: ../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 "" +"Конфигурационный файл зависит от инструмента, используемого для создания " +"артефактов сборки. Стандартной практикой является использование " +"файла :file:`pyproject.toml` в формате `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', " +"`trampolim`_ и `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', \":term:`frontend `\" tool like :ref:`build` может запускать выбранный вами " +"инструмент построения \":term:`backend `\" для создания " +"артефактов сборки. Ваш инструмент сборки также может предоставить свой " +"собственный фронтенд. Инструмент установки, такой как :ref:`pip'', также " +"действует в качестве фронтенда, когда он запускает предысторию вашего " +"инструмента для установки из распределения источника." + +#: ../source/flow.rst:94 +msgid "" +"The particular build tool you choose dictates what additional information is " +"required in the :file:`pyproject.toml` file. For example, you might specify:" +msgstr "" +"Выбранный вами инструмент сборки диктует, какая дополнительная информация " +"требуется в файле :file:`pyproject.toml`. Например, вы можете указать:" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" +"таблица ``[проект]``, содержащая проект :doc:``Основные метаданные ` (название, версия, автор и так далее)," + +#: ../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 guide `." + +#: ../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 "Построенные дистрибутивы (колеса)" + +#: ../source/flow.rst:132 +msgid "" +"A built distribution contains only the files needed for an end user's Python " +"environment. No compilation steps are required during the install, and the " +"wheel file can simply be unpacked into the ``site-packages`` directory. This " +"makes the install faster and more convenient for end users." +msgstr "" +"Собранный дистрибутив содержит только файлы, необходимые для среды Python " +"конечного пользователя. При установке не требуется компиляция, а файл wheel " +"можно просто распаковать в каталог ``ite-packages``. Это делает установку " +"более быстрой и удобной для конечных пользователей." + +#: ../source/flow.rst: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 обычно требуется только одно \"общее\" колесо. Пакет " +"с компилируемыми бинарными расширениями нуждается в колесе для каждой " +"поддерживаемой комбинации интерпретатора Python, операционной системы и " +"архитектуры процессора, которые он поддерживает. Если подходящий файл колеса " +"недоступен, такие инструменты, как :ref:`pip`, вернутся к установке " +"исходного дистрибутива." + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" +"Или же ваш инструмент сборки может предоставлять собственный интерфейс для " +"создания колеса." + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" +"По умолчанию поведение :ref:`build' состоит в том, чтобы сделать как sdist, " +"так и колесо из источника в текущем каталоге; приведенные выше примеры " +"преднамеренно конкретны." + +#: ../source/flow.rst: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:`pdm'." + +#: ../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 "" +"Особый вид :term:`Built Distribution`, содержащий скомпилированные " +"расширения." + +#: ../source/glossary.rst:14 +msgid "Build Backend" +msgstr "Создание бэкэнда" + +#: ../source/glossary.rst:17 +#, fuzzy +#| msgid "" +#| "A library that takes a source tree and builds a :term:`source " +#| "distribution ` or :term:`built " +#| "distribution ` from it. The build is delegated to the " +#| "backend by a :term:`frontend `. All backends offer a " +#| "standardized interface." +msgid "" +"A library that takes a :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" +"Библиотека, которая принимает дерево исходных текстов и собирает из него : " +"термин:`источник дистрибутива <Источник дистрибутива (или \"sdist\")>` " +"или :термин:`сборка дистрибутива <Сборка дистрибутива>`. Сборка делегируется " +"бэкенду с помощью : термин:`фронтенд <Сборка фронтенда>`. Все бэкенды " +"предлагают стандартизированный интерфейс." + +#: ../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's flit-core " +"`, :ref:`hatch's hatchling `, :ref:`maturin`, :ref:`meson-" +"python`, :ref:`scikit-build-core`, и :ref:`setuptools`." + +#: ../source/glossary.rst:32 +msgid "Build Frontend" +msgstr "Сборка фронтенда" + +#: ../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:`колеса `. Собственно сборка " +"делегируется каждому дереву исходников :term:`build backend `." + +#: ../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 :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 "" +"Формат : термин:`Дистрибутив <Дистрибутивный пакет>`, содержащий файлы и " +"метаданные, которые нужно только переместить в нужное место на целевой " +"системе, чтобы установить. :термин:`Wheel` является таким форматом, тогда " +"как :термин:`Источник дистрибутива <Источник дистрибутива (или \"sdist\")>` " +"не является, поскольку требует этапа сборки перед установкой. Этот формат " +"не подразумевает, что файлы Python должны быть предварительно скомпилированы " +"(:term:`Wheel` намеренно не включает скомпилированные файлы Python). " +"Дополнительную информацию смотрите в : ссылка:`форматы пакетов`." + +#: ../source/glossary.rst:56 +msgid "Built Metadata" +msgstr "Встроенные метаданные" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" +"Конкретная форма, которую принимает : термин:`Основные метаданные` при " +"включении в установленный :термин:`Проект` (файл ``METADATA``) или " +"архив :термин:`Дистрибутив` (``PKG-INFO`` в :термин:`Sdist <Источник " +"дистрибутива (или \"sdist\")>` и ``METADATA`` в :термин:`Колесо``)." + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "Основные метаданные" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" +"`Спецификация <основные метаданные>` и набор определяемых ею полей : " +"термин:`Основные поля метаданных`\\, которые описывают ключевые статические " +"атрибуты :термин:`Дистрибутивный пакет` или :термин:`Установленный проект`." + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "Поле основных метаданных" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" +"Одиночная пара ключ-значение (или последовательность таких пар с одинаковым " +"именем, для многоразовых полей), определенная в спецификации : " +"термин:`Основные метаданные` и хранящаяся в :термин:`Строенные метаданные`. " +"Отличается от : термин:`Ключ метаданных пайпроекта`." + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "Архив дистрибутивов" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" +"Физический артефакт распространения (т.е. файл на диске) для : " +"термин:`Дистрибутивный пакет`." + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "Пакет дистрибутива" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" +"Версионный архивный файл, содержащий Python :term:`пакеты `, :term:`модули ` и другие файлы ресурсов, которые " +"используются для распространения :term:`Release`. Архивный файл - это то, " +"что конечный пользователь скачает из интернета и установит." + +#: ../source/glossary.rst:97 +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:`Import Package` (который также обычно называется \"пакет\") или " +"другим видом дистрибутива (например, дистрибутив Linux или дистрибутив языка " +"Python), которые часто обозначаются одним термином \"дистрибутив\". Разбор " +"различий см. в :ref:`distribution-package-vs-import-package`." + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "Яйцо" + +#: ../source/glossary.rst:108 +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:`Built Distribution`, введенный :ref:`setuptools`, который был " +"заменен :term:`Wheel`. Подробности см. в :ref:`egg-format`." + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "Модуль расширения" + +#: ../source/glossary.rst:114 +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 "" +"Термин:`Модуль`, написанный на языке низкого уровня реализации Python: C/C++ " +"для Python, Java для Jython. Обычно содержится в одном динамически " +"загружаемом предварительно скомпилированном файле, например, в файле общих " +"объектов (.so) для расширений Python на Unix, DLL (с расширением .pyd) для " +"расширений Python на Windows, или в файле классов Java для расширений Jython." + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "Import Package (Импортируемый пакет)" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" +"Модуль Python, который может содержать другие модули или, рекурсивно, другие " +"пакеты." + +#: ../source/glossary.rst:127 +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:`Distribution Package`, который " +"также обычно называется \"пакет\". Различия см. в :ref:`distribution-package-" +"vs-import-package`." + +#: ../source/glossary.rst:133 +msgid "Installed Project" +msgstr "Установленный проект" + +#: ../source/glossary.rst:136 +#, fuzzy +#| msgid "" +#| "A :term:`Project` that is installed for use with a Python interpreter " +#| "or :term:`Virtual Environment`, as described in the " +#| "specicifcation :ref:`recording-installed-packages`." +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" +"Проект, установленный для использования с интерпретатором Python или : " +"термин:`виртуальное окружение`, как описано в спецификации : ссылка:`запись-" +"установленных-пакетов`." + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "Known Good Set (KGS, Известный хороший набор)" + +#: ../source/glossary.rst:143 +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 "" +"Набор дистрибутивов определенных версий, совместимых друг с другом. Обычно " +"перед тем, как объявить определенный набор пакетов заведомо исправным, " +"запускается набор тестов, который проходит все проверки. Этот термин обычно " +"используется во фреймворках и наборах инструментов, которые состоят из " +"нескольких отдельных дистрибутивов." + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "Лицензионный классификатор" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" +"Классификатор PyPI Trove (как :ref:`described ` в " +"спецификации :term:`Core Metadata`), который начинается с ``Лицензии ::``." + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "Лицензионная экспрессия" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "SPDX Экспрессия" + +#: ../source/glossary.rst:161 +#, fuzzy +#| msgid "" +#| "A string with valid SPDX license expression syntax, including one or more " +#| "SPDX :term:`License Identifier`\\(s), which describes a :term:`Project`'s " +#| "license(s) and how they inter-relate. Examples: ``GPL-3.0-or-later``, " +#| "``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" +"Строка с допустимым синтаксисом выражения лицензий SPDX, включающая один или " +"несколько идентификаторов SPDX :term:`License Identifier`\\(s), которые " +"описывают лицензии :term:`Project` и их взаимосвязь. Примеры: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "Лицензионный идентификатор" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "Идентификатор SPDX" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" +"Действительный идентификатор короткой формы лицензии SPDX, первоначально " +"указанный в :pep:`639`. Сюда входят все действительные идентификаторы SPDX и " +"пользовательские строки ``LicenseRef-[idstring]``, соответствующие " +"спецификации SPDX. Примеры: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-" +"Custom-License``" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "Модуль" + +#: ../source/glossary.rst:186 +msgid "" +"The basic unit of code reusability in Python, existing in one of two " +"types: :term:`Pure Module`, or :term:`Extension Module`." +msgstr "" +"Базовая единица многократного использования кода в Python, существующая в " +"одном из двух типов: :термин: «чистый модуль» или :термин: «модуль " +"расширения»." + +#: ../source/glossary.rst:189 +msgid "Package Index" +msgstr "Индекс пакета" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" +"Репозиторий дистрибутивов с веб-интерфейсом для автоматизации :term:`package " +"` обнаружения и потребления." + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "Индекс на проект" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "Проект" + +#: ../source/glossary.rst:205 +msgid "" +"A library, framework, script, plugin, application, or collection of data or " +"other resources, or some combination thereof that is intended to be packaged " +"into a :term:`Distribution `." +msgstr "" +"Библиотека, структура, сценарий, плагин, приложение или сбор данных или " +"других ресурсов, или определенная их комбинация, которая должна быть " +"упакована в :term:`Distribution `." + +#: ../source/glossary.rst:209 +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 "" +"Поскольку большинство проектов создают :term:`Distributions <Дистрибутивный " +"пакет>`, используя либо :pep:`518` `build-system`, :ref:`distutils` " +"или :ref:`setuptools`, другим практичным способом определения проектов в " +"настоящее время является то, что " +"содержит :term:`pyproject.toml`, :term:`setup.py` или :term:`setup.cfg` файл " +"в корне исходного каталога проекта." + +#: ../source/glossary.rst:215 +msgid "" +"Python projects must have unique names, which are registered on :term:`PyPI " +"`. Each project will then contain one or " +"more :term:`Releases `, and each release may comprise one or " +"more :term:`distributions `." +msgstr "" +"Проекты Python должны иметь уникальные имена, которые регистрируются " +"в :term:`PyPI `. Каждый проект будет содержать " +"один или несколько :term:`Releases `, а каждый релиз может состоять " +"из одного или нескольких :term:`distributions `." + +#: ../source/glossary.rst:220 +msgid "" +"Note that there is a strong convention to name a project after the name of " +"the package that is imported to run that project. However, this doesn't have " +"to hold true. It's possible to install a distribution from the project 'foo' " +"and have it provide a package importable only as 'bar'." +msgstr "" +"Обратите внимание, что существует строгое правило называть проект по имени " +"пакета, который импортируется для запуска этого проекта. Однако это не " +"обязательно так. Можно установить дистрибутив из проекта 'foo' и получить от " +"него пакет, импортируемый только как 'bar'." + +#: ../source/glossary.rst:226 +msgid "Project Root Directory" +msgstr "Корневой каталог проекта" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" +"Каталог файловой системы, в котором находится : " +"термин:`Проект` :термин:`дерево источников <Дерево источников проекта>`." + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "Дерево источников проекта" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" +"Дисковый формат : термин:`Проект`, используемый для разработки, содержащий " +"его исходный код перед упаковкой в :термин:`Источник дистрибутива <Источник " +"дистрибутива (или \"sdist\")>` или :термин:`Созданный дистрибутив`." + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "Исходные метаданные проекта" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" +"Метаданные, определенные автором пакета в : термин:`Проект` " +"в :термин:`дерево источников <Дерево источников проекта>`, которые должны " +"быть преобразованы в :термин:`поля основных метаданных`\\ " +"в :термин:`Строенные метаданные` бэкендом проекта :термин:`бэкенд сборки " +"<Бэкенд сборки>`. Может быть записана как : термин:`Метаданные Пайпроекта`, " +"или в специфическом для инструмента формате (в таблице ``[ Инструмент]`` в " +"``pyproject.toml``, или в собственном конфигурационном файле инструмента)." + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "Чистый модуль" + +#: ../source/glossary.rst:257 +msgid "" +"A :term:`Module` written in Python and contained in a single ``.py`` file " +"(and possibly associated ``.pyc`` and/or ``.pyo`` files)." +msgstr "" +"Модуль, написанный на языке Python и содержащийся в одном файле ``.py`` (и, " +"возможно, связанных с ним файлах ``.pyc`` и/или ``.pyo``)." + +#: ../source/glossary.rst:260 +msgid "Pyproject Metadata" +msgstr "Метаданные Pyproject" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" +"Формат исходных метаданных проекта, определенный " +"спецификацией :ref:`декларирования метаданных проекта` и первоначально " +"представленный в :pep:`621`, хранящийся как : термин:`Пайпроект Метаданные " +"Ключ`\\ в таблице ``[ проект]`` файла : термин:`pyproject.toml`. " +"Примечательно, что *не* специфический для инструмента формат метаданных " +"источника в таблице ``[ инструмент]`` в файле ``pyproject.toml``." + +#: ../source/glossary.rst:271 +msgid "Pyproject Metadata Key" +msgstr "Ключ метаданных Pyproject" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" +"TOML-ключ верхнего уровня в таблице ``[[проект]`` в файле " +"``pyproject.toml``; часть : термин:``Метаданные пайпроекта``. Отличается " +"от : термин:`Поле основных метаданных`." + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "Подключите метаданные Pyproject" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" +"Ключ TOML второго уровня под табличным значением : термин:`Пайпроект Ключ " +"Метаданных`." + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "Python Управление по упаковке (PyPA)" + +#: ../source/glossary.rst:287 +#, fuzzy +#| 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 `__." +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" +"PyPA - это рабочая группа, которая поддерживает множество соответствующих " +"проектов по упаковке Python. Они поддерживают сайт по адресу :doc:`pypa.io " +"`, размещают проекты на `GitHub `_ и " +"`Bitbucket `_, а также обсуждают проблемы в " +"списке рассылки `distutils-sig `_ и на форуме Python Discourse `__." + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "Индекс пакетов Python (PyPI)" + +#: ../source/glossary.rst:298 +msgid "" +"`PyPI `_ is the default :term:`Package Index` for the " +"Python community. It is open to all Python developers to consume and " +"distribute their distributions." +msgstr "" +"`PyPI `_ является стандартным :term:`Package Index` для " +"сообщества Python. Он открыт для всех разработчиков Python для потребления и " +"распространения их дистрибутивов." + +#: ../source/glossary.rst:301 +msgid "pypi.org" +msgstr "pypi.org" + +#: ../source/glossary.rst:304 +msgid "" +"`pypi.org `_ is the domain name for the :term:`Python " +"Package Index (PyPI)`. It replaced the legacy index domain name, " +"``pypi.python.org``, in 2017. It is powered by :ref:`warehouse`." +msgstr "" +"`pypi.org `_ - это доменное имя для :term:`Python Package " +"Index (PyPI)`. Он заменил устаревшее доменное имя индекса, " +"``pypi.python.org``, в 2017 году. Он работает на базе :ref:`warehouse`." + +#: ../source/glossary.rst:308 +msgid "pyproject.toml" +msgstr "pyproject.toml" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" +"Инструмент-агностик:термин: файл спецификации \"Проект\". Определен " +"в :pep:`518'." + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "Выпуск" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" +"Снимок :term:`Project` в определенный момент времени, обозначаемый " +"идентификатором версии." + +#: ../source/glossary.rst:319 +msgid "" +"Making a release may entail the publishing of multiple :term:`Distributions " +"`. For example, if version 1.0 of a project was " +"released, it could be available in both a source distribution format and a " +"Windows installer distribution format." +msgstr "" +"Создание релиза может повлечь за собой публикацию " +"нескольких :term:`Distributions `. Например, если " +"версия 1.0 проекта была выпущена, она может быть доступна как в формате " +"распределения источника, так и в формате Windows." + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "Требование" + +#: ../source/glossary.rst:327 +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:`пакета `. :ref:`pip`, рекомендуемый установщик :term:`PYPA `, допускает различные формы спецификации, " +"которые все могут считаться \"требованием\". Для получения дополнительной " +"информации смотрите ссылку :ref:`pip:pip install`." + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "Спецификатор требований" + +#: ../source/glossary.rst:336 +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 "" +"Формат, используемый :ref:`pip` для установки пакетов из :term:`Package " +"Index`. EBNF диаграмму этого формата смотрите в :ref:`dependency-" +"specifiers`. Например, \"foo>=1.3\" - это спецификатор требований, где " +"\"foo\" - это имя проекта, а часть \">=1.3\" - это :term:`Version Specifier`" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "Требования к файлам" + +#: ../source/glossary.rst:344 +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 "" +"Файл, содержащий список :term:`Requirements ` который может " +"быть установлен с помощью :ref:`pip'. Дополнительные сведения см. " +"в :ref:`pip'''' docs on :ref:`pip:Requirements Files`." + +#: ../source/glossary.rst:348 +msgid "Root License Directory" +msgstr "Каталог корневых лицензий" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "Каталог лицензий" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" +"Каталог, в котором хранятся файлы лицензий в :term:`Project Source " +"Tree`, :term:`Distribution Archive` или :term:`Installed Project`. " +"Для :term:`Project Source Tree` или :term:`Source Distribution (or " +"\"sdist\")` это :term:`Project Root Directory`. Для :term:`Built " +"Distribution` или :term:`Installed Project` - это :file:`.dist-info/licenses/" +"` каталог архива колеса или папки проекта соответственно. Также это корневая " +"директория, к которой относятся пути, записанные в ``License-" +"File`` :term:`Core Metadata Field``." + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "setup.py" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "setup.cfg" + +#: ../source/glossary.rst:369 +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:372 +msgid "Source Archive" +msgstr "Источник Архив" + +#: ../source/glossary.rst:375 +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:`Release`, до " +"создания :term:`Source Distribution ` " +"или :term:`Built Distribution`." + +#: ../source/glossary.rst:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "Распространение исходных текстов (или \"sdist\")" + +#: ../source/glossary.rst:382 +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." +msgstr "" +"Формат : термин:`дистрибутив <архив дистрибутива>` (обычно генерируется с " +"помощью ``python -m build --sdist``), который предоставляет метаданные и " +"основные исходные файлы, необходимые для установки с помощью такого " +"инструмента, как : ссылка:`pip`, или для генерации :термин:`сборка " +"дистрибутива``. Дополнительную информацию смотрите в : ссылка:`Форматы " +"пакетов`." + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "Системный пакет" + +#: ../source/glossary.rst:391 +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:394 +msgid "Version Specifier" +msgstr "Спецификатор версии" + +#: ../source/glossary.rst:397 +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 "" +"Компонент версии :термин: \" спецификатор запросов \" . Например, \">=1.3\" " +"части \"foo>=1.3\". Прочтите :ref:`Version спецификатор ` для полного описания спецификаторов, которые Python в " +"настоящее время поддерживаются. Поддержка этой спецификации была реализована " +"в :ref:`setuptools` v8.0 и :ref:`pip` v6.0." + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "Виртуальная среда" + +#: ../source/glossary.rst:405 +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:`Создание и " +"использование виртуальных сред`." + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "Формат колеса" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "Колесо" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" +"Стандартный формат : термин:`Созданный дистрибутив`, первоначально " +"представленный в :pep:`427` и определенный спецификацией : ссылка:`binary-" +"distribution-format`. Дополнительную информацию см. в : ссылка:`пакетные " +"форматы`. Не путать с его эталонной реализацией, : термин:``Колесо проекта``." + +#: ../source/glossary.rst:421 +msgid "Wheel Project" +msgstr "Проект Колесо" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" +"Эталонная реализация PyPA формата : термин:`Формат колеса`; см. : " +"ссылка:`колесо`." + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "Рабочая группа" + +#: ../source/glossary.rst:429 +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. В " +"рабочем наборе возможен максимум один :term:`Distribution ` для проекта." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "Анализ загрузок пакетов с PyPI" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "Фон" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "PyPI не отображает статистику загрузки по ряду причин: [#]_" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "``pip`` кэш загрузки (считывает количество загрузок)" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" +"Внутренние или неофициальные зеркала (могут как поднять, так и снизить " +"количество загрузок)" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "Пакеты, не размещенные на PyPI (для сравнения)" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" +"Неофициальные скрипты или попытки скачать подсчет инфляции (изобличает " +"количество загрузок)" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" +"Известные исторические проблемы качества данных (низкие числа загрузок)" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "Набор данных" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" +"`__ потоков загружает " +"журналы от PyPI до `Google BigQuery`_ [#]_, где они хранятся в виде набора " +"общедоступных данных." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "Подготовка к работе" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 и " +"включить API BigQuery в проект Google Cloud Platform. `__" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "Перейдите к `BigQuery web UI`_." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "Создайте новый проект." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" +"Включить `BigQuery API `__." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" +"Для более подробных инструкций о том, как начать работу с BigQuery, " +"ознакомьтесь с `BigQuery Руководством по ускоренному запуску `__." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "Схема данных" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" +"Linehaul пишет запись в таблице ``bigquery-public-data.pypi.file_downloads`` " +"для каждой загрузки. В таблице содержится информация о том, какой файл был " +"загружен и как он был загружен. Некоторые полезные столбцы из «табличной " +"схемы `__ включить:" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "Колонка" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "Описание" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "Примеры" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "Дата и время" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "Название проекта" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "``pipenv``, ``nose``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "Версия пакета" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "``0.1.6``, ``1.4.2``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "Установщик" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "pip, :ref:`bandersnatch`" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "Версия Python" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "Полезные запросы" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" +"Запустить запросы в `BigQuery веб-UI`_, нажав на кнопку \"Compose request\"." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "Подсчёт количества загрузок пакетов" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" +"В следующем запросе учитывается общее количество загрузок для проекта " +"«pytest." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" +"Чтобы подсчитать загрузки только из pip, отфильтруйте столбец " +"``details.installer.name``." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "Загрузки пакетов с течением времени" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" +"Для группировки по месячным загрузкам используйте функцию " +"``TIMESTAMP_TRUNC``. Также фильтрация по этому столбцу снижает " +"соответствующие расходы." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "1956741" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "2344692" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "2017-12-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "1730398" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "2017-11-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "2047310" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "2017-10-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "1744443" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "2017-09-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "1916952" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "2017-08-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "Python версии с течением времени" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" +"Исключить Python версию из колонки ``details.python``. Предупреждение: Этот " +"запрос обрабатывает 500 ГБ данных." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "python" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "3.7" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "18051328726" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "3.6" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "9635067203" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "3.8" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "7781904681" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "2.7" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "6381252241" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "2026630299" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "3.5" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "1894153540" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "Получение абсолютной связи с артефактами" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" +"Не гарантируется, что сгенерированный здесь URL будет стабильным, но в " +"настоящее время он совпадает с URL, на котором размещены артефакты PyPI." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "url" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +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/analyzing-pypi-package-downloads.rst:246 +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/analyzing-pypi-package-downloads.rst:248 +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/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "Оговорки" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" +"В дополнение к предостережениям, перечисленным выше, Linehaul страдает от " +"ошибки, из-за которой он значительно занижает статистику загрузок до 26 июля " +"2018 года. Количество загрузок до этой даты пропорционально точно (например, " +"процентное соотношение загрузок Python 2 и Python 3), но общее количество на " +"порядок ниже фактического." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "Дополнительные инструменты" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +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:273 +msgid "``google-cloud-bigquery``" +msgstr "``google-cloud-bigquery``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" +"Вы также можете получить доступ к публичному набору данных статистики " +"загрузок PyPI программным путем через BigQuery API и проект `google-cloud-" +"bigquery`_, официальную клиентскую библиотеку Python для BigQuery." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "``pypinfo``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" +"`pypinfo`_ - это инструмент командной строки, который предоставляет доступ к " +"набору данных и может генерировать несколько полезных запросов. Например, вы " +"можете запросить общее количество загрузок для пакета с помощью команды " +"``pypinfo package_name``." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "Установите `pypinfo`_ через :program:`pip`." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "Использование:" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "``pandas-gbq``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" +"Проект `pandas-gbq`_ позволяет получать доступ к результатам запросов через " +"`Pandas`_." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "Ссылка" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" +"`PyPI Скачать Counts deprecation email `__" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" +"Сообщение об анонсе набора данных PyPI BigQuery по электронной почте " +"`__" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "Создание и обнаружение плагинов" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" +"Часто при создании приложений или библиотек на Python вы хотите иметь " +"возможность предоставлять настройки или дополнительные возможности с помощью " +"**плагинов**. Поскольку пакеты Python могут распространяться отдельно, ваше " +"приложение или библиотека могут захотеть автоматически **обнаружить** все " +"доступные плагины." + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" +"Существует три основных подхода к автоматическому обнаружению плагинов:" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "`Использование соглашения об именах`_." + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "`Использование пакетов пространства имён`_." + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "`Использование метаданных пакета`_." + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "Использование соглашения об именах" + +#: ../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 "" +"Если все плагины вашего приложения имеют одинаковые имена, вы можете " +"использовать :func:`pkgutil.iter_modules` для поиска всех модулей верхнего " +"уровня, которые соответствуют этому соглашению. Например, `Flask`_ " +"использует соглашение об именовании ``flask_{plugin_name}``. Если вы хотите " +"автоматически обнаружить все установленные плагины Flask:" + +#: ../source/guides/creating-and-discovering-plugins.rst:38 +msgid "" +"If you had both the `Flask-SQLAlchemy`_ and `Flask-Talisman`_ plugins " +"installed then ``discovered_plugins`` would be:" +msgstr "" +"Если у вас установлены оба плагина `Flask-SQLAlchemy`_ и `Flask-Talisman`_, " +"то ``discovered_plugins`` будет иметь вид:" + +#: ../source/guides/creating-and-discovering-plugins.rst:48 +msgid "" +"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 Package Index :ref:`simple repository API ` все пакеты, которые соответствуют вашему соглашению об " +"именовании." + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "Использование пакетов пространства имён" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" +":doc:`Пакеты пространства имен <пакеты-пространства имен>` могут быть " +"использованы для обеспечения соглашения о том, где размещать плагины, а " +"также обеспечивают способ обнаружения. Например, если вы сделаете подпакет " +"``myapp.plugins`` пакетом пространства имен, то другие :term:``дистрибутивы " +"`` смогут предоставлять модули и пакеты для этого " +"пространства имен. После установки вы можете " +"использовать :func:`pkgutil.iter_modules` для обнаружения всех модулей и " +"пакетов, установленных под этим пространством имен:" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" +"Указание ``myapp.plugins.__path__`` в :func:`~pkgutil.iter_modules`` " +"заставляет его искать только те модули, которые находятся непосредственно в " +"этом пространстве имен. Например, если у вас установлены дистрибутивы, " +"предоставляющие модули ``myapp.plugins.a`` и ``myapp.plugins.b``, то " +"``discovered_plugins`` в этом случае будет:" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +msgid "" +"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 "" +"В этом примере в качестве пакета пространства имен используется подпакет " +"(``myapp.plugins``), но можно также использовать для этой цели пакет " +"верхнего уровня (например, ``myapp_plugins``). Выбор пространства имен - это " +"вопрос предпочтений, но не рекомендуется делать основной пакет верхнего " +"уровня вашего проекта (``myapp`` в данном случае) пакетом пространства имен " +"для плагинов, так как один плохой плагин может привести к поломке всего " +"пространства имен, что в свою очередь сделает ваш проект неимпортируемым. " +"Чтобы подход \"namespace sub-package\" работал, пакеты плагинов должны " +"опускать :file:`__init__.py` для каталога пакета верхнего уровня (``myapp`` " +"в данном случае) и включать стиль namespace-package :file:`__init__.py` в " +"каталог namespace sub-package (``myapp/plugins``). Это также означает, что " +"плагины должны будут явно передавать список пакетов в аргумент ``packages`` " +"в :func:`setup``, а не использовать :func:`setuptools.find_packages``." + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +msgid "" +"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 "" +"Пакеты пространства имен - сложная функция, и существует несколько различных " +"способов их создания. Настоятельно рекомендуется прочитать " +"документацию :doc:`packaging-namespace-packages` и четко документировать, " +"какой подход предпочтителен для плагинов вашего проекта." + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "Использование метаданных пакета" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" +"Пакеты могут иметь метаданные для плагинов, описанные в :ref:`entry-points`. " +"Указывая их, пакет сообщает, что он содержит определенный тип плагина. " +"Другой пакет, поддерживающий этот тип плагина, может использовать метаданные " +"для обнаружения этого плагина." + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" +"Например, если у вас есть пакет с именем ``myapp-plugin-a`` и он включает " +"следующее в свой ``pyproject.toml``:" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +msgid "" +"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 "" +"Затем вы можете обнаружить и загрузить все зарегистрированные точки входа, " +"используя :func:`importlib.metadata.entry_points` (или backport_ " +"``importlib_metadata >= 3.6`` для Python 3.6-3.9):" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" +"В этом примере ``discovered_plugins`` будет коллекцией " +"типа :class:`importlib.metadata.EntryPoint``:" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" +"Теперь выбранный вами модуль можно импортировать, выполнив команду " +"``discovered_plugins['a'].load()``." + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +msgid "" +"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 "" +"Спецификация ``точки входа`` в :file:`setup.py` довольно гибкая и имеет " +"множество опций. Рекомендуется прочитать весь раздел по :doc:``точкам входа " +"` ." + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" +"Поскольку эта спецификация является частью :doc:`стандартной библиотеки " +"`, большинство инструментов упаковки, " +"кроме setuptools, обеспечивают поддержку определения точек входа." + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "Создание и упаковка инструментов командной строки" + +#: ../source/guides/creating-command-line-tools.rst:7 +#, fuzzy +#| msgid "" +#| "This guide will walk you through creating and packaging a standalone " +#| "command-line application that can be installed with :ref:`pipx`, a tool " +#| "creating and managing :term:`Python Virtual Environments ` and exposing the executable scripts of packages (and " +#| "available manual pages) for use on the command-line." +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" +"Это руководство поможет вам создать и упаковать автономное приложение " +"командной строки, которое можно установить с помощью :ref:`pipx`, " +"инструмента для создания и управления :term:`Python Virtual Environments " +"` и предоставления исполняемых скриптов пакетов (и " +"доступных страниц руководства) для использования в командной строке." + +#: ../source/guides/creating-command-line-tools.rst:12 +msgid "Creating the package" +msgstr "Создание пакета" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" +"Прежде всего, создайте дерево исходных текстов для :term:`project " +"`. Для примера мы создадим простой инструмент, выводящий " +"приветствие (строку) для человека на основе аргументов, заданных в командной " +"строке." + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "Todo" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" +"Посоветуйте оптимальную структуру пакета Python в другом руководстве или " +"обсуждении и дайте на него ссылку здесь." + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" +"Этот проект будет придерживаться :ref:`src-layout ` и в итоге будет похож на это дерево файлов, с папкой верхнего " +"уровня и именем пакета ``greetings``:" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" +"Собственно код, отвечающий за функциональность инструмента, будет храниться " +"в файле :file:`greet.py`, названном в честь основного модуля:" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" +"Приведенная выше функция получает несколько аргументов-ключей, которые " +"определяют, как будет построено приветствие для вывода. Теперь " +"сконструируйте интерфейс командной строки, чтобы обеспечить его тем же " +"самым, что делается в :file:`cli.py`:" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" +"Интерфейс командной строки построен с помощью typer_, простого в " +"использовании парсера CLI, основанного на подсказках типов Python. Он " +"обеспечивает автозавершение и красиво оформленную справку по командной " +"строке из коробки. Другим вариантом может быть :py:mod:`argparse`, парсер " +"командной строки, включенный в стандартную библиотеку Python. Он достаточен " +"для большинства потребностей, но требует много кода, обычно в ``cli.py``, " +"для правильной работы. В качестве альтернативы, docopt_ позволяет создавать " +"интерфейсы CLI, основанные исключительно на строках документов; продвинутым " +"пользователям рекомендуется использовать click_ (на котором основан " +"``typer``)." + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" +"Теперь добавьте пустой файл :file:`__init__.py`, чтобы определить проект как " +"обычный :term:`import package `." + +#: ../source/guides/creating-command-line-tools.rst:88 +#, fuzzy +#| msgid "" +#| "The file :file:`__main__.py` marks the main entry point for the " +#| "application when running it via :mod:`runpy` (i.e. ``python -m " +#| "greetings``, which works immediately with flat layout, but requires " +#| "installation of the package with src layout), so initizalize the command-" +#| "line interface here:" +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" +"Файл :file:`__main__.py` обозначает основную точку входа в приложение при " +"его запуске через :mod:`runpy` (т.е. ``python -m greetings``, что сразу " +"работает при плоской раскладке, но требует установки пакета при src-" +"раскладке), поэтому инициализируйте здесь интерфейс командной строки:" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" +"Для того чтобы можно было вызывать интерфейс командной строки " +"непосредственно из :term:`source tree `, т.е. как " +"``python src/greetings``, в этот файл можно поместить определенный хак; " +"подробнее читайте в :ref:`running-cli-from-source-src-layout``." + +#: ../source/guides/creating-command-line-tools.rst:106 +msgid "``pyproject.toml``" +msgstr "``pyproject.toml``" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" +"Метаданные проекта :term:`metadata ` размещаются " +"в :term:`pyproject.toml`. Ключи метаданных :term:`pyproject ` и таблица ``[build-system]`` могут быть заполнены, как " +"описано в :ref:`writing-pyproject-toml`, добавив зависимость от ``typer`` (в " +"этом руководстве используется версия *0.12.3*)." + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" +"Чтобы проект распознавался как инструмент командной строки, дополнительно " +"необходимо добавить ``console_scripts`` :ref:`entry point ` " +"(см. :ref:`console_scripts`) в качестве :term:`subkey `:" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" +"Теперь дерево исходных текстов проекта готово к преобразованию " +"в :term:`distribution package `, что делает его " +"пригодным для установки." + +#: ../source/guides/creating-command-line-tools.rst:123 +msgid "Installing the package with ``pipx``" +msgstr "Установка пакета с помощью ``pipx``" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" +"После установки ``pipx``, как описано в :ref:`installing-stand-alone-command-" +"line-tools`, установите ваш проект:" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" +"Это откроет исполняемый скрипт, который мы определили как точку входа, и " +"сделает доступной команду ``greet``. Давайте проверим это:" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" +"Поскольку в этом примере используется ``typer``, теперь вы также можете " +"получить обзор использования программы, вызвав ее с помощью опции ``--" +"help``, или настроить завершение работы с помощью опции ``--install-" +"completion``." + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" +"Чтобы просто запустить программу без ее постоянной установки, используйте " +"``pipx run``, который создаст для нее временное (но кэшированное) " +"виртуальное окружение:" + +#: ../source/guides/creating-command-line-tools.rst:156 +#, fuzzy +#| msgid "" +#| "This syntax is a bit unpractical, however; as the name of the entry point " +#| "we defined above does not match the package name, we need to state " +#| "explicitly which executable script to run (even though there is only on " +#| "in existence)." +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" +"Однако этот синтаксис немного непрактичен: поскольку имя точки входа, " +"которую мы определили выше, не совпадает с именем пакета, нам нужно явно " +"указать, какой исполняемый скрипт запускать (даже если существует только " +"один)." + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" +"Однако существует более практичное решение этой проблемы в виде точки входа, " +"специфичной для ``pipx run``. Ее можно определить следующим образом " +"в :file:`pyproject.toml`:" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" +"Благодаря этой точке входа (которая *должна* соответствовать имени пакета), " +"``pipx`` подберет исполняемый скрипт по умолчанию и запустит его, что делает " +"эту команду возможной:" + +#: ../source/guides/creating-command-line-tools.rst:176 +msgid "Conclusion" +msgstr "Заключение" + +#: ../source/guides/creating-command-line-tools.rst:178 +#, fuzzy +#| msgid "" +#| "You know by now how to package a command-line application written in " +#| "Python. A further step could be to distribute you package, meaning " +#| "uploading it to a :term:`package index `, most " +#| "commonly :term:`PyPI `. To do that, follow " +#| "the instructions at :ref:`Packaging your project`. And once you're done, " +#| "don't forget to :ref:`do some research ` on how your package is received!" +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" +"Вы уже знаете, как упаковать приложение командной строки, написанное на " +"Python. Следующим шагом может быть распространение вашего пакета, то есть " +"загрузка его в :term:`package index `, чаще всего :term:`PyPI " +"`. Чтобы сделать это, следуйте инструкциям " +"в :ref:`Packaging your project`. И как только вы закончите, не " +"забудьте :ref:`do some research ` на " +"предмет того, как был принят ваш пакет!" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "Упаковка и распространение проектов" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "Устаревший" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "2023-12-14" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" +"В этом разделе рассматриваются некоторые дополнительные детали по настройке, " +"упаковке и распространению проектов Python с помощью ``setuptools``, которые " +"не были рассмотрены во вводном руководстве в :doc:`/tutorials/packaging-" +"projects``. При этом предполагается, что вы уже знакомы с содержанием " +"страницы :doc:`/tutorials/installing-packages`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" +"Этот раздел *не* ставит целью охватить лучшие практики разработки проектов " +"на Python в целом. Например, в нем нет руководства или рекомендаций по " +"инструментам для контроля версий, документации или тестирования." + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" +"Дополнительные справочные материалы см. в :std:doc:`Building and " +"Distributing Packages ` в :ref:`setuptools` " +"docs, но учтите, что некоторые рекомендации там могут быть устаревшими. В " +"случае возникновения противоречий отдавайте предпочтение советам в " +"руководстве пользователя по упаковке Python." + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "Требования к упаковке и распространению" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" +"Во-первых, убедитесь, что вы уже выполнили :ref:`требования к установке " +"пакетов `." + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "Установите «twine» [1]_:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" +"Он понадобится для загрузки вашего проекта :term:`distributions " +"<Дистрибутивный пакет>` в :term:`PyPI <Индекс пакетов Python (PyPI)>` " +"(см. :ref:`ниже <Загрузка проекта в PyPI>`)." + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"The most important file is :file:`setup.py` which exists at the root of your " +"project directory. For an example, see the `setup.py `_ " +"in the `PyPA sample project `_." +msgstr "" +"Наиболее важным файлом является :file:`setup.py`, который существует в корне " +"каталога вашего проекта. Для примера смотрите `setup.py `_ " +"в проекте-образце PyPA `_." + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "Файл :file:`setup.py` выполняет две основные функции:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" +"Это файл, в котором настраиваются различные аспекты вашего проекта. Главная " +"особенность :file:`setup.py` заключается в том, что он содержит глобальную " +"функцию ``setup()``. Ключевые слова-аргументы этой функции определяют " +"конкретные детали вашего проекта. Наиболее важные аргументы описаны " +"в :ref:`разделе ниже `." + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" +"Это интерфейс командной строки для запуска различных команд, связанных с " +"задачами упаковки. Чтобы получить список доступных команд, выполните команду " +"``python3 setup.py --help-commands``." + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" +":file:`setup.cfg` - это ini-файл, содержащий параметры по умолчанию для " +"команд :file:`setup.py`. Для примера смотрите файл `setup.cfg `_ в проекте-образце `PyPA `_." + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "README.rst / README.md" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" +"Все проекты должны содержать файл readme, в котором описывается цель " +"проекта. Наиболее распространенным форматом является `reStructuredText " +"`_ с расширением \"rst\", хотя это " +"не является обязательным условием; также поддерживаются различные варианты " +"`Markdown `_ (посмотрите на " +"аргумент ``setup()`` :ref:`long_description_content_type `)." + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" +"Для примера смотрите `README.md `_ из проекта-образца `PyPA `_." + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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:`setuptools` 0.6.27+, стандартные файлы readme " +"(:file:`README.rst`, :file:`README.txt` или :file:`README`) по умолчанию " +"включены в дистрибутивы исходных текстов. Встроенная " +"библиотека :ref:`distutils` перенимает это поведение начиная с Python 3.7. " +"Кроме того, :ref:`setuptools` 36.4.0+ будет включать :file:`README.md`, если " +"он будет найден. Если вы используете setuptools, вам не нужно указывать свой " +"файл readme в :file:`MANIFEST.in`. В противном случае включите его в явном " +"виде." + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "MANIFEST.in" + +#: ../source/guides/distributing-packages-using-setuptools.rst:113 +msgid "" +"A :file:`MANIFEST.in` is needed when you need to package additional files " +"that are not automatically included in a source distribution. For details " +"on writing a :file:`MANIFEST.in` file, including a list of what's included " +"by default, see \":ref:`Using MANIFEST.in`\"." +msgstr "" +"Файл :file:`MANIFEST.in` необходим, когда вам нужно упаковать дополнительные " +"файлы, которые не включены автоматически в дистрибутив. Подробнее о " +"написании файла :file:`MANIFEST.in`, включая список того, что включается по " +"умолчанию, смотрите в разделе \":ref:`Using MANIFEST.in`\"." + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" +"Однако вы можете не использовать :file:`MANIFEST.in`. Для примера, проект " +"примера `PyPA `_ удалил свой файл " +"манифеста, так как все необходимые файлы были включены в :ref:`setuptools` " +"43.0.0 и новее." + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" +":file:`MANIFEST.in' не влияет на бинарные дистрибутивы, такие как колеса." + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "LICENSE.txt" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" +"Каждый пакет должен содержать файл лицензии с подробным описанием условий " +"распространения. Во многих юрисдикциях пакеты без явной лицензии не могут " +"быть законно использованы или распространены кем-либо, кроме " +"правообладателя. Если вы не уверены, какую лицензию выбрать, вы можете " +"воспользоваться такими ресурсами, как `GitHub's Choose a License `_ или проконсультироваться с юристом." + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" +"Для примера смотрите `LICENSE.txt `_ из проекта-образца `PyPA `_." + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "<ваш пакет>" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" +"Хотя это и не обязательно, наиболее распространенной практикой является " +"включение ваших модулей и пакетов Python в один пакет верхнего уровня, " +"который имеет то же :ref:`имя `, что и ваш проект, или что-то " +"очень близкое." + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" +"В качестве примера можно привести пакет `sample `_, который входит в состав проекта-" +"образца PyPA `_." + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "Аргументы ``setup()``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" +"Как уже говорилось выше, главная особенность :file:`setup.py` заключается в " +"том, что он содержит глобальную функцию ``setup()``. Ключевые слова-" +"аргументы этой функции определяют конкретные детали вашего проекта." + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" +"Некоторые из них временно описаны ниже, пока информация о них не будет " +"перенесена в другое место. Полный список можно найти :doc:`в документации по " +"setuptools `." + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" +"Большинство приведенных фрагментов взяты из файла `setup.py `_, содержащегося в проекте-образце `PyPA `_." + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" +"Дополнительные сведения о том, как использовать версии для передачи " +"информации о совместимости пользователям, см. в :ref:`Выбор схемы " +"версионирования`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "``пакеты``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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:`packages ` в " +"вашем проекте, включая их подпакеты, подсубпакеты и т.д. Хотя пакеты можно " +"перечислить вручную, ``setuptools.find_packages()`` находит их " +"автоматически. Используйте ключевой аргумент ``include`` для поиска только " +"заданных пакетов. Используйте ключевой аргумент ``exclude`` для исключения " +"пакетов, которые не предназначены для выпуска и установки." + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +msgstr "``py_modules``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:198 +msgid "" +"If your project contains any single-file Python modules that aren't part of " +"a package, set ``py_modules`` to a list of the names of the modules (minus " +"the ``.py`` extension) in order to make :ref:`setuptools` aware of them." +msgstr "" +"Если ваш проект содержит однофайловые модули Python, которые не являются " +"частью пакета, установите ``py_modules`` в список имен модулей (за вычетом " +"расширения ``.py``), чтобы :ref:`setuptools`` узнал о них." + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +#, fuzzy +msgid "``install_requires``" +msgstr "install_requires" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" +"\"install_requires\" следует использовать, чтобы указать, какие зависимости " +"минимально необходимы проекту для запуска. Когда проект устанавливается с " +"помощью :ref:`pip`, именно эта спецификация используется для установки его " +"зависимостей." + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" +"Подробнее об использовании \"install_requires\" " +"смотрите :ref:`install_requires vs Requirements files`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "``package_data``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"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 "" +"Часто в :term:`пакет ` необходимо установить дополнительные " +"файлы. Эти файлы часто представляют собой данные, тесно связанные с " +"реализацией пакета, или текстовые файлы, содержащие документацию, которая " +"может быть интересна программистам, использующим пакет. Такие файлы " +"называются \"данными пакета\"." + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" +"Значение должно представлять собой отображение имени пакета на список " +"относительных имен путей, которые должны быть скопированы в пакет. Пути " +"интерпретируются как относительные к директории, содержащей пакет." + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" +"Дополнительную информацию см. в :std:doc:`Including Data Files " +"` из :std:doc:`setuptools docs " +"`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "``data_files``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" +"Хотя конфигурирования :ref:`Package Data` достаточно для большинства " +"потребностей, в некоторых случаях вам может понадобиться разместить файлы " +"данных *вне* вашего :term:`packages `. Директива " +"``data_files`` позволяет это сделать. В основном она полезна, если вам нужно " +"установить файлы, используемые другими программами, которые могут не знать о " +"пакетах Python." + +#: ../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 "" +"Каждая пара ``(директория, файлы)`` в последовательности указывает " +"директорию установки и файлы для установки. Каталог ``directory`` должен " +"быть относительным путем (хотя это может измениться в будущем, см. `wheel " +"Issue #92 `_), и он " +"интерпретируется относительно префикса установки (Python'овский " +"``sys.prefix`` для установки по умолчанию; ``site.USER_BASE`` для установки " +"пользователем). Каждое имя файла в ``files`` интерпретируется относительно " +"скрипта :file:`setup.py`` в верхней части исходного дистрибутива проекта." + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" +"Дополнительную информацию можно найти в разделе distutils на :ref:`Установка " +"дополнительных файлов `." + +#: ../source/guides/distributing-packages-using-setuptools.rst:274 +msgid "" +"When installing packages as egg, ``data_files`` is not supported. So, if " +"your project uses :ref:`setuptools`, you must use ``pip`` to install it. " +"Alternatively, if you must use ``python setup.py``, then you need to pass " +"the ``--old-and-unmanageable`` option." +msgstr "" +"При установке пакетов как яиц, ``data_files`` не поддерживается. Поэтому, " +"если ваш проект использует :ref:`setuptools`, то для его установки " +"необходимо использовать ``pip``. В противном случае, если вы должны " +"использовать ``python setup.py``, то вам нужно передать опцию ``-old-and-" +"unmanageable``." + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +#, fuzzy +msgid "``scripts``" +msgstr "scripts" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" +"Хотя ``setup()`` поддерживает ключевое слово :ref:`scripts " +"` для указания на готовые скрипты " +"для установки, рекомендуемый подход для достижения кроссплатформенной " +"совместимости - использовать точки входа :ref:`console_scripts` (см. ниже)." + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "Выбор схемы управления версиями" + +#: ../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 "" +"Информацию о распространенных схемах версий и о том, как выбирать между " +"ними, смотрите в : ссылка:`версионирование`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "Работа в «режиме разработки»" + +#: ../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/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" +"Чтобы установить пакет Python в режиме \"редактируемый\"/\"разработка\", " +"измените каталог на корень каталога проекта и выполните команду:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" +"Флаг командной строки pip ``-e`` - это сокращение от ``-editable``, а ``.`` " +"означает текущий рабочий каталог, так что вместе это означает установку " +"текущего каталога (т.е. вашего проекта) в режиме редактирования. При этом " +"также будут установлены все зависимости, объявленные с помощью " +"``install_requires``, и все скрипты, объявленные с помощью " +"``console_scripts``. Зависимости будут установлены в обычном, " +"нередактируемом режиме." + +#: ../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::" +msgstr "" +"Возможно, вы захотите установить некоторые из ваших зависимостей в " +"редактируемом режиме. Например, предположим, что ваш проект требует \"foo\" " +"и \"bar\", но вы хотите, чтобы \"bar\" устанавливался из VCS в редактируемом " +"режиме, тогда вы можете создать файл требований следующим образом::" + +#: ../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\" так, чтобы она выполнялась " +"из VCS, а не из PyPI." + +#: ../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 "" +"Если же вы хотите установить \"Бар\" из локальной директории в редактируемом " +"режиме, файл требований должен выглядеть следующим образом, с локальными " +"путями в верхней части файла::" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" +"В противном случае зависимость будет выполняться из PyPI, что обусловлено " +"порядком установки файла требований. Подробнее о файлах требований смотрите " +"раздел :ref:`Requirements File ` в документации " +"pip. Подробнее о VCS-установках смотрите в разделе :ref:`VCS Support " +"` документации pip." + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" +"Наконец, если вы не хотите устанавливать никаких зависимостей, вы можете " +"выполнить команду:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" +"Для получения дополнительной информации см. раздел :doc:`Режим разработки " +"` в :ref:`setuptools` docs." + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "Упаковка вашего проекта" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" +"Чтобы ваш проект можно было установить из индекса :term:`Package Index`, " +"например :term:`PyPI `, вам нужно будет " +"создать :term:`Distribution ` (он же \":term:`Package " +"`\") для вашего проекта." + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" +"Прежде чем вы сможете построить колеса и диски для своего проекта, вам нужно " +"будет установить пакет ``build``:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "Распространение в исходных кодах" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" +"Минимумом вы должны создать :термин:`Источник распределения <Источник " +"распределения (или \"сдист\")>`:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" +"Исходный дистрибутив\" является несобранным (т.е. не является :term:`Built " +"Distribution`) и требует шага сборки при установке с помощью pip. Даже если " +"дистрибутив является чистым Python (т.е. не содержит расширений), он все " +"равно требует сборки для создания метаданных установки из :file:`setup.py` и/" +"или :file:`setup.cfg`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "Колёса" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" +"Вы также должны создать колесо для своего проекта. Колесо - " +"это :term:`сборка пакета <Сборка дистрибутива>`, который может быть " +"установлен без необходимости проходить процесс \"сборки\". Установка колес " +"значительно быстрее для конечного пользователя, чем установка из исходного " +"дистрибутива." + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" +"Если ваш проект является чистым Python, то вы будете создавать :ref: «Чистый " +"Python Колесо» (см. раздел ниже) <Чистый Python Колеса>`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" +"Если ваш проект содержит компилированные расширения, то вы будете создавать " +"то, что называется:ref:`*Platform Wheel* (см. раздел ниже) `." + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" +"Если ваш проект также поддерживает Python 2 *и* не содержит расширений C, то " +"вам следует создать так называемое *универсальное колесо*, добавив следующее " +"в файл :file:`setup.cfg`:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" +"Используйте эту настройку только в том случае, если ваш проект не имеет " +"расширений на языке C *и* поддерживает Python 2 и 3." + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "Колёса чистого Python'а" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" +"* Чистые Python колеса* не содержат компилированных расширений, и поэтому " +"требуется только одно колесо Python." + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "Для построения колеса выполните:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" +"Пакет ``wheel`` определит, что код - это чистый Python, и создаст колесо, " +"названное так, чтобы его можно было использовать на любой установке Python " +"3. Подробнее об именовании файлов wheel смотрите в :pep:`425`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" +"Если вы запустите ``build`` без ``--wheel`` или ``--sdist``, он соберет оба " +"файла за вас; это полезно, когда вам не нужно несколько колес." + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "Платформо-зависимые колёса" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" +"*Платформенные колеса* - это колеса, которые специфичны для определенной " +"платформы, например Linux, macOS или Windows, обычно из-за содержания " +"скомпилированных расширений." + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" +"Пакет ``wheel`` определит, что код не является чистым Python, и создаст " +"колесо, названное так, что его можно использовать только на той платформе, " +"на которой оно было создано. Подробнее об именовании файлов wheel смотрите " +"в :pep:`425`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" +":term:`PyPI ` в настоящее время поддерживает " +"загрузку платформенных колес для Windows, macOS и мульти-дистро " +"``manylinux*`` ABI. Подробности о последнем определены в :pep:`513`." + +#: ../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 "" +"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 "" +"Когда вы выполнили команду создания дистрибутива, под корневым каталогом " +"вашего проекта был создан новый каталог ``dist/``. Именно в ней вы найдете " +"файл(ы) дистрибутива для загрузки." + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" +"Эти файлы создаются только тогда, когда вы выполняете команду создания " +"дистрибутива. Это означает, что при любом изменении исходного кода проекта " +"или конфигурации в файле :file:`setup.py` вам нужно будет заново создать эти " +"файлы, прежде чем вы сможете распространить изменения в PyPI." + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" +"Перед выпуском на основной PyPI-репо, вы можете предпочесть тренировку на " +"`PyPI test site `_, который чистится на " +"полурегулярной основе. Смотрите :ref:`using-test-pypi` о том, как настроить " +"свою конфигурацию для его использования." + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" +"На других ресурсах вы можете встретить упоминания об использовании ``python " +"setup.py register`` и ``python setup.py upload``. Эти методы регистрации и " +"загрузки пакетов **настоятельно не рекомендуются**, поскольку в некоторых " +"версиях Python они могут использовать HTTP-соединение с открытым текстом или " +"непроверенное HTTPS-соединение, что позволяет перехватить ваши имя " +"пользователя и пароль во время передачи." + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" +"Парсер reStructuredText, используемый на PyPI, - это **не** Sphinx! Кроме " +"того, для обеспечения безопасности всех пользователей, некоторые виды URL и " +"директив запрещены или удалены (например, директива ``...raw::``). **Перед " +"тем, как** попытаться загрузить свой дистрибутив, вы должны проверить, " +"действительны ли ваши краткие/длинные описания, указанные " +"в :file:`setup.py`. Это можно сделать, выполнив :std:doc:`twine check " +"` для файлов вашего пакета:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "Создание учётной записи" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" +"Во-первых, вам нужна учетная запись пользователя :term:`PyPI `. Вы можете создать учетную запись, используя форму на сайте " +"PyPI `_." + +#: ../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 "" +"Теперь вы создадите токен PyPI `API token`_, чтобы иметь возможность " +"безопасно загружать свой проект." + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" +"Перейдите на https://pypi.org/manage/account/#api-tokens и создайте новый " +"`API-токен`_; не ограничивайте его область действия конкретным проектом, " +"поскольку вы создаете новый проект." + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" +"**Не закрывайте страницу, пока не скопируете и не сохраните токен - больше " +"вы его не увидите**" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" +"Чтобы не копировать и не вставлять токен при каждой загрузке, вы можете " +"создать файл :file:`$HOME/.pypirc`:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" +"Более подробную информацию см. в :ref:`спецификации ` " +"для :file:`.pypirc`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "Загрузите свои дистрибутивы" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" +"После создания учетной записи вы можете загружать свои дистрибутивы " +"в :term:`PyPI `, используя :ref:`twine`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" +"Процесс загрузки релиза одинаков вне зависимости от того, существует ли уже " +"проект на PyPI - если его еще нет, он будет автоматически создан при " +"загрузке первого релиза." + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" +"Для второго и последующих релизов PyPI требует только, чтобы номер версии " +"нового релиза отличался от всех предыдущих релизов." + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" +"Вы можете убедиться, что ваш пакет успешно загружен, перейдя по URL-адресу " +"``https://pypi.org/project/``, где ``sampleproject`` - это " +"имя загруженного вами проекта. Возможно, потребуется минута или две, чтобы " +"ваш проект появился на сайте." + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" +"В зависимости от вашей платформы, для этого может потребоваться доступ root " +"или администратора. :ref:`pip` в настоящее время рассматривает возможность " +"изменить это, сделав пользовательскую установку поведением по умолчанию " +"`_." + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "Удаление поддержки старых версий Python'а" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" +"Возможность отказаться от поддержки старых версий Python предусмотрена " +"стандартной спецификацией :ref:`core-metadata` 1.2 с помощью " +"атрибута :ref:`\"Requires-Python\" `." + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" +"Установщики с метаданными 1.2+, такие как Pip, будут придерживаться этой " +"спецификации, определяя текущую среду выполнения Python и сравнивая ее с " +"требуемой версией в метаданных пакета. Если они не совпадают, то будет " +"предпринята попытка установить последний дистрибутив пакета, который " +"поддерживал эту среду выполнения Python." + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" +"Этот механизм можно использовать для отказа от поддержки старых версий " +"Python, изменив атрибут ``Requires-Python`` в метаданных пакета." + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "Требования" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" +"Этот рабочий процесс требует, чтобы пользователь, устанавливающий пакет, " +"использовал Pip [#]_ или другую программу установки, поддерживающую " +"спецификацию Metadata 1.2." + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "Работа с универсальными колесами" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" +"Традиционно проекты :ref:`setuptools`, предоставляющие код на Python, " +"семантически совместимый как с Python 2, так и с Python 3, " +"создают :term:`wheels `, в именах которых присутствует тег " +"``py2.py3``. При отказе от поддержки Python 2 важно не забыть изменить этот " +"тег на просто ``py3``. Часто его настраивают в :file:`setup.cfg` в разделе " +"``[bdist_wheel]``, установив ``universal = 1``." + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" +"Если вы используете этот метод, либо удалите эту опцию или секцию, либо явно " +"установите ``universal`` в ``0``:" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" +"Что касается :ref:`deprecated ` прямых вызовов " +"``setup.py``, передача флага ``--universal`` в командной строке может " +"отменить эту настройку." + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "Определение требуемой версии Python'а" + +#: ../source/guides/dropping-older-python-versions.rst:48 +msgid "1. Install twine" +msgstr "1. Установить шпагат" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "Убедитесь, что у вас есть шпагат последней версии. Шаги:" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "2. Укажите диапазоны версий поддерживаемых дистрибутивов Python'а" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" +"Устанавливает диапазоны версий, объявляющие, какие дистрибутивы Python " +"поддерживаются в :file:`pyproject.toml` вашего проекта. Поле " +"конфигурации :ref:`requires-python` соответствует полю метаданных " +"ядра :ref:`Requires-Python `:" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" +"Вы можете указать диапазон версий и правила исключения (в соответствии со " +"спецификацией :ref:`version-specifiers`), например, не ниже Python 3.9. Или, " +"по крайней мере, Python 3.7 и далее, пропуская точечные выпуски 3.7.0 и " +"3.7.1:" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" +"Если вы используете бэкенд сборки :ref:`setuptools`, обратитесь к " +"документации `dependency-management`_ за дополнительными опциями." + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" +"Избегайте добавления верхних границ к диапазонам версий, например, ``\">= " +"3.8, < 3.10\"``. Это может привести к различным ошибкам и конфликтам версий. " +"Дополнительную информацию см. в `discourse-discussion`_." + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "3. Перед публикацией проверьте метаданные" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" +"Внутри исходного пакета Python (zip- или tar-gz-файла, который вы " +"скачиваете) находится текстовый файл PKG-INFO." + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` 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 "" +"Этот файл генерируется :term:`build backend ` при создании " +"исходного пакета. Файл содержит набор ключей и значений, список ключей " +"является частью стандартного формата метаданных PyPA." + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "Вы можете увидеть содержимое сгенерированного файла следующим образом:" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" +"Перед публикацией пакета убедитесь, что все перечисленное ниже на месте:" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" +"Если вы выполнили обновление правильно, значение ``Metadata-Version`` должно " +"быть 1.2 или выше." + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" +"Поле ``Requires-Python`` установлено и соответствует вашей спецификации в " +"файле конфигурации." + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "4. Публикация пакета" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "Действуйте, как указано в :ref:`Uploading your Project to PyPI`." + +#: ../source/guides/dropping-older-python-versions.rst:120 +msgid "Dropping a Python version" +msgstr "Отказ от версии Python" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" +"В принципе, по крайней мере, поддержка версий Python в метаданных должна " +"сохраняться как можно дольше, потому что после отказа от неё люди, всё ещё " +"зависящие от версии, будут вынуждены перейти на новую версию. Если же " +"поддержка конкретной версии становится препятствием для новых возможностей " +"или возникают другие проблемы, метаданные ``Requires-Python`` должны быть " +"изменены. Конечно, это также зависит от того, должен ли проект быть " +"стабильным и хорошо покрытым для более широкого круга пользователей." + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" +"Каждое изменение совместимости версий должно иметь свой собственный релиз." + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" +"При отказе от версии Python может быть полезно обновить синтаксис кода " +"проекта в целом, помимо обновления версий, используемых в видимых местах " +"(например, в тестовой среде). Такие инструменты, как pyupgrade_ или `ruff " +"`_, могут автоматизировать часть этой " +"работы." + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "В Pip 9.0 добавлена поддержка спецификации Metadata 1.2." + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "Создание собственного простого хранилища" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" +"Если вы хотите разместить свой собственный простой репозиторий [1]_, вы " +"можете использовать пакет программного обеспечения, например:doc:`devpi " +"` или вы можете просто создать правильную структуру каталога и " +"использовать любой веб-сервер, который может обслуживать статические файлы и " +"генерировать автоиндекс." + +#: ../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:" +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." +msgstr "" +"Кроме того, **высоко** рекомендуется, чтобы вы служили своему репозиторию с " +"действительным HTTPS. В настоящее время безопасность установок вашего " +"пользователя зависит от всех репозиториев, использующих действительную " +"настройку HTTP." + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "Хранилище \"Руководство\"" + +#: ../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/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`_, вы просто запустите ``twistd " +"-n web --path .``, а затем попросите пользователей добавить URL в " +"конфигурацию их программы установки." + +#: ../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 ":ссылка:`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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" +"множественные индексы с наследованием, с синхронизацией, репликацией, " +"отказоустойчивостью; зеркалирование" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr ": ссылка:`simpleindex" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr ":ссылка:`pypiserver`" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr ":ссылка:`pypiprivate`" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr ":ссылка:`pypicloud`" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" +"не поддерживается; также кэшированное проксирование; аутентификация, " +"авторизация" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr ":ссылка:`pywharf`" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "не поддерживается; служебные файлы на GitHub" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr ":ссылка:`pulppython`" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "также зеркалирование, проксирование; плагин для Pulp" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr ":ссылка:`pip2pi`" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "также зеркальное отображение; ручная синхронизация" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr ":ссылка:`dumb-pypi`" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "не сервер, а генератор сайтов со статическими файлами" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr ": ссылка:`httpserver`" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "стандартная библиотека" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "`Apache `_" + +#: ../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 "" +"Используя `мод_перезаписи `_ и `мод_кэш_диска `_, вы можете кэшировать запросы к индексам пакетов " +"через сервер Apache" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" +"Полную документацию по протоколу простого репозитория смотрите " +"в :ref:`simple repository API `." + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" +"Может быть настроен на возврат к PyPI (или другому индексу пакетов), если " +"запрашиваемый пакет отсутствует." + +#: ../source/guides/index.rst:4 +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`." +msgstr "" +"**Руководства** направлены на выполнение конкретной задачи и предполагают, " +"что вы уже знакомы с основами упаковки в Python. Если вы ищете введение в " +"упаковку, смотрите :doc:`/tutorials/index`." + +#: ../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-08" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" +"Зеркалирование или кэширование PyPI (и других : термин:`индексов пакетов " +"<Пакетный индекс>`) может быть использовано для ускорения локальной " +"установки пакетов, для работы в автономном режиме, для работы с " +"корпоративными брандмауэрами или для обычного интернет-флакинга." + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "В этой области существует несколько классов опций:" + +#: ../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 "" +"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/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/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" +"pip предоставляет ряд возможностей для ускорения установки за счет " +"использования локальных кэшированных копий :term:`packages `:" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" +":ref:`Быстрая и локальная установка ` за " +"счет загрузки всех требований для проекта и последующего указания pip на эти " +"загруженные файлы вместо обращения к PyPI." + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" +"Вариант вышеописанного, который предварительно собирает установочные файлы в " +"соответствии с требованиями, используя :ref:`python3 -m pip wheel `:" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "Кэш" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" +"множественные индексы с наследованием; синхронизация, репликация, обход " +"отказа; загрузка пакетов" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr ":ссылка:`bandersnatch`" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" +"Пользовательский плагин включает кэширование; перенаправление к другим " +"индексам пакетов" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "не поддерживается; аутентификация, авторизация" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "плагин для Pulp; несколько проксированных индексов; загрузка пакетов" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr ":ссылка:`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 ": ссылка:`nginx_pypi_cache`" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr ":ссылка:`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 "" +"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 "" +"Научное программное обеспечение, как правило, имеет более сложные " +"зависимости, чем большинство других, и часто имеет несколько вариантов " +"сборки, чтобы использовать преимущества различных видов оборудования или " +"взаимодействовать с различными частями внешнего программного обеспечения." + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" +"В частности, `NumPy `__, который является основой для " +"большинства программ в научном стеке Python `_, может быть настроен на взаимодействие с различными " +"библиотеками FORTRAN и может использовать преимущества различных уровней " +"векторизованных инструкций, доступных в современных процессорах." + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" +"Начиная с версии 1.10.4 NumPy и версии 1.0.0 SciPy, на PyPI доступны " +"предварительно собранные 32- и 64-битные двоичные файлы в формате ``колеса'' " +"для всех основных операционных систем (Windows, macOS и Linux). Обратите " +"внимание, однако, что в Windows двоичные файлы NumPy скомпонованы с " +"библиотекой BLAS/LAPACK `ATLAS `__, " +"ограниченной инструкциями SSE2, поэтому они могут не обеспечивать " +"оптимальную производительность линейной алгебры." + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" +"Существует несколько альтернативных вариантов получения научных библиотек " +"Python (или любых других библиотек Python, которые требуют среды компиляции " +"для установки из исходного кода и не предоставляют предварительно собранные " +"файлы wheel на PyPI)." + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "Создание из исходников" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" +"Та же сложность, которая затрудняет распространение NumPy (и многих " +"проектов, зависящих от него) в виде файлов на колесах, также затрудняет их " +"самостоятельную сборку из исходных текстов. Однако для смельчаков, готовых " +"потратить время на работу с компиляторами и компоновщиками для C и FORTRAN, " +"сборка из исходных текстов - это всегда вариант." + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +msgstr "Распространяемые пакеты Linux" + +#: ../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/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/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "Установщики Windows" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" +"Многие Python-проекты, которые в настоящее время не публикуют (или не могут " +"опубликовать) файлы wheel, по крайней мере, публикуют инсталляторы для " +"Windows, либо на PyPI, либо на странице загрузки проекта. Использование этих " +"инсталляторов позволяет пользователям избежать необходимости создавать " +"подходящее окружение для локальной сборки расширений." + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" +"Расширения, предоставляемые в этих установщиках, обычно совместимы с " +"установщиками CPython для Windows, опубликованными на python.org." + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" +"Как и в случае с системными пакетами Linux, программы установки Windows " +"будут устанавливаться только в системную установку Python - они не " +"поддерживают установку в виртуальных средах. Предоставление доступа к " +"дистрибутивам, установленным в системный Python, при использовании " +"виртуальных сред - распространенный подход к обходу этого ограничения." + +#: ../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` также предоставляет подкоманду :command:`wheel " +"convert`, которая может преобразовать установщик " +"Windows :command:`bdist_wininst` в wheel." + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +msgstr "Установщики и менеджеры пакетов macOS" + +#: ../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) публикуют " +"инсталляторы для macOS, совместимые с двоичными файлами macOS CPython, " +"опубликованными на python.org." + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" +"Пользователи macOS также имеют доступ к пакетным менеджерам в стиле " +"дистрибутива Linux, таким как ``Homebrew``. На сайте SciPy есть более " +"подробная информация об использовании Homebrew для `установки SciPy на macOS " +"`_." + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "Дистрибутивы SciPy" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" +"На сайте SciPy перечислены `несколько дистрибутивов `_, которые предоставляют полный стек SciPy конечным пользователям " +"в удобном для использования и обновления формате." + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" +"Некоторые из этих дистрибутивов могут быть несовместимы со стандартным " +"инструментарием на базе ``pip`` и ``virtualenv``." + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "Spack" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" +"`Spack `_ - это гибкий менеджер пакетов, " +"разработанный для поддержки множества версий, конфигураций, платформ и " +"компиляторов. Он был создан для удовлетворения потребностей крупных " +"суперкомпьютерных центров и команд разработчиков научных приложений, которым " +"часто приходится собирать программное обеспечение разными способами. Spack " +"не ограничивается Python; он может устанавливать пакеты для ``C``, ``C++``, " +"``Fortran``, ``R`` и других языков. Spack является неразрушающим; установка " +"новой версии одного пакета не нарушает существующие установки, поэтому на " +"одной системе может сосуществовать множество конфигураций." + +#: ../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 " +"также генерирует файлы *модулей*, чтобы пакеты можно было загружать и " +"выгружать из окружения пользователя." + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "Кроссплатформенный менеджер пакетов conda" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" +"``conda`` - это система управления пакетами с открытым исходным кодом " +"(лицензия BSD) и система управления окружением, которая позволяет " +"пользователям устанавливать несколько версий бинарных программных пакетов и " +"их зависимостей, а также легко переключаться между ними. Это " +"кроссплатформенный инструмент, работающий под Windows, MacOS и Linux. Conda " +"может использоваться для упаковки и распространения всех видов пакетов, она " +"не ограничивается только пакетами Python. Она имеет полную поддержку " +"собственных виртуальных сред. Conda делает окружения гражданами первого " +"класса, позволяя легко создавать независимые окружения даже для библиотек на " +"Си. Она написана на Python, но является Python-агностичной. Conda управляет " +"самим Python как пакетом, поэтому возможна команда :`conda update python`, в " +"отличие от pip, который управляет только пакетами Python." + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" +"Anaconda `Anaconda `_ - дистрибутив " +"Python, опубликованный компанией Anaconda, Inc. Это стабильная коллекция " +"пакетов с открытым исходным кодом для работы с большими данными и научными " +"исследованиями, а также набор утилит с графическим интерфейсом для " +"управления средами conda." + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" +"В дополнение к полному дистрибутиву, предоставляемому Anaconda, сам менеджер " +"пакетов conda доступен в `miniconda `_, `miniforge `_ и `pixi " +"`_." + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" +"Пакеты Conda доступны по нескольким каналам на Anaconda.org, включая канал " +"по умолчанию, поддерживаемый Anaconda, Inc, канал conda-forge, " +"поддерживаемый сообществом, который предоставляет широкий спектр " +"предварительно созданных пакетов, а также некоторые коллекции пакетов, " +"специфичные для конкретного домена." + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "Установка отдельных инструментов командной строки" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" +"Многие пакеты предоставляют приложения командной строки. Примерами таких " +"пакетов являются: `mypy `_, `flake8 `_, `black `_ " +"и :ref:`pipenv`." + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" +"Обычно вы хотите иметь доступ к этим приложениям из любой точки системы, но " +"установка пакетов и их зависимостей в одно и то же глобальное окружение " +"может привести к конфликту версий и нарушению зависимостей операционной " +"системы от пакетов Python." + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" +":ref:`pipx` решает эту проблему, создавая виртуальное окружение для каждого " +"пакета, а также обеспечивая доступ к его приложениям через каталог, который " +"находится в вашем ``$PATH``. Это позволяет обновлять или удалять каждый " +"пакет, не вызывая конфликтов с другими пакетами, и позволяет безопасно " +"запускать приложения из любого места." + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "pipx работает только с Python 3.6+." + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "pipx устанавливается вместе с pip:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" +"``ensurepath`` гарантирует, что каталог приложения находится в вашем " +"``$PATH``. Возможно, вам потребуется перезапустить терминал, чтобы " +"обновление вступило в силу." + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" +"Теперь вы можете устанавливать пакеты с помощью ``pipx install`` и запускать " +"приложения пакета из любого места." + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "Например:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" +"Чтобы посмотреть список пакетов, установленных с помощью pipx, и доступных " +"приложений, используйте ``pipx list``:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "Чтобы обновить или удалить пакет:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "pipx можно обновить или удалить с помощью pip:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" +"pipx также позволяет установить и запустить последнюю версию приложения во " +"временной, эфемерной среде. Например:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" +"Чтобы увидеть полный список команд, которые предлагает pipx, выполните " +"команду:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +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 "Установка pip/setuptools/wheel через менеджеры пакетов Linux" + +#: ../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 section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" +"В этом разделе рассказывается о том, как " +"установить :ref:`pip`, :ref:`setuptools` и :ref:`wheel` с помощью менеджеров " +"пакетов Linux." + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" +"Если вы используете Python, загруженный с сайта `python.org `_, то этот раздел не применим. Вместо этого смотрите " +"раздел :ref:`installing_requirements`." + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +msgstr "" +"Обратите внимание, что обычно версии :ref:`pip`, :ref:`setuptools` " +"и :ref:`wheel`, поддерживаемые конкретным дистрибутивом Linux, устаревают к " +"моменту его публичного выпуска, а обновления обычно происходят только по " +"соображениям безопасности, а не для обновления функций. Для некоторых " +"дистрибутивов существуют дополнительные репозитории, которые могут быть " +"включены для получения более новых версий. Репозитории, о которых мы знаем, " +"описаны ниже." + +#: ../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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "Fedora" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" +"Чтобы узнать больше о Python в Fedora, посетите `официальную документацию " +"Fedora`_, `Python Classroom`_ или `Fedora Loves Python`_." + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "CentOS/RHEL" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" +"CentOS и RHEL не предлагают :ref:`pip` или :ref:`wheel` в своих основных " +"репозиториях, хотя :ref:`setuptools` установлен по умолчанию." + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "Чтобы установить pip и wheel для системы Python, есть два варианта:" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" +"Включите `репозиторий EPEL `_, " +"используя `эти инструкции `__. На EPEL 7 вы можете установить pip и wheel следующим образом:" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" +"Поскольку EPEL предлагает только дополнительные, не противоречащие друг " +"другу пакеты, EPEL не предлагает setuptools, поскольку он находится в " +"основном репозитории." + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" +"Включите `PyPA Copr Repo `_, используя `эти инструкции `__ [1]_. Вы можете установить pip и " +"wheel следующим образом:" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "Чтобы дополнительно обновить setuptools, запустите:" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" +"Чтобы установить pip, wheel и setuptools в параллельном, несистемном " +"окружении (с помощью yum), есть два варианта:" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" +"Используйте функцию \"Коллекции программ\", чтобы включить параллельную " +"коллекцию, включающую pip, setuptools и wheel." + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" +"Для Redhat смотрите здесь: https://developers.redhat.com/products/" +"softwarecollections/overview" + +#: ../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 "Помните, что коллекции могут содержать не самые последние версии." + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" +"Включите `IUS-репозиторий `_ и установите один из " +"`параллельно устанавливаемых `_ Pythons, а также pip, setuptools и wheel, которые поддерживаются " +"в актуальном состоянии." + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "Например, для Python 3.4 на CentOS7/RHEL7:" + +#: ../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 "" +"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 "" +"В последних версиях Debian/Ubuntu pip был модифицирован, чтобы по умолчанию " +"использовать `\"Схему пользователя\" `_, что является значительным изменением " +"поведения, которое может быть неожиданным для некоторых пользователей." + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "Arch Linux" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +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" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +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" + +#: ../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 "Использование и создание файла требований" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" +"Это руководство относится к поддерживаемым версиям Python, в настоящее время " +"3.8 и выше." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" +"В этом руководстве используется термин **упаковка** для обозначения " +"термина :термин: \" Пакет распределения \" , который обычно устанавливается " +"из внешнего хоста. Это отличается от термина :term:`Import Package', который " +"относится к модулям импорта в исходном коде Python." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" +"Это руководство содержит обязательное условие - использование официальной " +"версии Python, полученной по адресу . " +"Если вы используете менеджер пакетов вашей операционной системы для " +"установки Python, пожалуйста, убедитесь, что Python установлен, прежде чем " +"приступать к выполнению этих шагов." + +#: ../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 "" +":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 "" +":ref:`venv` (для Python 3) позволяет управлять отдельными установками " +"пакетов для разных проектов. Она создает \"виртуальную\" изолированную " +"установку Python. При смене проекта вы можете создать новую виртуальную " +"среду, изолированную от других виртуальных сред. Вы получаете преимущество " +"от виртуальной среды, так как пакеты можно устанавливать уверенно и они не " +"будут мешать среде другого проекта." + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" +"Чтобы создать виртуальную среду, перейдите в каталог вашего проекта и " +"выполните следующую команду. Это создаст новое виртуальное окружение в " +"локальной папке с именем ``.venv``:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" +"Второй аргумент - это место создания виртуального окружения. Как правило, вы " +"можете просто создать его в своем проекте и назвать ``.venv``." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "``venv`` создаст виртуальную установку Python в папке ``.venv``." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" +"Вы должны исключить каталог виртуального окружения из системы контроля " +"версий с помощью ``.gitignore`` или аналогичного инструмента." + +#: ../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 "" +"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 "" +"Прежде чем вы начнете устанавливать или использовать пакеты в виртуальной " +"среде, ее нужно будет ``активировать``. Активация виртуальной среды поместит " +"специфические для виртуальной среды исполняемые файлы ``python`` и ``pip`` в " +"``PATH`` вашей оболочки." + +#: ../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 "" +"Чтобы убедиться, что виртуальная среда активирована, проверьте расположение " +"вашего интерпретатора Python:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" +"Пока виртуальная среда активна, приведенная выше команда выведет путь к " +"файлу, включающий каталог ``.venv``, заканчивающийся следующим образом:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" +"Пока виртуальная среда активирована, pip будет устанавливать пакеты в эту " +"среду. Это позволит вам импортировать и использовать пакеты в вашем " +"приложении Python." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "Деактивация виртуальной среды" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" +"Если вы хотите сменить проект или покинуть виртуальную среду, " +"``деактивируйте`` среду:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" +"Закрытие оболочки приведет к деактивации виртуальной среды. Если вы откроете " +"новое окно оболочки и захотите использовать виртуальную среду, активируйте " +"ее снова." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "Повторная активация виртуальной среды" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" +"Если вы хотите повторно активировать существующую виртуальную среду, " +"следуйте тем же инструкциям по активации виртуальной среды. Создавать новую " +"виртуальную среду не нужно." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" +":ref:`pip` - эталонный менеджер пакетов Python. Он используется для " +"установки и обновления пакетов в виртуальной среде." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" +"Python установщики для macOS включают pip. На Linux вам, возможно, придется " +"установить дополнительный пакет, такой как ``python3-pip``. Вы можете " +"убедиться, что pip обновляется при запуске:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" +"После этого на вашем пользовательском сайте должна быть установлена " +"последняя версия pip:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" +"Установщики Python для Windows включают 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" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" +"Когда ваша виртуальная среда активирована, вы можете устанавливать пакеты. " +"Для установки пакетов используйте команду ``pip install``." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "Установить пакет" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +#, fuzzy +#| msgid "" +#| "For example,let's install the `Requests`_ library from the :term:`Python " +#| "Package Index (PyPI)`:" +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" +"Например, давайте установим библиотеку `Requests`_ из :term:`Python Package " +"Index (PyPI)`:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "pip должен загружать запросы и все его зависимости и устанавливать их:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "Установить конкретную версию пакета" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" +"pip позволяет указать, какую версию пакета следует установить, " +"используя :term:`определители версии <Определитель версии>`. Например, чтобы " +"установить определенную версию пакета ``requests``:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "Чтобы установить последний ``2.x`` выпуск requests:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" +"Чтобы установить предварительные версии пакетов, используйте флаг ``--pre``:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +msgid "Install extras" +msgstr "Установка дополнительных" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" +"Некоторые пакеты содержат дополнительные `extras`_. Вы можете указать pip на " +"их установку, указав в скобках дополнительное дополнение:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "Установите пакет из исходного кода" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" +"pip может установить пакет непосредственно из его исходного кода. Например, " +"чтобы установить исходный код в каталог ``google-auth``:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +msgid "" +"Additionally, pip can install packages from source in :doc:`development mode " +"`, meaning that changes to the source " +"directory will immediately affect the installed package without needing to " +"re-install:" +msgstr "" +"Кроме того, pip может устанавливать пакеты из исходного кода в :doc:`режиме " +"разработки `, что означает, что " +"изменения в каталоге исходного кода немедленно повлияют на установленный " +"пакет без необходимости повторной установки:" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" +"pip может устанавливать пакеты непосредственно из их системы контроля " +"версий. Например, вы можете установить пакет непосредственно из репозитория " +"git:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" +"Дополнительную информацию о поддерживаемых системах контроля версий и " +"синтаксисе см. в документации pip по :ref:`VCS Support `." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "Установка из локального архива" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" +"Если у вас есть локальная копия архива :term:`Distribution Package` (файл " +"zip, wheel или tar), вы можете установить его напрямую с помощью pip:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" +"Если у вас есть каталог, содержащий архивы нескольких пакетов, вы можете " +"указать pip искать пакеты там и не использовать :term:`Python Package Index " +"(PyPI)` вообще:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" +"Это полезно, если вы устанавливаете пакеты на систему с ограниченными " +"возможностями подключения или хотите строго контролировать происхождение " +"дистрибутивных пакетов." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "Установка из других индексов пакетов" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" +"Если вы хотите загрузить пакеты из индекса, отличного от " +"индекса :term:`Python Package Index (PyPI)`, вы можете использовать флаг ``--" +"index-url``:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" +"Если вы хотите разрешить пакеты как из :term:`Python Package Index (PyPI)`, " +"так и из отдельного индекса, вы можете использовать флаг ``--extra-index-" +"url`` вместо этого:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "Обновление пакетов" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" +"pip может обновлять пакеты на месте, используя флаг ``--upgrade``. Например, " +"для установки последней версии ``requests`` и всех его зависимостей:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "Использование файла требований" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" +"Вместо того чтобы устанавливать пакеты по отдельности, pip позволяет " +"объявить все зависимости в :ref:`Requirements File `. Например, вы можете создать файл :file:`requirements.txt`, " +"содержащий:" + +#: ../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 "" +"И укажите pip установить все пакеты из этого файла, используя флаг ``-r``:" + +#: ../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 "" +"Pip can export a list of all installed packages and their versions using the " +"``freeze`` command:" +msgstr "" +"Pip может экспортировать список всех установленных пакетов и их версий с " +"помощью команды ``freeze``:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 +msgid "Which will output a list of package specifiers such as:" +msgstr "Что выведет список спецификаторов пакетов, например:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" +"Команда ``pip freeze`` полезна для создания :ref:`pip:Requirements Files``, " +"которые могут воссоздать точные версии всех пакетов, установленных в " +"окружении." + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "Установка пакетов с помощью virtualenv" + +#: ../source/guides/installing-using-virtualenv.rst:4 +msgid "" +"This guide discusses how to install packages using :ref:`pip` " +"and :ref:`virtualenv`, a tool to create isolated Python environments." +msgstr "" +"В этом руководстве рассказывается о том, как устанавливать пакеты с " +"помощью :ref:`pip` и :ref:`virtualenv`, инструмента для создания " +"изолированных окружений Python." + +#: ../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` " +"находится в стадии разработки. Пожалуйста, обратитесь к документации " +"по :ref:`virtualenv` для получения подробной информации об установке и " +"использовании." + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" +"В этом документе термин **пакет** используется для " +"обозначения :term:`Distribution Package`, который отличается " +"от :term:`Import Package`, который используется для импорта модулей в " +"исходный код Python." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "Примеры лицензирования и пользовательские сценарии" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +#, fuzzy +#| msgid "" +#| ":pep:`639` has specified the way to declare a project's license and paths " +#| "to license files and other legally required information. This document " +#| "aims to provide clear guidance how to migrate from the legacy to the " +#| "standardized way of declaring licenses. Make sure your preferred build " +#| "backend supports :pep:`639` before trying to apply the newer guidelines. " +#| "As of February 2025, :doc:`setuptools ` and :ref:`flit ` don't " +#| "support :pep:`639` yet." +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" +"В :pep:`639` указан способ объявления лицензии проекта, пути к файлам " +"лицензии и другая юридически необходимая информация. Этот документ призван " +"дать четкое руководство по переходу от устаревшего к стандартизированному " +"способу объявления лицензий. Убедитесь, что ваш бэкенд сборки " +"поддерживает :pep:`639`, прежде чем пытаться применить новые рекомендации. " +"По состоянию на февраль 2025 года, :doc:`setuptools ` и :ref:`flit ` пока не " +"поддерживают :pep:`639`." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "Примеры лицензирования" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "Базовый пример" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" +"Сам проект Setuptools, начиная с `версии 75.6.0 `__, не " +"использует поле ``Лицензия`` в собственных метаданных источника проекта. " +"Кроме того, он больше не указывает явно ``license_file``/ ``license_files``, " +"как это было раньше, поскольку Setuptools полагается на собственное " +"автоматическое включение файлов, связанных с лицензией, соответствующих " +"общим шаблонам, таким как файл :file:`LICENSE``, который он использует." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" +"Он включает следующие связанные с лицензией метаданные в " +"свой :file:`pyproject.toml`:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" +"Самый простой переход на PEP 639 будет заключаться в использовании этого " +"варианта:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" +"Или, если проект использовал :file:`setup.cfg`, в его таблице ``[metadata]``:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +#, fuzzy +#| msgid "" +#| "The output Core Metadata for the distribution packages would then be:" +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" +"Выходные метаданные Core Metadata для дистрибутивных пакетов будут такими:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" +"Файл :file:`LICENSE` будет храниться по адресу :file:`/setuptools-{VERSION}/" +"LICENSE` в sdist и :file:`/setuptools-{VERSION}.dist-info/licenses/LICENSE` " +"в wheel, и распаковываться оттуда в каталог сайта (например, :file:`site-" +"packages/`) при установке; :file:/` - корень соответствующего архива, а " +"``{VERSION}`` - версия выпуска Setuptools. например, :file:`site-packages/`) " +"при установке; :file:`/` - корень соответствующего архива, а ``{VERSION}`` - " +"версия релиза Setuptools в метаданных ядра." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "Расширенный пример" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" +"Предположим, что Setuptools должна включить лицензии сторонних проектов, " +"которые хранятся в каталогах :file:`setuptools/_vendor/` " +"и :file:`pkg_resources/_vendor/`; а именно:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +#, fuzzy +#| msgid "Some additional examples of valid ``License-Expression`` values:" +msgid "The appropriate license expressions are:" +msgstr "" +"Некоторые дополнительные примеры допустимых значений ``License-Expression``:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" +"Всеобъемлющее выражение лицензии, охватывающее как собственно Setuptools, " +"так и его вендовые зависимости, будет содержать эти метаданные, объединяя " +"все выражения лицензии в одно. Такое выражение может быть следующим:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" +"Кроме того, согласно требованиям лицензий, в пакет должны быть включены " +"соответствующие файлы лицензий. Допустим, файл :file:`LICENSE` содержит " +"текст лицензии MIT и авторские права, используемые Setuptools, " +"``pyparsing``, ``more_itertools`` и ``ordered-set``; а " +"файлы :file:`LICENSE*` в каталоге :file:`setuptools/_vendor/packaging/` " +"содержат текст лицензии Apache 2.0 и 2 пункта лицензии BSD, а также " +"заявление об авторских правах Packaging и уведомление о выборе лицензии " +"`__." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" +"В частности, мы предполагаем, что файлы лицензий расположены по следующим " +"путям в дереве исходных текстов проекта (относительно корня проекта " +"и :file:`pyproject.toml`):" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" +"Если собрать все это вместе, то наш :file:`pyproject.toml` будет иметь вид:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" +"Или же файлы лицензии можно указать явно (пути будут интерпретированы как " +"glob-шаблоны):" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" +"Если бы наш проект использовал :file:`setup.cfg`, мы могли бы определить это " +"в :" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" +"При любом из этих подходов выходные метаданные Core Metadata в дистрибутиве " +"будут такими:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" +"В полученном sdist, с :file:`/` в качестве корня архива и ``{VERSION}`` " +"версией выпуска Setuptools, указанной в Core Metadata, файлы лицензий будут " +"расположены по путям:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" +"В собранном колесе, где :file:`/` является корнем архива, а ``{VERSION}`` - " +"предыдущей, файлы лицензии будут храниться по адресу:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" +"Наконец, в установленном проекте, где :file:`site-packages/` является диром " +"сайта, а ``{VERSION}`` - предыдущей версией, файлы лицензии будут " +"установлены в:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "Примеры выражений" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" +"Некоторые дополнительные примеры допустимых значений ``License-Expression``:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "Пользовательские сценарии" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" +"Ниже рассматривается ряд распространенных случаев использования с точки " +"зрения пользователя и даются рекомендации по каждому из них. Обратите " +"внимание, что нижеследующее **не** должно рассматриваться как юридическая " +"консультация, и читатели должны проконсультироваться с лицензированным " +"юристом в своей юрисдикции, если они не уверены в специфике своей ситуации." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "У меня есть частный пакет, который не будет распространяться" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" +"Если ваш пакет не будет распространяться публично, то есть за пределами " +"вашей компании, организации или домохозяйства, то *обычно* нет необходимости " +"включать официальную лицензию, так что вам не придется делать здесь ничего " +"лишнего." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" +"Тем не менее, не лишним будет включить ``LicenseRef-Proprietary`` в качестве " +"выражения лицензии в конфигурацию пакета, и/или заявление об авторских " +"правах и любые юридические уведомления в файл :file:`LICENSE.txt` в корне " +"каталога вашего проекта, который будет автоматически включен средствами " +"упаковки." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "Я просто хочу поделиться своими работами без юридических ограничений" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" +"Хотя вы не обязаны включать лицензию, если вы ее не включите, ни у кого не " +"будет `никакого разрешения на скачивание, использование или улучшение вашей " +"работы `__, так что это, вероятно, *противоположное* " +"тому, что вы на самом деле хотите. Лицензия Массачусетского технологического " +"института `__ - отличный выбор, поскольку она проста, " +"широко используется и позволяет любому делать с вашей работой все, что он " +"захочет (кроме как подать на вас в суд, чего вы, вероятно, тоже не хотите)." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" +"Чтобы применить его, просто вставьте ``текст ``__ в файл " +"с именем :file:`LICENSE.txt`` в корне вашего репо, и добавьте год и ваше имя " +"в строку копирайта. Затем просто добавьте ``license = \"MIT\"`` под " +"``[project]`` в ваш :file:`pyproject.toml`, если ваш инструмент упаковки " +"поддерживает это, или в его конфигурационный файл/раздел. Все готово!" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "Я хочу распространять свой проект под определенной лицензией" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" +"Чтобы использовать определенную лицензию, просто вставьте ее текст в " +"файл :file:`LICENSE.txt` в корне вашего репозитория, если он еще не " +"находится в файле, начинающемся с :file:`LICENSE` или :file:`COPYING`, и " +"добавьте ``license = \"LICENSE-ID\"`` под ``[project]`` в " +"вашем :file:`pyproject.toml`, если ваш инструмент упаковки поддерживает это, " +"или в другом случае в его конфигурационном файле. Вы можете найти ``LICENSE-" +"ID`` и копируемый текст лицензии на сайтах вроде `ChooseALicense " +"`__ или `SPDX `__." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" +"Многие популярные хостинги кода, шаблоны проектов и средства упаковки могут " +"добавить файл лицензии за вас, а в будущем, возможно, будут поддерживать и " +"выражение." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "Я поддерживаю существующий пакет, который уже лицензирован" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" +"Если в вашем проекте уже есть лицензионные файлы и метаданные, то вам нужно " +"будет внести всего пару изменений, чтобы воспользоваться новой " +"функциональностью." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +#, fuzzy +#| msgid "" +#| "In your project config file, enter your license expression under " +#| "``license`` (``[project]`` table in :file:`pyproject.toml`), or the " +#| "equivalent for your packaging tool, and make sure to remove any legacy " +#| "``license`` table subkeys or ``License ::`` classifiers. Your existing " +#| "``license`` value may already be valid as one (e.g. ``MIT``, ``Apache-2.0 " +#| "OR BSD-2-Clause``, etc); otherwise, check the `SPDX license list " +#| "`__ for the identifier that matches the license used in your " +#| "project." +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" +"В конфигурационном файле проекта введите выражение лицензии в ``license`` " +"(таблица ``[project]`` в :file:`pyproject.toml`) или эквивалентное выражение " +"для вашего инструмента упаковки, и убедитесь, что удалили все устаревшие " +"подключи таблицы ``license`` или классификаторы ``License ::``. Возможно, " +"существующее значение ``лицензии`` уже является действительным (например, " +"``MIT``, ``Apache-2.0 OR BSD-2-Clause`` и т. д.); в противном случае " +"проверьте список лицензий `__ для идентификатора, который " +"соответствует лицензии, используемой в вашем проекте." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" +"Убедитесь, что вы перечислили файлы лицензий в разделе ``license-files`` под " +"``[project]`` в :file:`pyproject.toml` или в другом файле конфигурации " +"вашего инструмента." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" +"Смотрите :ref:`licensing-example-basic` для простой, но полной демонстрации " +"того, как это работает на практике. См. также руководство по переводу " +"классификаторов лицензий в выражения лицензий, предоставленное " +"авторами :pep:`639`: `Mapping License Classifiers to SPDX Identifiers " +"`__. Средства упаковки могут поддерживать " +"автоматическое преобразование устаревших лицензионных метаданных; для " +"получения дополнительной информации обратитесь к документации вашего " +"средства." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "Мой пакет включает в себя другой код под разными лицензиями" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" +"Если ваш проект включает в себя код, полученный от других людей, на которые " +"распространяются разные лицензии, например, зависимые файлы или файлы, " +"скопированные из других программ с открытым исходным кодом, вы можете " +"построить лицензионное выражение, чтобы описать соответствующие лицензии и " +"отношения между ними." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +#, fuzzy +#| msgid "" +#| "In short, ``License-1 AND License-2`` mean that *both* licenses apply to " +#| "your project, or parts of it (for example, you included a file under " +#| "another license), and ``License-1 OR License-2`` means that *either* of " +#| "the licenses can be used, at the user's option (for example, you want to " +#| "allow users a choice of multiple licenses). You can use parenthesis " +#| "(``()``) for grouping to form expressions that cover even the most " +#| "complex situations." +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" +"Вкратце, ``Лицензия-1 И Лицензия-2`` означает, что *обе* лицензии применимы " +"к вашему проекту или его части (например, вы включили файл под другой " +"лицензией), а ``Лицензия-1 ИЛИ Лицензия-2`` означает, что *любая* из " +"лицензий может быть использована по выбору пользователя (например, вы хотите " +"предоставить пользователям возможность выбора из нескольких лицензий). Вы " +"можете использовать круглые скобки (``()``) для группировки, чтобы " +"сформировать выражения, которые охватывают даже самые сложные ситуации." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" +"В файле конфигурации проекта введите выражение лицензии в ``license`` " +"(таблица ``[project]`` в :file:`pyproject.toml`), или эквивалентное " +"выражение для вашего инструмента упаковки, и убедитесь, что вы удалили все " +"устаревшие подключи таблицы ``license`` или классификаторы ``License ::``." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" +"Также убедитесь, что вы добавили полный текст всех лицензий в виде файлов " +"куда-то в репозиторий вашего проекта. Укажите относительный путь или glob-" +"шаблоны к каждому из них в ``license-files`` в ``[project]`` " +"в :file:`pyproject.toml` (если ваш инструмент поддерживает это), или в " +"другом конфигурационном файле вашего инструмента." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" +"Например, если ваш проект имеет лицензию MIT, но включает зависимость от " +"поставщика (скажем, ``упаковку''), которая лицензируется либо под Apache " +"2.0, либо под BSD с двумя оговорками, ваше выражение лицензии будет ``MIT " +"AND (Apache-2.0 OR BSD-2-Clause)``. У вас может быть :file:`LICENSE.txt` в " +"корне репо, а также :file:`LICENSE-APACHE.txt` и :file:`LICENSE-BSD.txt` в " +"подкаталоге :file:`_vendor/`, поэтому, чтобы включить их все, вы укажете " +"``[\"LICENSE. txt\", \"_vendor/packaging/LICENSE*\"]`` как glob-шаблоны, или " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` как буквальные пути к файлам." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" +"Смотрите полностью проработанный пример :ref:`licensing-example-advanced` " +"для комплексного применения этого метода в реальном сложном проекте, с " +"множеством технических деталей, а также обратитесь к `учебнику " +"`__ для получения дополнительной помощи и примеров " +"использования идентификаторов и выражений SPDX." + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "Создание дружественного к PyPI файла README" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" +"Файлы README могут помочь вашим пользователям понять ваш проект и могут быть " +"использованы для создания описания вашего проекта на PyPI. Это руководство " +"поможет вам создать README в удобном для PyPI формате и включить README в " +"ваш пакет, чтобы он появился на PyPI." + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "Создание файла :file:`README`" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" +"Файлы README для проектов Python часто называются ``README``, " +"``README.txt``, ``README.rst`` или ``README.md``." + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" +"Чтобы ваш README правильно отображался на PyPI, выберите язык разметки, " +"поддерживаемый PyPI. Форматы, поддерживаемые `PyPI's README renderer " +"`_, следующие:" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "простой текст" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" +"`reStructuredText `_ (без " +"расширений Sphinx)" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" +"текст в формате Markdown (`GitHub Flavored Markdown `_ по умолчанию или `CommonMark `_)" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" +"Обычно файл README сохраняется в корне проекта, в той же директории, что и " +"файл :file:`setup.py`." + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "Включение файла README в метаданные вашего пакета" + +#: ../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 в описание пакета, установите метаданные " +"проекта ``Description`` и ``Description-Content-Type``, обычно в файле " +"проекта :file:`setup.py``." + +#: ../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/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" +"Например, чтобы установить эти значения в файле пакета :file:`setup.py`, " +"используйте ``setup()`` ``long_description`` и " +"``long_description_content_type``." + +#: ../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``." +msgstr "" +"Установите значение ``long_description`` в содержимое (не путь) самого файла " +"README. Установите значение ``long_description_content_type`` в принятый " +"стиль ``Content-Type`` для разметки вашего файла README, например ``text/" +"plain``, ``text/x-rst`` (для reStructuredText) или ``text/markdown``." + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" +"Если для написания описания проекта вы используете Markdown со вкусом " +"GitHub, убедитесь, что вы обновили следующие инструменты:" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" +"Минимально необходимыми версиями соответствующих инструментов являются:" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" +"Рекомендуется использовать ``twine`` для загрузки дистрибутивных пакетов " +"проекта:" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" +"Например, смотрите этот файл :file:`setup.py`, который считывает " +"содержимое :file:`README.md` как ``длинное_описание`` и идентифицирует " +"разметку как GitHub-flavored Markdown:" + +#: ../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 "" +"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 "" +"Если ваш README написан на reStructuredText, то любая некорректная разметка " +"не позволит его отобразить, в результате чего PyPI просто покажет исходный " +"текст README." + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" +"Обратите внимание, что расширения Sphinx, используемые в документах, такие " +"как :doc:`directives ` " +"и :doc:`roles ` (например, " +"\"``:py:func:`getattr``\" или \"``:ref:`my-reference-label``\"), здесь " +"недопустимы и приведут к сообщениям об ошибках типа \"``Ошибка: Неизвестная " +"интерпретируемая текстовая роль \"py:func\".``\"." + +#: ../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/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +msgstr "" +"Установите последнюю версию `twine `_; " +"требуется версия 1.12.0 или выше:" + +#: ../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 "" +"Соберите sdist и wheel для вашего проекта, как описано в " +"разделе :ref:`Packaging Your Project`." + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "Запустите ``twine check`` на sdist и wheel:" + +#: ../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/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 "" +":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/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 "" +"С сентября 2016 года платформой загрузки по умолчанию является ``pypi.org``." + +#: ../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`` была *отключена* с **июля 3 июля 2017 " +"года**. По состоянию на 13 апреля 2018 года URL-адресом PyPI является " +"``pypi.org``." + +#: ../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/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" +"Настройки загрузки по умолчанию переключились на ``pypi.org`` в следующих " +"версиях:" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../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 "" +"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 "" +"Помимо того, что вы находитесь на достаточно новой версии инструмента, чтобы " +"его значение по умолчанию изменилось, вы также должны убедиться, что не " +"настроили инструмент на переопределение URL-адреса загрузки по умолчанию. " +"Обычно это настраивается в файле, расположенном по " +"адресу :file:`$HOME/.pypirc`. Если вы видите файл вида:" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" +"Затем просто удалите строку, начинающуюся с ``repository``, и вы будете " +"использовать URL по умолчанию вашего инструмента загрузки." + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +msgstr "" +"Если по каким-то причинам вы не можете обновить версию вашего инструмента до " +"версии, которая по умолчанию использует PyPI.org, то вы можете " +"отредактировать :file:`$HOME/.pypirc` и включить строку ``repository:``, но " +"вместо нее использовать значение ``https://upload.pypi.org/legacy/``:" + +#: ../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 "" +"(``legacy`` в этом URL означает, что это новая реализация сервера, " +"эмулирующая API загрузки старой реализации сервера)" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "Регистрация имён и метаданных пакетов" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" +"Явная предварительная регистрация имен пакетов с помощью команды ``setup.py " +"register`` перед первой загрузкой больше не требуется, и в настоящее время " +"не поддерживается эмуляцией устаревшего API загрузки на PyPI.org." + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" +"В результате попытка явной регистрации после перехода на использование " +"PyPI.org для загрузки приведет к следующему сообщению об ошибке::" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" +"Решение состоит в том, чтобы пропустить шаг регистрации и перейти " +"непосредственно к загрузке артефактов." + +#: ../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 "" +"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 (testpypi.python.org) больше не доступен; вместо него " +"используйте `test.pypi.org `_. Если вы используете " +"TestPyPI, вы должны обновить свой :file:`$HOME/.pypirc` для соответствия " +"новому местоположению TestPyPI, заменив ``https://testpypi.python.org/pypi`` " +"на ``https://test.pypi.org/legacy/``, например:" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "Регистрация новых учётных записей пользователей" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" +"Для того, чтобы помочь смягчить спам-атаки на PyPI, регистрация новых " +"пользователей через ``pypi.python.org`` была *отключена* с **февраля 20, " +"2018**. Регистрация новых пользователей на ``pypi.org`` открыта." + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "Просмотр пакетов" + +#: ../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." +msgstr "" +"Хотя ``pypi.python.org`` по-прежнему может использоваться в ссылках из " +"другой документации PyPA и т.д., по умолчанию для просмотра пакетов " +"используется интерфейс ``pypi.org``. Домен pypi.python.org сейчас " +"перенаправляет на pypi.org, и может быть отключен в будущем." + +#: ../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 "``pypi.org`` является хостом по умолчанию для загрузки пакетов." + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "Управление опубликованными пакетами и выпусками" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +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/modernize-setup-py-project.rst:12 +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`." +msgstr "" +"Настоятельно рекомендуется наличие файла :term:`pyproject.toml`. Само по " +"себе наличие файла :file:`pyproject.toml` мало что дает. [#]_ Что " +"действительно настоятельно рекомендуется, так это таблица ``[build-system]`` " +"в :file:`pyproject.toml`." + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" +"Обратите внимание, что это влияет на функцию изоляции сборки в pip, см. ниже." + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" +"Нет, :file:`setup.py` может существовать в современном проекте, основанном " +"на :ref:`setuptools`. Файл :term:`setup.py` является допустимым " +"конфигурационным файлом для setuptools, который, как оказалось, написан на " +"Python. Однако следующие команды устарели и **НЕ ДОЛЖНЫ** больше " +"выполняться, и вместо них следует использовать рекомендуемые команды-" +"заменители:" + +#: ../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 "" +"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 "" +"Термин :term:`project` должен содержать в корне дерева исходников " +"файл :file:`pyproject.toml`, который содержит таблицу ``[build-system]``, " +"как показано ниже:" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" +"Это стандартный способ сообщить :term:`build frontends ` о " +"том, что :ref:`setuptools` является :term:`build backend ` " +"для этого проекта." + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" +"Обратите внимание, что наличие файла :file:`pyproject.toml` (даже если он " +"пуст) заставляет :ref:`pip` изменить свое поведение по умолчанию на " +"использование *изоляции сборки*." + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr ":ref:`distributing-packages`" + +#: ../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-сборка-система-таблица`" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +#, fuzzy +#| msgid ":doc:`pip:reference/build-system/pyproject-toml`" +msgid ":doc:`pip:reference/build-system`" +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 "" +"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 "" +"Помимо самой setuptools, если :file:`setup.py` зависит от других сторонних " +"библиотек (вне стандартной библиотеки Python), они должны быть перечислены в " +"списке ``requires`` таблицы ``[build-system]``, чтобы фронтенд сборки знал, " +"что их нужно установить при сборке :term:`distributions `." + +#: ../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/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" +"требует наличия такого файла :file:`pyproject.toml` (:file:`setup.py` " +"остается неизменным):" + +#: ../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 "" +"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 "" +"Обычно фронтенды сборки создают эфемерное виртуальное окружение, в котором " +"устанавливают только те зависимости сборки (и их зависимости), которые " +"перечислены в ``build-system.requires``, и запускают сборку в этом окружении." + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" +"Для некоторых проектов эта изоляция нежелательна, и ее можно отключить " +"следующим образом:" + +#: ../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/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" +"Все статические метаданные по желанию могут быть перенесены в таблицу " +"``[проект]`` в :file:`pyproject.toml`." + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" +"может быть полностью заменен файлом :file:`pyproject.toml`, например, таким:" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" +"Читайте :ref:`pyproject-project-table` для полной спецификации содержимого, " +"допустимого в таблице ``[project]``." + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "Как обрабатывать динамические метаданные?" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" +"Если некоторые поля метаданных упаковки не являются статическими, их нужно " +"указать как ``динамические`` в этой таблице ``[проект]``." + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "можно модернизировать следующим образом:" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr ":ref:`декларирование метаданных проекта-динамический`" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" +"Что делать, если что-то, что нельзя изменить, ожидает файл ``setup.py``?" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" +"Например, существует процесс, который нельзя легко изменить, и ему нужно " +"выполнить команду типа ``python setup.py --name``." + +#: ../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:`setup.py` в дереве исходников " +"проекта даже после того, как все его содержимое было перемещено " +"в :file:`pyproject.toml`. Этот файл может быть таким минималистичным:" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr ":ref:`pyproject-toml-spec`" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr ":doc:`setuptools:build_meta`" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "Установка нескольких версий" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" +"easy_install позволяет одновременно устанавливать различные версии одного и " +"того же проекта в единое окружение, разделяемое несколькими программами, " +"которые должны ``требовать`` соответствующую версию проекта во время " +"выполнения (используя ``pkg_resources``)." + +#: ../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." +msgstr "" +"Для многих случаев использования виртуальные среды решают эту задачу без " +"усложнения директивы ``require``. Однако преимущество параллельной установки " +"в одной среде заключается в том, что она работает для среды, разделяемой " +"несколькими приложениями, например, для системы Python в дистрибутиве Linux." + +#: ../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." +msgstr "" +"Основное ограничение параллельной установки на основе ``pkg_resources`` " +"заключается в том, что как только вы импортируете ``pkg_resources``, он " +"фиксирует *default* версию всего, что уже доступно в sys.path. Это может " +"вызвать проблемы, поскольку скрипты командной строки, созданные " +"``setuptools``, используют ``pkg_resources`` для поиска точки входа для " +"выполнения. Это означает, что, например, вы не сможете использовать тесты " +"``require``, вызываемые через ``nose``, или приложения WSGI, вызываемые " +"через ``gunicorn``, если вашему приложению нужна версия, отличная от той, " +"что доступна по умолчанию в стандартном ``sys.path`` - скриптовая обертка " +"для основного приложения заблокирует версию, доступную по умолчанию, и " +"последующий вызов ``require`` в вашем собственном коде завершится с ложным " +"конфликтом версий." + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" +"Это можно обойти, установив все зависимости в ``__main__.__requires__`` " +"перед первым импортом ``pkg_resources``, но такой подход означает, что " +"стандартные вызовы командной строки соответствующих инструментов не могут " +"быть использованы - необходимо написать собственный сценарий-обертку или " +"использовать ``python3 -c ''`` для прямого вызова основной точки " +"входа приложения." + +#: ../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" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" +"Одна из особенностей эталонного интерпретатора CPython заключается в том, " +"что, помимо возможности выполнения кода Python, он также предоставляет " +"богатый C API для использования другими программами. Одно из наиболее " +"распространенных применений этого C API - создание импортируемых расширений " +"C, которые позволяют делать вещи, которые не всегда легко реализовать в " +"чистом коде Python." + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "Обзор двоичных расширений" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "Варианты использования" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" +"Типичные случаи использования бинарных расширений делятся всего на три " +"условные категории:" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" +"**Модули ускорителей**: эти модули полностью автономны и создаются " +"исключительно для того, чтобы работать быстрее, чем эквивалентный код на " +"чистом Python в CPython. В идеале, модули-ускорители всегда должны иметь " +"эквивалент на чистом Python, который можно использовать в качестве запасного " +"варианта, если ускоренная версия недоступна на данной системе. В стандартной " +"библиотеке CPython широко используются модули-ускорители. *Пример*: При " +"импорте ``datetime`` Python возвращается к модулю ``datetime.py `_, если реализация на C " +"( ``_datetimemodule.c `_) недоступна." + +#: ../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 `_." +msgstr "" +"**модули-обертки**: эти модули создаются для раскрытия существующих " +"интерфейсов C в коде Python. Они могут либо напрямую раскрывать основной " +"интерфейс C, либо раскрывать более \"питоновский\" API, который использует " +"возможности языка Python, чтобы сделать API проще в использовании. В " +"стандартной библиотеке CPython широко используются модули-обертки. *Пример*: " +"`functools.py `_ - это модуль-обертка Python для `_functoolsmodule.c `_." + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" +"**низкоуровневый доступ к системе**: эти модули создаются для доступа к " +"функциям нижнего уровня среды выполнения CPython, операционной системы или " +"базового оборудования. С помощью специфического для платформы кода модули " +"расширения могут достигать того, что невозможно в чистом коде Python. Ряд " +"модулей стандартной библиотеки CPython написан на языке C, чтобы получить " +"доступ к внутренним функциям интерпретатора, которые не раскрываются на " +"уровне языка. *Пример*: ``Sys``, который берется из `sysmodule.c `_." + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" +"Особенно примечательной особенностью расширений на C является то, что, когда " +"им не нужно возвращаться во время выполнения интерпретатора, они могут " +"освободить глобальную блокировку интерпретатора CPython для длительных " +"операций (независимо от того, связаны ли эти операции с процессором или IO)." + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" +"Не все модули расширения будут четко вписываться в вышеперечисленные " +"категории. Например, модули расширения, входящие в состав NumPy, охватывают " +"все три варианта использования - они переносят внутренние циклы на C по " +"соображениям скорости, оборачивают внешние библиотеки, написанные на C, " +"FORTRAN и других языках, и используют низкоуровневые системные интерфейсы " +"как для CPython, так и для базовой операционной системы, чтобы поддерживать " +"одновременное выполнение векторных операций и жестко контролировать точное " +"расположение в памяти созданных объектов." + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "Недостатки" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" +"Основным недостатком использования бинарных расширений является то, что это " +"затрудняет последующее распространение программного обеспечения. Одним из " +"преимуществ использования Python является то, что он в значительной степени " +"кроссплатформенный, а языки, используемые для написания модулей расширения " +"(обычно это C или C++, но на самом деле любой язык, который может " +"связываться с CPython C API), обычно требуют создания собственных двоичных " +"файлов для разных платформ." + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "Это означает, что двоичные расширения:" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" +"требуют, чтобы конечные пользователи могли либо собрать их из исходных " +"текстов, либо чтобы кто-то опубликовал предварительно собранные двоичные " +"файлы для распространенных платформ" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" +"может быть несовместим с различными сборками эталонного интерпретатора " +"CPython" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" +"часто не будет корректно работать с альтернативными интерпретаторами, такими " +"как PyPy, IronPython или Jython" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" +"при ручном кодировании усложняют сопровождение, требуя, чтобы сопровождающие " +"были знакомы не только с Python, но и с языком, использованным для создания " +"бинарного расширения, а также с деталями CPython C API." + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" +"если предусмотрена обратная реализация на чистом Python, усложняет " +"сопровождение, требуя, чтобы изменения были реализованы в двух местах, и " +"вносит дополнительные сложности в набор тестов, чтобы гарантировать, что обе " +"версии всегда выполняются." + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" +"Еще одним недостатком использования бинарных расширений является то, что " +"альтернативные механизмы импорта (например, возможность импортировать модули " +"непосредственно из zip-файлов) часто не работают для модулей расширений " +"(поскольку механизмы динамической загрузки на большинстве платформ могут " +"загружать библиотеки только с диска)." + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "Альтернативы ручному написанию ускоряющих модулей" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" +"Если модули расширения используются только для ускорения работы кода (после " +"того как профилирование выявило код, где увеличение скорости стоит " +"дополнительных усилий по сопровождению), следует рассмотреть и ряд других " +"альтернатив:" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" +"искать существующие оптимизированные альтернативы. Стандартная библиотека " +"CPython содержит ряд оптимизированных структур данных и алгоритмов (особенно " +"во встроенных модулях и модулях ``коллекции`` и ``итертулы``). Индекс " +"пакетов Python также предлагает дополнительные альтернативы. Иногда " +"правильный выбор стандартной библиотеки или стороннего модуля позволяет " +"избежать необходимости создания собственного модуля-ускорителя." + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" +"Для долго работающих приложений JIT-компилируемый интерпретатор `PyPy " +"`__ может стать подходящей альтернативой стандартной " +"среде выполнения CPython. Основным препятствием для внедрения PyPy обычно " +"является зависимость от других бинарных модулей расширения - хотя PyPy и " +"эмулирует CPython C API, модули, полагающиеся на него, создают проблемы для " +"PyPy JIT, а слой эмуляции часто может выявить скрытые дефекты в модулях " +"расширения, к которым CPython в настоящее время терпим (часто вокруг ошибок " +"подсчета ссылок - объект с одной живой ссылкой вместо двух часто ничего не " +"нарушает, но отсутствие ссылок вместо одной является большой проблемой)." + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" +"`Cython `__ - это зрелый статический компилятор, " +"который может компилировать большинство кода Python в модули расширения C. " +"Первоначальная компиляция обеспечивает некоторое увеличение скорости (минуя " +"слой интерпретатора CPython), а дополнительные функции статической типизации " +"Cython могут предложить дополнительные возможности для увеличения скорости. " +"Использование Cython все еще имеет недостатки, связанные с использованием " +"бинарных расширений, но имеет преимущество в виде снижения барьера входа для " +"программистов на Python (по сравнению с другими языками, такими как C или C+" +"+)." + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" +"`Numba `__ - это новый инструмент, созданный " +"членами научного Python-сообщества, цель которого - использовать LLVM для " +"выборочной компиляции частей Python-приложения в нативный машинный код во " +"время выполнения. Он требует, чтобы LLVM был доступен в системе, на которой " +"выполняется код, но может обеспечить значительное увеличение скорости, " +"особенно для операций, которые поддаются векторизации." + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "Альтернативы ручному написанию модулей-обёрток" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" +"C ABI (Application Binary Interface) - это общий стандарт для совместного " +"использования функциональности несколькими приложениями. Одной из сильных " +"сторон CPython C API (Application Programming Interface) является " +"возможность использования этой функциональности пользователями Python. " +"Однако создавать модули вручную довольно утомительно, поэтому следует " +"рассмотреть ряд других альтернативных подходов." + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" +"Описанные ниже подходы не упрощают ситуацию с дистрибутивами, но они *могут* " +"значительно снизить нагрузку на поддержку модулей-оберток в актуальном " +"состоянии." + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" +"Помимо того, что `Cython `__ полезен для создания " +"модулей ускорителей, он также широко используется для создания модулей-" +"оберток для API на C или C++. Это предполагает обертывание интерфейсов " +"вручную, что дает широкую свободу в проектировании и оптимизации кода " +"обертки, но может быть не лучшим выбором для быстрого обертывания очень " +"больших API. См. `список сторонних инструментов `_ для автоматического обертывания с помощью Cython. Он " +"также поддерживает ориентированные на производительность реализации Python, " +"которые предоставляют CPython-подобный C-API, такие как PyPy и Pyston." + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" +":doc:`pybind11 ` - это чистая библиотека C++11, которая " +"предоставляет чистый C++ интерфейс к CPython (и PyPy) C API. Она не требует " +"предварительной обработки и написана полностью на шаблонизированном C++. В " +"комплект включены помощники для сборки Setuptools или CMake. Он был основан " +"на `Boost.Python `__, но не требует библиотек Boost или BJam." + +#: ../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 "" +":doc:`cffi ` - это проект, созданный некоторыми разработчиками " +"PyPy, чтобы упростить разработчикам, которые уже знают Python и C, " +"возможность использовать свои C-модули в Python-приложениях. Он также " +"позволяет относительно просто обернуть модуль на Си на основе его " +"заголовочных файлов, даже если вы сами не знаете Си." + +#: ../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." +msgstr "" +"Одним из ключевых преимуществ ``cffi`` является его совместимость с PyPy " +"JIT, что позволяет модулям-оберткам CFFI полноценно участвовать в JIT-" +"оптимизации трассировки PyPy." + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" +"`SWIG `__ - это генератор интерфейсов-оберток, который " +"позволяет различным языкам программирования, включая Python, " +"взаимодействовать с кодом на C и C++." + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" +"Модуль ``ctypes'' стандартной библиотеки, хотя и полезен для получения " +"доступа к интерфейсам уровня C, когда информация о заголовках недоступна, " +"страдает от того, что он работает исключительно на уровне C ABI, и поэтому " +"не имеет автоматической проверки согласованности между интерфейсом, " +"фактически экспортируемым библиотекой, и интерфейсом, объявленным в коде " +"Python. В отличие от этого, все вышеперечисленные альтернативы способны " +"работать на уровне C *API*, используя заголовочные файлы C для обеспечения " +"согласованности между интерфейсом, экспортируемым обертываемой библиотекой, " +"и интерфейсом, ожидаемым модулем-оберткой Python. Хотя ``cffi`` *может* " +"работать непосредственно на уровне C ABI, он страдает от тех же проблем " +"несогласованности интерфейсов, что и ``ctypes``, когда его используют таким " +"образом." + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "Альтернативы для низкоуровневого доступа к системе" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" +"Для приложений, которым нужен низкоуровневый доступ к системе (независимо от " +"причины), модуль бинарного расширения часто *является* лучшим способом " +"решения этой проблемы. Это особенно верно для низкоуровневого доступа к " +"самой среде выполнения CPython, поскольку некоторые операции (например, " +"снятие глобальной блокировки интерпретатора) просто недействительны, когда " +"интерпретатор выполняет код, даже если для получения доступа к " +"соответствующим интерфейсам C API используется модуль типа ``ctypes`` или " +"``cffi``." + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" +"Для случаев, когда модуль расширения манипулирует базовой операционной " +"системой или аппаратным обеспечением (а не средой выполнения CPython), " +"иногда лучше просто написать обычную библиотеку на C (или библиотеку на " +"другом системном языке программирования, например C++ или Rust, который " +"может экспортировать ABI, совместимый с C), а затем использовать одну из " +"описанных выше техник обертывания, чтобы сделать интерфейс доступным в " +"качестве импортируемого модуля Python." + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "Реализация двоичных расширений" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" +"Руководство CPython :doc:`Extending and Embedding ` " +"включает в себя введение в написание модуля расширения :doc:`custom " +"extension module in C `." + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" +"FIXME: Уточните, что все это - одна из причин, почему вы, вероятно, *не* " +"хотите вручную кодировать свои модули расширения :)" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "Жизненный цикл модуля расширения" + +#: ../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/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "Последствия общего статического состояния и субинтерпретаторов" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "Последствия GIL" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "API для распределения памяти" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "Совместимость ABI" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" +"CPython C API не гарантирует стабильность ABI между минорными версиями (3.2, " +"3.3, 3.4 и т.д.). Это означает, что, как правило, если вы собираете модуль " +"расширения для одной версии Python, он гарантированно будет работать только " +"с той же минорной версией Python, но не с любыми другими минорными версиями." + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" +"В Python 3.2 появился Limited API, который представляет собой четко " +"определенное подмножество API Python на языке C. Символы, необходимые для " +"Limited API, образуют \"Стабильный ABI\", который гарантированно совместим " +"со всеми версиями Python 3.x. Колеса, содержащие расширения, созданные на " +"основе стабильного ABI, используют тег ``abi3`` ABI, чтобы показать, что они " +"совместимы со всеми версиями Python 3.x." + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" +"Страница CPython :doc:`C API stability` содержит " +"подробную информацию о гарантиях стабильности 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: Покройте сборки-бэкенды, доступные для сборки расширений." + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "Создание расширений для нескольких платформ" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" +"Если вы планируете распространять свое расширение, вам следует " +"предоставить :term:`wheels ` для всех платформ, которые вы " +"собираетесь поддерживать. Обычно они создаются на основе систем непрерывной " +"интеграции (CI). Существуют инструменты, которые помогут вам собрать " +"перераспределяемые двоичные файлы из CI; к ним относятся :ref:`cibuildwheel` " +"и :ref:`multibuild`." + +#: ../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::" +msgstr "" +"Для большинства расширений вам потребуется создать колеса для всех платформ, " +"которые вы собираетесь поддерживать. Это означает, что количество колес, " +"которые вам нужно построить, складывается из::" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" +"Использование CPython :ref:`Stable ABI ` может " +"значительно сократить количество колес, которые вам нужно предоставить, так " +"как одно колесо на платформе может использоваться со всеми минорными " +"версиями Python, устраняя одно измерение матрицы. Это также избавляет от " +"необходимости генерировать новые колеса для каждой новой минорной версии " +"Python." + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "Двоичные расширения для Windows" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" +"Прежде чем приступить к созданию бинарного расширения, необходимо убедиться, " +"что у вас есть подходящий компилятор. В Windows для сборки официального " +"интерпретатора CPython используется Visual C, который следует использовать " +"для сборки совместимых бинарных расширений. Чтобы создать среду сборки для " +"бинарных расширений, установите `Visual Studio Community Edition `__ - подойдет любая последняя версия." + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" +"Одна оговорка: если вы используете Visual Studio 2019 или более позднюю " +"версию, ваше расширение будет зависеть от \"дополнительного\" файла, " +"``VCRUNTIME140_1.dll``, в дополнение к ``VCRUNTIME140.dll``, от которого " +"зависят все предыдущие версии, начиная с 2015 года. Это добавит " +"дополнительные требования к использованию вашего расширения в версиях " +"CPython, которые не включают этот дополнительный файл. Чтобы избежать этого, " +"вы можете добавить аргумент времени компиляции ``/d2FH4-``. Последние версии " +"Python могут включать этот файл." + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" +"Сборка для Python до версии 3.5 не рекомендуется, поскольку старые версии " +"Visual Studio больше не поставляются компанией Microsoft. Если вам все же " +"необходимо собирать для старых версий, вы можете установить " +"``DISTUTILS_USE_SDK=1`` и ``MSSdk=1`` для принудительного поиска текущей " +"активированной версии MSVC, а также проявить осторожность при разработке " +"расширения, чтобы не расшаривать/свобождать память в разных библиотеках, не " +"полагаться на измененные структуры данных и так далее. Инструменты для " +"генерации модулей расширения обычно позволяют избежать этих проблем." + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "Двоичные расширения для Linux" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" +"Для совместимости с более старыми дистрибутивами Linux двоичные файлы должны " +"использовать достаточно старый glibc. Docker-образы `manylinux `_ предоставляют среду сборки с достаточно старой " +"glibc для поддержки большинства современных дистрибутивов Linux на " +"распространенных архитектурах." + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "Двоичные расширения для macOS" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" +"Совместимость бинарных файлов на macOS определяется целевой минимальной " +"системой развертывания, например *10.9*, которая часто указывается с помощью " +"переменной окружения ``MACOSX_DEPLOYMENT_TARGET`` при сборке бинарных файлов " +"на macOS. При сборке с помощью setuptools / distutils цель развертывания " +"указывается с помощью флага ``--plat-name``, например ``macosx-10.9-" +"x86_64``. Об общих целях развертывания для дистрибутивов macOS Python см. в " +"`MacPython Spinning Wheels wiki `_." + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "Публикация двоичных расширений" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" +"Публикация бинарных расширений через PyPI использует те же механизмы " +"загрузки, что и публикация пакетов чистого Python. Вы создаете wheel-файл " +"для своего расширения с помощью build-бэкенда и загружаете его в PyPI с " +"помощью :doc:`twine `." + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "Избегайте выпуска только бинарных релизов" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +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/packaging-binary-extensions.rst:381 +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." +msgstr "" +"Кросс-платформенная разработка и распространение модулей расширения - " +"сложная тема, поэтому в данном руководстве основное внимание уделено " +"указателям на различные инструменты, автоматизирующие решение основных " +"технических проблем. Дополнительные ресурсы в этом разделе предназначены для " +"разработчиков, желающих больше узнать о базовых бинарных интерфейсах, на " +"которые опираются эти системы во время выполнения." + +#: ../source/guides/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "Кросс-платформенная генерация колёс при помощи scikit-build" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" +"Пакет `scikit-build `_ " +"помогает абстрагироваться от кроссплатформенных операций сборки и " +"предоставляет дополнительные возможности при создании пакетов бинарных " +"расширений. Также доступна дополнительная документация по `C runtime, " +"компилятору и генератору системы сборки `_ для бинарных модулей расширения Python." + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "Введение в модули расширения на C/C++" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" +"Для более подробного объяснения того, как модули расширения используются в " +"CPython на системе Debian, смотрите следующие статьи:" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" +"Что такое модули расширения (c)python? `_" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "`Освобождение gil `_" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" +"`Написание модулей расширения cpython с использованием C++ `_" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "Дополнительные соображения для бинарных колес" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" +"Сайт `pypackaging-native `_ содержит " +"дополнительные сведения об упаковке пакетов Python с нативным кодом. Его " +"цель - предоставить обзор наиболее важных вопросов упаковки для таких " +"проектов, а также подробные объяснения и ссылки." + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" +"Например, рассматриваются такие темы, как зависимости, не компилируемые в " +"Python (\"нативные зависимости\"), важность ABI (Application Binary " +"Interface) нативного кода, зависимости от SIMD-кода и кросс-компиляция." + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "Упаковка пакетов пространства имён" + +#: ../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 "" +"Пакеты пространства имен позволяют разделить подпакеты и модули " +"одного :term:`пакета <Импортный пакет>` на несколько " +"отдельных :term:`дистрибутивных пакетов <Дистрибутивный пакет>` (во " +"избежание двусмысленности в этом документе они называются " +"**дистрибутивами**). Например, если у вас есть следующая структура пакета:" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "И вы используете этот пакет в своем коде следующим образом::" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "Затем вы можете разбить эти подпакеты на два отдельных дистрибутива:" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" +"Теперь каждый подпакет может быть установлен, использован и версионирован " +"отдельно." + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" +"Пакеты пространства имен могут быть полезны для большой коллекции слабо " +"связанных между собой пакетов (например, большой корпус клиентских библиотек " +"для нескольких продуктов одной компании). Однако пакеты пространства имен " +"имеют несколько оговорок и подходят не во всех случаях. Простая альтернатива " +"- использовать во всех дистрибутивах префикс, например ``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/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" +"В настоящее время существует два различных подхода к созданию пакетов " +"пространства имен, из которых последний не рекомендуется:" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" +"Используйте `нативные пакеты пространства имен`_. Этот тип пакетов " +"пространства имен определен в :pep:`420` и доступен в Python 3.3 и более " +"поздних версиях. Это рекомендуется, если пакеты в вашем пространстве имен " +"должны поддерживать только Python 3 и устанавливаться через ``pip``." + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" +"Используйте пакеты `legacy namespace`_. Это включает в себя пакеты " +"пространства имен в стиле `pkgutil`_ и пакеты пространства имен в стиле " +"`pkg_resources`_." + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "Родные пакеты пространства имён" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" +"В Python 3.3 добавлены **имплицитные** пакеты пространства имен " +"из :pep:`420`. Все, что требуется для создания нативного пакета пространства " +"имен, это просто опустить :file:`__init__.py` из каталога пакета " +"пространства имен. Пример файловой структуры (в соответствии с :ref:`src-" +"layout `):" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" +"Очень важно, чтобы каждый дистрибутив, использующий пакет namespace, " +"опускал :file:`__init__.py` или использовал :file:`__init__.py` в стиле " +"pkgutil. Если какой-либо дистрибутив этого не сделает, это приведет к сбою " +"логики пространства имен, и другие подпакеты не будут импортированы." + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" +"Структура каталогов ``rc-layout`` позволяет автоматически находить пакеты " +"большинством :term:`build backends `. Более подробную " +"информацию смотрите в :ref:`src-layout-vs-flat-layout. Если же вы хотите " +"самостоятельно управлять исключениями или включениями пакетов, это можно " +"настроить в верхнем уровне :file:`pyproject.toml`:" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "То же самое можно сделать с помощью :file:`setup.cfg`:" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "Или :файл:`setup.py`:" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" +":ref:`setuptools` по умолчанию будет искать в структуре каталогов пакеты " +"неявного пространства имен." + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" +"Полный рабочий пример двух пакетов нативного пространства имен можно найти в " +"проекте `Пример пакета нативного пространства имен`_." + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" +"Поскольку пакеты пространства имен native и pkgutil-style в значительной " +"степени совместимы, вы можете использовать пакеты пространства имен native в " +"дистрибутивах, поддерживающих только Python 3, и пакеты пространства имен " +"pkgutil-style в дистрибутивах, которые должны поддерживать Python 2 и 3." + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +msgstr "Унаследованные пакеты пространства имен" + +#: ../source/guides/packaging-namespace-packages.rst:160 +#, fuzzy +#| 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." +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 one of these " +"methods." +msgstr "" +"Эти два метода, которые использовались для создания пакетов пространства " +"имен до появления :pep:`420`, теперь считаются устаревшими и не должны " +"использоваться, если вам не нужна совместимость с пакетами, уже " +"использующими этот метод. Кроме того, :doc:`pkg_resources " +"` был устаревшим." + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" +"Чтобы перенести существующий пакет, необходимо одновременно перенести все " +"пакеты, разделяющие это пространство имен." + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" +"В то время как пакеты родного пространства имен и пакеты пространства имен в " +"стиле pkgutil в основном совместимы, пакеты пространства имен в стиле " +"pkg_resources не совместимы с другими методами. Нежелательно использовать " +"разные методы в разных дистрибутивах, предоставляющих пакеты для одного и " +"того же пространства имен." + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "Пакеты пространства имён в стиле pkgutil" + +#: ../source/guides/packaging-namespace-packages.rst:175 +#, fuzzy +#| 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." +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 was 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/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" +"Чтобы создать пакет пространства имен в стиле pkgutil, вам нужно " +"предоставить файл :file:`__init__.py` для пакета пространства имен:" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" +"Файл :file:`__init__.py` для пакета namespace должен содержать следующее:" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" +"**Каждый** дистрибутив, использующий пакет namespace, должен включать " +"такой :файл:`__init__.py`. Если дистрибутив не включит его, это приведет к " +"сбою логики пространства имен, и другие подпакеты будут недоступны для " +"импорта. Любой дополнительный код в :file:`__init__.py` будет недоступен." + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" +"Полный рабочий пример двух пакетов пространства имен в стиле pkgutil можно " +"найти в проекте `pkgutil namespace example`_." + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "Пакеты пространства имён в стиле pkg_resources" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +#, fuzzy +#| 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." +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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`_ и аргумент " +"``namespace_packages``:func:`~setuptools.setup'. Вместе они могут быть " +"использованы для объявления пакетов пространства имен. Хотя этот подход " +"больше не рекомендуется, он широко присутствует в большинстве существующих " +"пакетов пространства имен. Если вы создаете новое распределение в " +"существующем пакете пространства имен, который использует этот метод, " +"рекомендуется продолжать использовать это, поскольку различные методы не " +"являются взаимосовместимыми, и не рекомендуется пытаться мигрировать " +"существующий пакет." + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" +"Чтобы создать пакет пространства имен в стиле pkg_resources, вам нужно " +"предоставить файл :file:`__init__.py` для пакета пространства имен:" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" +"В некоторых старых рекомендациях в пакете пространства " +"имен :file:`__init__.py` рекомендуется следующее:" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" +"Идея заключалась в том, что в редких случаях, когда setuptools недоступен, " +"пакеты будут возвращаться к пакетам в стиле pkgutil. Это нежелательно, " +"поскольку пакеты пространства имен в стиле pkgutil и pkg_resources не " +"являются кросс-совместимыми. Если наличие setuptools является проблемой, то " +"пакет должен просто явно зависеть от setuptools через ``install_requires``." + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" +"Наконец, каждый дистрибутив должен предоставить аргумент " +"``namespace_packages`` в :func:`~setuptools.setup` в :file:`setup.py`. " +"Например:" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" +"Публикация релизов дистрибутивов пакетов с помощью рабочих процессов GitHub " +"Actions CI/CD" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" +"`GitHub Actions CI/CD`_ позволяет запускать серию команд каждый раз, когда " +"на платформе GitHub происходит какое-либо событие. Одним из популярных " +"вариантов является рабочий процесс, который запускается по событию ``push``. " +"В этом руководстве показано, как публиковать дистрибутив Python каждый раз, " +"когда выкладывается коммит с меткой. Для публикации будет использован экшен " +"GitHub `pypa/gh-action-pypi-publish`_. Также используются действия GitHub " +"`upload-artifact`_ и `download-artifact`_ для временного хранения и загрузки " +"исходных пакетов." + +#: ../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." +msgstr "" +"Это руководство *предполагает*, что у вас уже есть проект, для которого вы " +"знаете, как собирать дистрибутивы, и *он живет на GitHub*. Это руководство " +"также избегает подробностей сборки проектов для конкретных платформ. Если у " +"вас есть бинарные компоненты, посмотрите примеры GitHub Action " +"от :ref:`cibuildwheel`." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:25 +#, fuzzy +#| msgid "Configuring trusted publishing" +msgid "Configuring Trusted Publishing" +msgstr "Настройка доверенной публикации" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:27 +#, fuzzy +#| 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." +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." +msgstr "" +"В этом руководстве используется реализация PyPI `trusted publishing`_ для " +"подключения к `GitHub Actions CI/CD`_. Это рекомендуется из соображений " +"безопасности, поскольку генерируемые токены создаются для каждого вашего " +"проекта отдельно и автоматически истекают. В противном случае вам придется " +"сгенерировать `API-токен`_ как для PyPI, так и для TestPyPI. В случае " +"публикации в сторонние индексы, такие как :doc:`devpi `, вам " +"может потребоваться указать комбинацию имя пользователя/пароль." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +#, fuzzy +#| 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." +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." +msgstr "" +"Поскольку в этом руководстве мы продемонстрируем загрузку на PyPI и " +"TestPyPI, нам понадобятся два доверенных издателя. Следующие шаги приведут " +"вас к созданию \"ожидающих\" издателей для вашего нового :term:`PyPI проекта " +"`. Однако можно также добавить `доверенную публикацию`_ в любой уже " +"существующий проект, если вы являетесь его владельцем." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" +"Если вы следовали предыдущим версиям этого руководства, вы создали секреты " +"``PYPI_API_TOKEN`` и ``TEST_PYPI_API_TOKEN`` для прямого доступа к PyPI и " +"TestPyPI. Теперь они устарели, и вам следует удалить их из вашего " +"репозитория GitHub и отозвать их в настройках ваших аккаунтов PyPI и " +"TestPyPI, если вы заменяете старую настройку на новую." + +#: ../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 "" +"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:`PyPI-" +"проект ` (значение ``name`` в вашем ``setup.cfg`` или " +"``pyproject.toml``), имя владельца репозитория GitHub (org или user), имя " +"репозитория, а также имя файла рабочего процесса релиза в папке ``.github/" +"``, см. :ref:`workflow-definition``. Наконец, добавьте имя окружения GitHub " +"(``pypi``), которое мы собираемся установить под вашим репозиторием. " +"Зарегистрируйте доверенного издателя." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" +"Теперь перейдите на https://test.pypi.org/manage/account/publishing/ и " +"повторите второй шаг, но на этот раз введите ``testpypi`` в качестве имени " +"среды GitHub." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" +"Ваши \"ожидающие\" издатели теперь готовы к первому использованию и будут " +"создавать ваши проекты автоматически, как только вы впервые их используете." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" +"Если у вас нет учетной записи TestPyPI, вам нужно ее создать. Это не то же " +"самое, что обычная учетная запись PyPI." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:78 +#, fuzzy +#| msgid "" +#| "For security reasons, you must require `manual approval `_ on each " +#| "run for the ``pypi`` environment." +msgid "" +"For security reasons, you must require `manual approval `_ on each run for the ``pypi`` environment." +msgstr "" +"По соображениям безопасности вы должны требовать `ручного одобрения `_ при каждом " +"запуске для среды ``pypi``." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "Создание определения рабочего процесса" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" +"Рабочие процессы GitHub CI/CD объявляются в файлах YAML, хранящихся в " +"директории ``.github/workflows/`` вашего репозитория." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +#, fuzzy +#| msgid "Let's create a ``.github/workflows/publish-to-test-pypi.yml`` file." +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "Давайте создадим файл ``.github/workflows/publish-to-test-pypi.yml``." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" +"Начните его с осмысленного имени и определите событие, которое должно " +"заставить GitHub запустить этот рабочий процесс:" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" +"Нам нужно будет определить два задания для публикации в PyPI и TestPyPI " +"соответственно, а также дополнительное задание для сборки дистрибутива." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" +"Сначала мы определим задание для сборки дист-пакетов вашего проекта и " +"хранения их для последующего использования:" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" +"Это позволит загрузить ваш репозиторий в CI runner, а затем установить и " +"активировать самый новый доступный релиз Python 3." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" +"Теперь мы можем собрать дисты из исходного кода и сохранить их. В этом " +"примере мы будем использовать пакет ``build``. Так что добавьте его в список " +"шагов:" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "Определение рабочей среды рабочего процесса" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:130 +#, fuzzy +#| 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." +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. Это процесс, который будет выполнять команды, которые " +"мы определим позже. В этом руководстве мы будем использовать последнюю " +"стабильную версию Ubuntu LTS, предоставленную GitHub Actions. Здесь также " +"определяется окружение GitHub для запуска задания в его контексте и URL-" +"адрес, который будет красиво отображаться в пользовательском интерфейсе " +"GitHub. Кроме того, она позволяет получить токен OpenID Connect, который " +"необходим действию ``pypi-publish`` для реализации секретной доверенной " +"публикации в PyPI." + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "Публикация дистрибутива в PyPI" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" +"Этот шаг использует действие `pypa/gh-action-pypi-publish`_ GitHub: после " +"загрузки сохраненного дистрибутива действием `download-artifact`_, оно " +"безусловно загружает содержимое папки ``dist/`` в PyPI." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "Отдельный рабочий процесс для публикации в TestPyPI" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" +"Теперь повторите эти шаги и создайте еще одно задание для публикации в " +"индекс пакета TestPyPI в разделе ``jobs``:" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" +"Требование ручного одобрения в среде ``testpypi`` GitHub обычно не " +"требуется, поскольку она предназначена для выполнения каждого коммита в " +"основной ветке и часто используется для обозначения здорового конвейера " +"публикации pipрелизов." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "Весь рабочий процесс CI/CD" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" +"В этом пункте показан весь рабочий процесс после выполнения вышеописанного " +"руководства." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "Вот и все, друзья!" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" +"Теперь, когда бы вы ни отправили помеченный коммит в свой Git-репозиторий на " +"GitHub, этот рабочий процесс будет публиковать его в PyPI. И он будет " +"публиковать любой push в TestPyPI, что полезно для предоставления тестовых " +"сборок вашим альфа-пользователям, а также для того, чтобы убедиться, что ваш " +"конвейер релизовpip остаётся здоровым!" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" +"Если в вашем репозитории часто происходят коммиты и каждый push загружается " +"в TestPyPI, как описано выше, проект может превысить ограничение на размер " +"проекта `_. Лимит может быть " +"увеличен, но лучшим решением может быть использование PyPI-совместимого " +"сервера, например :ref:`pypiserver`, в CI для тестирования." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +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 "Хостинг" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +msgid "Installation" +msgstr "Установка" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "0; url=../../discussions/single-source-version/" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" +"Перенаправление устаревшей ссылки на версию пакета из одного источника..." + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" +"Если страница не обновляется автоматически, смотрите :ref:`single-source-" +"version`." + +#: ../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 "" +"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 "" +"Помимо работы, необходимой для создания пакета Python, часто возникает " +"необходимость сделать его доступным для разных версий Python. Разные версии " +"Python могут содержать разные (или переименованные) пакеты стандартной " +"библиотеки, а изменения между версиями Python 2.x и 3.x включают изменения в " +"синтаксисе языка." + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" +"Если выполнять тестирование вручную, то все проверки, необходимые для " +"обеспечения корректной работы пакета на всех целевых версиях Python (и ОС!), " +"могут занять очень много времени. К счастью, существует несколько " +"инструментов для решения этой проблемы, о которых мы вкратце расскажем здесь." + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "Автоматическое тестирование и непрерывная интеграция" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" +"Существует несколько хостинговых сервисов для автоматизированного " +"тестирования. Эти сервисы обычно следят за вашим репозиторием исходного кода " +"(например, на `GitHub `_ или `Bitbucket `_) и запускают набор тестов вашего проекта каждый раз, когда " +"делается новый коммит." + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" +"Эти сервисы также предлагают возможности для запуска тестового набора вашего " +"проекта на *многих версиях Python*, что позволяет быстро получить информацию " +"о том, будет ли работать код, без необходимости разработчику самому " +"выполнять такие тесты." + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" +"В Википедии есть обширное \"сравнение `_ многих систем непрерывной " +"интеграции\". Существует два хостинговых сервиса, которые при совместном " +"использовании обеспечивают автоматизированное тестирование в Linux, Mac и " +"Windows:" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +#, fuzzy +#| 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." +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." +msgstr "" +"В системе Travis CI `_ есть как Linux, так и macOS. " +"Среда Linux - это Ubuntu 12.04 LTS Server Edition 64 bit, а macOS на момент " +"написания статьи - 10.9.2." + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" +"`Appveyor `_ предоставляет среду Windows (Windows " +"Server 2012)." + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" +"И `Travis CI`_, и Appveyor_ требуют файл формата `YAML `_ " +"в качестве спецификации инструкций для тестирования. Если какие-либо тесты " +"провалены, можно просмотреть журнал вывода для данной конкретной " +"конфигурации." + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" +"Для проектов на Python, которые предполагается развернуть как на Python 2, " +"так и на Python 3 с использованием стратегии единого источника, есть " +"несколько вариантов." + +#: ../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 +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_." +msgstr "" +"`six `_ - это инструмент, разработанный " +"Бенджамином Петерсоном для преодоления различий между Python 2 и Python 3. " +"Пакет six_ получил широкое распространение и может рассматриваться как " +"надежный способ написать модуль Python с одним исходным кодом, который можно " +"использовать как в Python 2, так и в Python 3. Модуль six_ можно " +"использовать уже в Python 2.5. Инструмент под названием `modernize `_, разработанный Армином Ронахером, может быть " +"использован для автоматического применения модификаций кода, предоставляемых " +"six_." + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" +"Как и six_, `python-future `_ - это " +"пакет, обеспечивающий слой совместимости между исходным кодом Python 2 и " +"Python 3; однако, в отличие от six_, этот пакет направлен на обеспечение " +"совместимости между Python 2 и Python 3 с синтаксисом языка, соответствующим " +"одной из двух версий Python: можно использовать" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "модуль Python 2 (по синтаксису) в проекте Python 3." + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "модуль Python 3 (по синтаксису) в проекте *Python 2*." + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" +"Благодаря двунаправленности, python-future_ предлагает путь к преобразованию " +"пакета Python 2 в синтаксис Python 3 модуль за модулем. Однако, в отличие от " +"six_, python-future_ поддерживается только начиная с Python 2.6. Подобно " +"modernize_ для six_, python-future_ поставляется с двумя скриптами " +"``futurize`` и ``pasteurize``, которые могут быть применены как к модулю " +"Python 2, так и к модулю Python 3 соответственно." + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" +"Использование six_ или python-future_ добавляет дополнительную зависимость " +"от времени выполнения: при использовании python-future_ скрипт ``futurize`` " +"может быть вызван с опцией ``--stage1`` для применения только тех изменений, " +"которые Python 2.6+ уже обеспечивает для прямой совместимости с Python 3. " +"Любые оставшиеся проблемы совместимости потребуют внесения изменений вручную." + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "Что находится в каком Python?" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" +"Нед Батчелдер приводит список изменений в каждом выпуске 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 "Поддержка Windows с помощью Appveyor" + +#: ../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 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 "" +"В этом разделе рассказывается о том, как использовать бесплатную службу " +"непрерывной интеграции `Appveyor`_ для обеспечения поддержки Windows в вашем " +"проекте. Сюда входит тестирование кода под Windows и сборка двоичных файлов, " +"ориентированных на Windows, для проектов, использующих расширения C." + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" +"Многие проекты по умолчанию разрабатываются на Unix, и обеспечение поддержки " +"Windows может быть сложной задачей, поскольку создание подходящей тестовой " +"среды Windows нетривиально и может потребовать покупки лицензий на " +"программное обеспечение." + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" +"Сервис Appveyor - это сервис непрерывной интеграции, подобный более " +"известному сервису `Travis`_, который обычно используется для тестирования " +"проектов, размещенных на `GitHub`_. Однако, в отличие от Travis, рабочие " +"сборщики Appveyor являются хостами Windows и имеют необходимые компиляторы " +"для сборки расширений Python." + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" +"Пользователи Windows, как правило, не имеют доступа к компилятору языка C, " +"поэтому проекты, использующие расширения C, должны распространять бинарные " +"колеса на PyPI, чтобы дистрибутив можно было установить с помощью ``python " +"-m pip install ``. Использование Appveyor в качестве сервиса сборки " +"(даже если он не используется для тестирования) позволяет проектам, не " +"имеющим выделенной среды Windows, предоставлять двоичные файлы, " +"ориентированные на Windows." + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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-колес для вашего проекта, вы " +"должны иметь учетную запись на этом сервисе. Инструкции по настройке учетной " +"записи приведены в документации Appveyor `__. Бесплатный уровень учетной записи вполне подходит для проектов с " +"открытым исходным кодом." + +#: ../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/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/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "Добавление поддержки Appveyor в ваш проект" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" +"Для того чтобы определить, как Appveyor должен собирать ваш проект, вам " +"необходимо добавить в проект файл :file:`appveyor.yml`. Все подробности о " +"том, что может быть включено в этот файл, описаны в документации Appveyor. В " +"этом руководстве мы расскажем о том, как настроить сборку колес." + +#: ../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 "" +"Appveyor по умолчанию включает в себя все цепочки инструментов компилятора, " +"необходимые для создания расширений для Python. Для Python 2.7, 3.5+ и 32-" +"битных версий 3.3 и 3.4 инструменты работают из коробки. Но для 64-битных " +"версий Python 3.3 и 3.4 требуется небольшая дополнительная настройка, чтобы " +"distutils знал, где найти 64-битные компиляторы. (Начиная с версии 3.5, " +"используемая версия Visual Studio включает 64-битные компиляторы без " +"дополнительных настроек)." + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr ":file:`appveyor.yml`" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" +"Этот файл можно скачать отсюда `__." + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" +"Файл :file:`appveyor.yml` должен находиться в корневом каталоге вашего " +"проекта. Он имеет формат ``YAML`` и состоит из нескольких секций." + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" +"Раздел ``окружение`` - это ключ к определению версий Python, для которых " +"будут создаваться ваши колеса. Appveyor поставляется с установленным Python " +"2.6, 2.7, 3.3, 3.4 и 3.5, как в 32-битных, так и в 64-битных сборках. Файл " +"примера собирается для всех этих сред, кроме Python 2.6. Установка для " +"Python 2.6 более сложна, так как в комплект поставки не входит pip. Мы не " +"поддерживаем 2.6 в этом документе (поскольку пользователи Windows, все еще " +"использующие Python 2, обычно могут перейти на Python 2.7 без особых " +"проблем)." + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" +"В разделе ``install`` используется pip для установки любого дополнительного " +"программного обеспечения, которое может потребоваться проекту. Единственным " +"требованием для сборки колес является проект ``wheel``, но проекты могут " +"захотеть изменить этот код в определенных обстоятельствах (например, для " +"установки дополнительных пакетов сборки, таких как ``Cython``, или " +"инструментов тестирования, таких как ``tox``)." + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" +"Секция ``build`` просто отключает сборку - в отличие от таких языков, как " +"``C#``, для Python не требуется никаких действий по сборке." + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" +"Основные секции, которые необходимо адаптировать под ваш проект, - это " +"``тестовый_скрипт`` и ``после_теста``." + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" +"Раздел ``тест_скрипт`` - это место, где вы будете запускать тесты вашего " +"проекта. В прилагаемом файле набор тестов запускается с помощью команды " +"``setup.py test``. Если вас интересует только сборка колес, а не запуск " +"тестов под Windows, вы можете заменить этот раздел фиктивной командой, " +"например ``echo Skipped Tests``. Возможно, вы захотите использовать другой " +"инструмент тестирования, например ``nose`` или :file:`py.test``. Или вы " +"можете использовать тестовый драйвер, например ``tox`` - однако если вы " +"используете ``tox``, вам придется внести некоторые дополнительные изменения " +"в конфигурацию, которые описаны ниже." + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" +"Команда ``after_test`` запускается после завершения тестов, и именно в ней " +"должны быть собраны колеса. Если ваш проект использует рекомендуемые " +"инструменты (в частности, ``setuptools``), то команда ``setup.py " +"bdist_wheel'' соберет ваши колеса." + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" +"Обратите внимание, что колеса будут собраны только в том случае, если ваши " +"тесты пройдут успешно. Если вы ожидаете, что ваши тесты не пройдут под " +"Windows, вы можете пропустить их, как описано выше." + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "Скрипт поддержки" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" +"Файл :file:`appveyor.yml` опирается на единственный скрипт поддержки, " +"который настраивает среду для использования компилятора SDK для 64-битных " +"сборок на Python 3.3 и 3.4. Для проектов, которым не нужен компилятор или " +"которые не поддерживают 3.3 или 3.4 на 64-битной Windows, необходим только " +"файл :file:`appveyor.yml`." + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" +"``build.cmd ``__ - это пакетный " +"скрипт для Windows, который запускает единственную команду в среде с " +"компилятором, соответствующим выбранной версии Python. Все, что вам нужно " +"сделать, это установить единственную переменную окружения " +"``DISTUTILS_USE_SDK`` в ``1``, а все остальное сделает скрипт. Он " +"устанавливает SDK, необходимый для 64-битных сборок Python 3.3.3 или 3.4, " +"поэтому не устанавливайте переменную окружения для других сборок." + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" +"Вы можете просто загрузить пакетный файл и включить его в свой проект без " +"изменений." + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "Доступ к собранным колёсам" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" +"Когда сборка завершится, построенные колеса будут доступны в панели " +"управления Appveyor для вашего проекта. Их можно найти, перейдя на страницу " +"состояния сборки для каждой сборки по очереди. В верхней части результатов " +"сборки есть ряд ссылок, одна из которых - \"Артефакты\". На этой странице " +"будет список ссылок на колеса для данной версии/архитектуры Python. Вы " +"можете скачать эти колеса и загрузить их в PyPI как часть вашего процесса " +"выпуска." + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "Тестирование с помощью tox" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" +"Многие проекты используют инструмент :doc:`Tox ` для запуска " +"своих тестов. Он обеспечивает запуск тестов в изолированном окружении с " +"использованием именно тех файлов, которые будут распространяться проектом." + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" +"Для использования ``tox`` в Appveyor есть пара дополнительных соображений " +"(на самом деле, эти вопросы не относятся к Appveyor и вполне могут " +"затрагивать другие CI-системы)." + +#: ../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." +msgstr "" +"По умолчанию ``tox`` передает тестовым процессам только выбранное " +"подмножество переменных окружения. Поскольку ``distutils`` использует " +"переменные окружения для управления компилятором, эта функция \"изоляции " +"тестов\" приведет к тому, что тесты по умолчанию будут использовать " +"неправильный компилятор." + +#: ../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 "" +"Чтобы заставить ``tox`` передавать подпроцессу необходимые переменные " +"окружения, нужно установить в конфигурационной опции ``tox`` ``passenv`` " +"список дополнительных переменных окружения, которые нужно передать " +"подпроцессу. Для компиляторов SDK необходимо" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "``DISTUTILS_USE_SDK``" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "``MSSdk``" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "``INCLUDE``" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +msgstr "``LIB``" + +#: ../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." +msgstr "" +"Опция ``passenv`` может быть задана в вашем :file:`tox.ini`, или, если вы " +"предпочитаете не добавлять специфические для Windows настройки в общие файлы " +"проекта, ее можно задать, установив переменную окружения " +"``TOX_TESTENV_PASSENV``. Поставляемый в комплекте скрипт :file:`build.cmd` " +"делает это по умолчанию, когда установлено значение ``DISTUTILS_USE_SDK``." + +#: ../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)." +msgstr "" +"При интерактивном использовании ``tox`` позволяет запускать тесты в " +"нескольких окружениях (часто это означает несколько версий Python). Эта " +"возможность не так полезна в среде CI, такой как Travis или Appveyor, где " +"все тесты запускаются в изолированных окружениях для каждой конфигурации. В " +"результате проекты часто передают аргумент ``-e ENVNAME`` в ``tox``, чтобы " +"указать, какое окружение использовать (есть окружения по умолчанию для " +"большинства версий Python)." + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" +"Однако это *не* хорошо работает с системой Windows CI, такой как Appveyor, " +"где (например) доступны две установки Python 3.4 (32-битная и 64-битная), но " +"только одно окружение ``py34`` в ``tox``." + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" +"Поэтому для запуска тестов с помощью ``tox`` проектам, вероятно, следует " +"использовать стандартное окружение ``py`` в ``tox``, которое использует " +"интерпретатор Python, использовавшийся для запуска ``tox``. Это гарантирует, " +"что когда Appveyor запустит тесты, они будут запущены с настроенным " +"интерпретатором." + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" +"Для поддержки работы в среде ``py``, возможно, проектам со сложной " +"конфигурацией ``tox`` потребуется изменить свой файл :file:`tox.ini`. Однако " +"это выходит за рамки данного документа." + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "Автоматическая загрузка колёс" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" +"Можно попросить Appveyor автоматически загружать колеса. " +"В :file:`appveyor.yml` есть шаг ``развертывания``, который можно " +"использовать, чтобы (например) скопировать собранные артефакты на FTP-сайт " +"или в экземпляр Amazon S3. Документация о том, как это сделать, включена в " +"руководства по Appveyor." + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" +"В качестве альтернативы можно было бы добавить в сборку шаг ``twine " +"upload``. Поставляемый :file:`appveyor.yml` этого не делает, поскольку " +"неясно, насколько желательна загрузка новых колес после каждого коммита " +"(хотя некоторые проекты могут захотеть это сделать)." + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "Внешние зависимости" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" +"Прилагаемые скрипты успешно соберут любой дистрибутив, который не зависит от " +"сторонних внешних библиотек для сборки." + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" +"В конфигурацию :file:`appveyor.yml` можно добавить шаги (обычно в разделе " +"\"install\") для загрузки и/или сборки внешних библиотек, необходимых " +"дистрибутиву. При необходимости можно добавить дополнительную конфигурацию " +"для сборки, чтобы указать компилятору местоположение этих библиотек. Однако " +"такой уровень конфигурации выходит за рамки данного документа." + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "Скрипты поддержки" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "Для справки, сценарий поддержки установки SDK приведен здесь:" + +#: ../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 "" +"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 "" +"Сфера упаковки Python состоит из множества различных инструментов. Для " +"многих задач : термин:` Python Packaging Authority ` (PyPA, рабочая группа, объединяющая многие инструменты " +"упаковки и поддерживающая это руководство) намеренно не дает общих " +"рекомендаций; например, причина существования множества бэкендов сборки в " +"том, что ландшафт был открыт, чтобы позволить разработку новых бэкендов, " +"обслуживающих потребности определенных пользователей лучше, чем ранее " +"уникальный бэкенд, setuptools. В этом руководстве указаны некоторые " +"инструменты, которые широко известны, а также даны рекомендации по " +"инструментам, которые не следует использовать, поскольку они устарели или " +"небезопасны." + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "Виртуальная среда" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" +"Стандартными инструментами для создания и использования виртуальных сред " +"вручную являются : ссылка:`virtualenv` (проект PyPA) и : документация:`venv " +"<питон:библиотека/venv>` (часть стандартной библиотеки Python, хотя и " +"лишенная некоторых возможностей virtualenv)." + +#: ../source/guides/tool-recommendations.rst:28 +msgid "Installing packages" +msgstr "Установка пакетов" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" +": ссылка:`Pip` - это стандартный инструмент для установки пакетов из : " +"термин:`PyPI `. Вы можете ознакомиться с " +"рекомендациями pip по : документу:`безопасная установка `. Pip доступен по умолчанию в большинстве инсталляций " +"Python через стандартный библиотечный пакет : документ:`ensurepip `." + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" +"В качестве альтернативы можно рассмотреть : ссылка:`pipx` для конкретного " +"случая установки Python-приложений, распространяемых через PyPI и " +"запускаемых из командной строки. Pipx - это обертка вокруг pip и venv, " +"которая устанавливает каждое приложение в отдельное виртуальное окружение. " +"Это позволяет избежать конфликтов между зависимостями различных приложений, " +"а также общесистемных приложений, использующих один и тот же интерпретатор " +"Python (особенно в Linux)." + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" +"Для научного программного обеспечения, в частности, рассмотрите : " +"ссылка:`Conda` или :ссылка:`Spack`." + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" +"Напишите отзыв о сравнении \"pip против Conda\" здесь или в новом обсуждении." + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" +"Не **не** используйте ``easy_install`` (часть : ссылка:`setuptools``), " +"который устарел в пользу pip (подробности см. в :ссылка:`pip против " +"easy_install``). Аналогично, **не** используйте ``питон setup.py install`` " +"или ``питон setup.py develop``, которые также устарели (смотрите : " +"ссылка:`setup-py-отказ от использования`` и :ссылка:`модернизация-setup-py-" +"проекта`` для рекомендаций по переходу)." + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "Блокировка файлов" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" +": ссылка:`pip-tools` и :ссылка:`Pipenv` - два признанных инструмента для " +"создания файлов блокировки, которые содержат точные версии всех пакетов, " +"установленных в окружении, для целей воспроизводимости." + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "Создание бэкендов" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" +"Пожалуйста, помните: этот документ не направлен на то, чтобы склонить " +"читателя к выбору конкретного инструмента, а лишь перечисляет общие " +"инструменты. Для различных случаев использования часто требуются " +"специализированные рабочие процессы." + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" +"Популярные : термин:`сборка бэкендов <сборка бэкенда>` для пакетов pure-" +"Python включают в себя, в алфавитном порядке:" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" +": документ:`Flit-core ` -- разрабатывается совместно " +"с : ссылка:`Flit`, но отдельно от :ссылка:`Flit`. Минимальный бэкенд для " +"сборки с собственным мнением. Не поддерживает плагины." + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" +"Hatchling_ -- разработан вместе с : ссылка:`Hatch`, но отдельно от него. " +"Поддерживает плагины." + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" +"PDM-бэкенд_ -- разработан совместно с : ссылка:`PDM`, но отдельно от него. " +"Поддерживает плагины." + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" +"Poetry-core_ -- разрабатывается вместе с : ссылка:`Poetry`, но отдельно от " +"него. Поддерживает плагины." + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" +"В отличие от других бэкендов в этом списке, Poetry-core не поддерживает " +"стандартную : ссылка:`[проект] таблица ` (он " +"использует другой формат, в таблице ``[ инструмент.поэзия]``)." + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" +": ссылка:`setuptools`, который раньше был единственным бэкендом сборки. " +"Поддерживает плагины." + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" +"Если вы используете setuptools, пожалуйста, имейте в виду, что некоторые " +"функции, появившиеся до стандартизации, теперь устарели и сохраняются только " +"*временно* для совместимости." + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" +"В частности, **не** используйте прямые вызовы ``python setup.py``. С другой " +"стороны, настройка setuptools с помощью файла : файл:`setup.py` по-прежнему " +"полностью поддерживается, хотя рекомендуется использовать современную " +"таблицу : ссылка:`[ проект] в pyproject.toml <запись-pyproject-toml>` " +"(или :файл:`setup.cfg`), когда это возможно, и сохранять :файл:`setup.py` " +"только в случае необходимости программной настройки. Смотрите : " +"ссылка:`setup-py-deprecated`." + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" +"Другие примеры устаревших функций, которые не следует **не** использовать, " +"включают аргумент ``setup_requires`` для ``setup()`` (вместо него " +"используйте : ссылка:`[ сборка-системы] таблица ` в :файл:`pyproject.toml``), и команду ``easy_install`` " +"(ср. :ссылка:`pip против easy_install``)." + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" +"Не используйте : ссылка:`distutils`, который устарел и был удален из " +"стандартной библиотеки в Python 3.12, хотя он по-прежнему доступен из " +"setuptools." + +#: ../source/guides/tool-recommendations.rst:115 +#, fuzzy +#| msgid "Building binary extensions" +msgid "Build backends for extension modules" +msgstr "Создание бинарных расширений" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" +"Для пакетов с : термин:`модули расширения <модуль расширения>`, лучше всего " +"использовать систему сборки с поддержкой языка, на котором написано " +"расширение, например:" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" +": ссылка:`setuptools` - изначально поддерживает C и C++ (со сторонними " +"плагинами для Go и Rust)," + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" +": ссылка:`meson-python` -- C, C++, Fortran, Rust и другие языки, " +"поддерживаемые Meson," + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" +": ссылка:`scikit-build-core` -- C, C++, Fortran и другие языки, " +"поддерживаемые CMake," + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr ": ссылка:`maturin` - Rust, через Cargo." + +#: ../source/guides/tool-recommendations.rst:128 +msgid "Building distributions" +msgstr "Распределение зданий" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" +"Стандартным инструментом для сборки : термин:`источник дистрибутива " +"<источник дистрибутива (или \"sdist\")>` и :термин:`колеса <колесо>` для " +"загрузки на PyPI является : ссылка:`build`. Он будет вызывать тот бэкенд " +"сборки, который вы : ссылка:`декларировали ` в :файл:`pyproject.toml`." + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" +"Не используйте для этой задачи ``python setup.py sdist`` и ``python setup.py " +"bdist_wheel``. Все прямые вызовы : файл:`setup.py` " +"являются :ссылка:`утратившими актуальность `." + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" +"Если у вас есть : термин:`модули расширения <модуль расширения>` и вы хотите " +"распространять колеса для нескольких платформ, используйте : " +"ссылка:`cibuildwheel` как часть вашей настройки CI для сборки " +"распространяемых колес." + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "Загрузка на PyPI" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" +"Для проектов, размещенных на поддерживаемых CI/CD платформах или " +"опубликованных с их помощью, рекомендуется использовать :ref:`Trusted " +"Publishing `, который позволяет безопасно загрузить " +"пакет в PyPI из CI/CD рабочего процесса без ручной настройки API-токена." + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" +"По состоянию на ноябрь 2024 года PyPI поддерживает следующие платформы в " +"качестве доверенных поставщиков публикаций:" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "Действия на GitHub (на ``https://github.com``)" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "GitLab CI/CD (на ``https://gitlab.com``)" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "ActiveState" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "Google Cloud" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" +"Другой доступный способ - загрузить пакет вручную с помощью : ссылка:`twine`." + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" +"**Никогда** не используйте ``python setup.py upload`` для этой задачи. " +"Помимо того, что он является : ссылка:`утратившим актуальность `, он еще и небезопасен." + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "Инструменты рабочего процесса" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" +"Эти инструменты представляют собой менеджеры окружения, которые " +"автоматически управляют виртуальными средами для проекта. Они также " +"выступают в роли \"бегунков задач\", позволяя вам определять и вызывать " +"такие задачи, как запуск тестов, компиляция документации, регенерация " +"некоторых файлов и т. д. Некоторые из них предоставляют ярлыки для сборки " +"дистрибутивов и загрузки в PyPI, а некоторые поддерживают блокировку файлов " +"для приложений. Часто они вызывают инструменты, упомянутые выше под капотом. " +"В алфавитном порядке:" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr ":ссылка:`Flit`," + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr ":ссылка:`Hatch`," + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr ": документ:`nox `," + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr ":ссылка:`PDM`," + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr ":ссылка:`Pipenv`," + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr ":ссылка:`Поэзия`," + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr ": документ:`токсический <токсический:индекс>`." + +#: ../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 "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" +"Информация на этой странице была перемещена в :doc:`setuptools:userguide/" +"miscellaneous` в документации по setuptools." + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" +"``TestPyPI`` - это отдельный экземпляр :term:``Python Package Index " +"(PyPI)``, который позволяет вам опробовать инструменты и процесс " +"распространения, не беспокоясь о том, что это повлияет на настоящий индекс. " +"TestPyPI размещен по адресу `test.pypi.org `_" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "Регистрация учётной записи" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" +"Поскольку TestPyPI имеет отдельную базу данных от живого PyPI, вам " +"понадобится отдельная учетная запись пользователя специально для TestPyPI. " +"Перейдите на https://test.pypi.org/account/register/, чтобы зарегистрировать " +"свою учетную запись." + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" +"База данных TestPyPI может периодически подвергаться обрезке, поэтому " +"нередко учетные записи пользователей удаляются." + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "Использование TestPyPI вместе с Twine" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" +"Вы можете загрузить свои дистрибутивы в TestPyPI с помощью :ref:`twine`, " +"указав флаг ``--repository``:" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" +"Вы можете убедиться, что ваш пакет успешно загружен, перейдя по URL-адресу " +"``https://test.pypi.org/project/``, где ``sampleproject`` - " +"это имя загруженного вами проекта. Возможно, потребуется минута или две, " +"чтобы ваш проект появился на сайте." + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "Использование TestPyPI вместе с pip" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" +"Вы можете указать :ref:`pip` загружать пакеты с TestPyPI вместо PyPI, указав " +"флаг ``--index-url``:" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" +"Если вы хотите, чтобы pip также загружал пакеты с PyPI, вы можете указать " +"``--extra-index-url``, чтобы он указывал на PyPI. Это полезно, когда у " +"тестируемого пакета есть зависимости:" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "Настройка TestPyPI в :file:`.pypirc`" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" +"Если вы хотите, чтобы вам не приходилось каждый раз запрашивать имя " +"пользователя и пароль, вы можете настроить TestPyPI в " +"вашем :file:`$HOME/.pypirc`:" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "Написание вашего ``pyproject.toml``" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" +"``pyproject.toml`` - это конфигурационный файл, используемый инструментами " +"упаковки, а также другими инструментами, такими как линеры, программы " +"проверки типов и т.д. В этом файле есть три возможные таблицы TOML." + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" +"Таблица ``[build-system]`` является **настоятельно рекомендуемой**. Она " +"позволяет указать, какой :term:`build backend` вы используете и какие другие " +"зависимости необходимы для сборки вашего проекта." + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" +"Таблица ``[project]`` - это формат, который используется большинством " +"сборочных бэкендов для указания основных метаданных вашего проекта, таких " +"как зависимости, ваше имя и т.д." + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" +"Таблица ``[tool]`` имеет подтаблицы, специфичные для каждого инструмента, " +"например, ``[tool.hatch]``, ``[tool.black]``, ``[tool.mypy]``. Здесь мы " +"касаемся только этой таблицы, поскольку ее содержимое определяется каждым " +"инструментом. Чтобы узнать, что в ней может содержаться, обратитесь к " +"документации конкретного инструмента." + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" +"Таблица ``[build-system]`` должна присутствовать всегда, независимо от того, " +"какой бэкенд сборки вы используете (``[build-system]`` *определяет* " +"инструмент сборки, который вы используете)." + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" +"С другой стороны, таблица ``[project]`` понимается *большинством* сборочных " +"бэкендов, но некоторые бэкенды используют другой формат." + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" +"Заметным исключением является Poetry_, который до версии 2.0 (выпущенной 5 " +"января 2025 года) не использовал таблицу ``[project]``, а использовал " +"таблицу ``[tool.poetry]``. В версии 2.0 она поддерживает обе таблицы. Кроме " +"того, бэкенд сборки setuptools_ поддерживает как таблицу ``[project]``, так " +"и более старый формат в ``setup.cfg`` или ``setup.py``." + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" +"Для новых проектов используйте таблицу ``[project]``, а ``setup.py`` " +"сохраняйте только в том случае, если требуется некоторая программная " +"настройка (например, сборка расширений на C), но форматы ``setup.cfg`` и " +"``setup.py`` по-прежнему актуальны. См. :ref:`setup-py-deprecated`." + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "Объявление бэкенда сборки" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" +"Таблица ``[build-system]`` содержит ключ ``build-backend``, который " +"указывает используемый бэкенд сборки. Она также содержит ключ ``requires``, " +"который представляет собой список зависимостей, необходимых для сборки " +"проекта - обычно это только пакет бэкенда сборки, но может содержать и " +"дополнительные зависимости. Вы также можете ограничить версии, например, " +"``requires = [\"setuptools >= 61.0\"]``." + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" +"Обычно вы просто копируете то, что предлагает документация вашего бэкенда " +"сборки (после :ref:`выбора бэкенда сборки `). Вот " +"значения для некоторых распространенных бэкендов сборки:" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "Статические и динамические метаданные" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "Остальная часть этого руководства посвящена таблице ``[проекта]``." + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" +"Чаще всего вы будете напрямую записывать значение поля ``[проект]``. " +"Например: ``requires-python = \">= 3.8\"``, или ``version = \"1.0\"``." + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" +"Однако в некоторых случаях полезно позволить бэкенду сборки вычислять " +"метаданные за вас. Например, многие сборки могут считывать версию из " +"атрибута ``__version__`` в вашем коде, тега Git или чего-то подобного. В " +"таких случаях вам следует пометить поле как динамическое, например, с " +"помощью," + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" +"Если поле динамическое, его заполнение возлагается на бэкенд сборки. " +"Обратитесь к документации вашего бэкенда сборки, чтобы узнать, как он это " +"делает." + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "Базовая информация" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "``name``" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" +"Укажите название вашего проекта на PyPI. Это поле обязательно для заполнения " +"и является единственным полем, которое не может быть помечено как " +"динамическое." + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" +"Имя проекта должно состоять из букв ASCII, цифр, знаков подчеркивания " +"\"``_``\", дефисов \"``-``\" и точек \"``.``\". Оно не должно начинаться или " +"заканчиваться подчеркиванием, дефисом или точкой." + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" +"Сравнение имен проектов не зависит от регистра и рассматривает произвольно " +"длинные символы подчеркивания, дефиса и/или точки как одинаковые. Например, " +"если вы зарегистрируете проект с именем ``cool-stuff``, пользователи смогут " +"загрузить его или объявить зависимость от него, используя любое из следующих " +"написаний: ``Cool-Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-" +"__sTuFF``." + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "Положите версию вашего проекта." + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" +"Возможны и более сложные спецификации версий, например ``2020.0.0a1`` (для " +"альфа-версии); подробности см. в :ref:`specification `." + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" +"Это поле является обязательным, хотя часто его помечают как динамическое с " +"помощью" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" +"Это позволяет использовать такие случаи, как заполнение версии из атрибута " +"``__version__`` или тега Git. За более подробной информацией обратитесь к " +"обсуждению :ref:`single-source-version`." + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "Зависимости и требования" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "``зависимости``/``опциональные-зависимости``" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" +"Если у вашего проекта есть зависимости, перечислите их следующим образом:" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" +"Полный синтаксис, который можно использовать для ограничения версий, см. " +"в :ref:`Спецификаторы зависимости `." + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" +"Вы можете сделать некоторые из ваших зависимостей необязательными, если они " +"необходимы только для определенной функции вашего пакета. В этом случае " +"поместите их в `` по выбору-зависимости``." + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" +"Каждый из ключей определяет \"дополнительную упаковку\". В примере выше " +"можно использовать, например, ``pip install your-project-name[gui]`` для " +"установки проекта с поддержкой графического интерфейса, добавив зависимость " +"PyQt5." + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "``требуется-python``" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" +"Это позволяет объявить минимальную версию Python, которую вы поддерживаете " +"[#requires-python-upper-bounds]_." + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "Создание исполняемых скриптов" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" +"Чтобы установить команду как часть вашего пакета, объявите ее в таблице " +"``[project.scripts]``." + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" +"В этом примере после установки вашего проекта будет доступна команда ``spam-" +"li``. Выполнение этой команды эквивалентно выполнению команды ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" +"В Windows скрипты, упакованные таким образом, нуждаются в терминале, поэтому " +"если вы запустите их из графического приложения, они вызовут всплывающий " +"терминал. Чтобы этого не происходило, используйте таблицу ``[project.gui-" +"scripts]`` вместо ``[project.scripts]``." + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" +"В этом случае запуск скрипта из командной строки сразу же вернет управление, " +"оставив скрипт работать в фоновом режиме." + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" +"Разница между ``[project.scripts]`` и ``[project.gui-scripts]`` актуальна " +"только для Windows." + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "О вашем проекте" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "``авторы``/ ``майнтейнеры``" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" +"Оба эти поля содержат списки людей, идентифицированных по имени и/или адресу " +"электронной почты." + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "``description``" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" +"Это должно быть однострочное описание вашего проекта, которое будет " +"отображаться в качестве \"заголовка\" страницы вашего проекта на PyPI " +"(`пример `_), а также в других местах, таких как списки " +"результатов поиска (`пример `_)." + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "``readme``" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" +"Это более длинное описание вашего проекта, которое будет отображаться на " +"странице вашего проекта на PyPI. Обычно у вашего проекта есть файл " +"``README.md`` или ``README.rst``, и вы просто помещаете его имя сюда." + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "Формат README определяется автоматически по расширению:" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "``README.md`` → `GitHub-flavored Markdown `_," + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "``README.rst`` → ``reStructuredText `_ (без расширений Sphinx)." + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "Вы также можете указать формат в явном виде, например, так:" + +#: ../source/guides/writing-pyproject-toml.rst:297 +#, fuzzy +#| msgid "``license-files``" +msgid "``license`` and ``license-files``" +msgstr "``лицензионные файлы``" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +#, fuzzy +#| msgid "" +#| "This is a valid :term:`SPDX license expression ` " +#| "consisting of one or more :term:`license identifiers `. The full license list is available at the `SPDX license " +#| "list page `_. The supported list version is 3.17 or any " +#| "later compatible one." +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" +"Это действительное выражение лицензии :term:`SPDX `, " +"состоящее из одного или нескольких :term:`license identifiers `. Полный список лицензий доступен на странице `списка лицензий " +"SPDX `_. Поддерживаемая версия списка - 3.17 или любая " +"более поздняя совместимая." + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +#, fuzzy +#| msgid "hatch" +msgid "hatchling" +msgstr "hatch" + +#: ../source/guides/writing-pyproject-toml.rst:313 +#, fuzzy +#| msgid "Setuptools" +msgid "setuptools" +msgstr "Инструменты настройки" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +#, fuzzy +#| msgid "Build backends" +msgid "pdm-backend" +msgstr "Создание бэкендов" + +#: ../source/guides/writing-pyproject-toml.rst:316 +#, fuzzy +#| msgid "poetry" +msgid "poetry-core" +msgstr "поэзия" + +#: ../source/guides/writing-pyproject-toml.rst:317 +#, fuzzy +#| msgid "build" +msgid "uv-build" +msgstr "построить" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "``лицензия``" + +#: ../source/guides/writing-pyproject-toml.rst:331 +#, fuzzy +#| msgid "" +#| "This is a valid :term:`SPDX license expression ` " +#| "consisting of one or more :term:`license identifiers `. The full license list is available at the `SPDX license " +#| "list page `_. The supported list version is 3.17 or any " +#| "later compatible one." +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" +"Это действительное выражение лицензии :term:`SPDX `, " +"состоящее из одного или нескольких :term:`license identifiers `. Полный список лицензий доступен на странице `списка лицензий " +"SPDX `_. Поддерживаемая версия списка - 3.17 или любая " +"более поздняя совместимая." + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" +"Как правило, лучше использовать стандартную, хорошо известную лицензию, как " +"для того, чтобы избежать путаницы, так и потому, что некоторые организации " +"избегают программ, лицензия которых не утверждена." + +#: ../source/guides/writing-pyproject-toml.rst:353 +#, fuzzy +#| msgid "" +#| "If your project is licensed with a license that doesn't have an existing " +#| "SPDX identifier, you can create a custom one in format ``LicenseRef-" +#| "[idstring]``. The custom identifiers must follow the SPDX specification, " +#| "`clause 10.1 `_ of the version 2.2 or any later " +#| "compatible one." +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" +"Если ваш проект лицензирован по лицензии, для которой не существует " +"идентификатора SPDX, вы можете создать собственный идентификатор в формате " +"``LicenseRef-[idstring]``. Пользовательские идентификаторы должны " +"соответствовать спецификации SPDX, `пункт 10.1 `_ версии 2.2 " +"или любой более поздней совместимой." + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "``лицензионные файлы``" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" +"Это список лицензионных файлов и файлов, содержащих другую юридическую " +"информацию, которую вы хотите распространить вместе с пакетом." + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "Шаблоны glob должны соответствовать спецификации:" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" +"Буквенно-цифровые символы, знаки подчеркивания (``_``), дефисы (``-``) и " +"точки (``.``) будут соответствовать дословно." + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" +"Специальные символы: ``*``, ``?``, ``**`` и диапазоны символов: [] " +"поддерживаются." + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "Разделителями путей должны быть символы прямой косой черты (``/``)." + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" +"Шаблоны являются относительными к директории, " +"содержащей :file:`pyproject.toml`, и поэтому не могут начинаться с символа " +"слэша." + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "Индикаторы родительских каталогов (``..``) не должны использоваться." + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "Каждый glob должен соответствовать хотя бы одному файлу." + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" +"Буквальные пути являются допустимыми глобусами. Любые символы или " +"последовательности символов, не предусмотренные данной спецификацией, " +"являются недопустимыми." + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "``ключевые слова``" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" +"Это поможет поисковой строке PyPI предлагать ваш проект при поиске по этим " +"ключевым словам." + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "`` классификаторы ``" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" +"Список классификаторов PyPI, которые применимы к вашему проекту. Проверьте " +"`полный список возможностей `_." + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" +"Хотя список классификаторов часто используется для объявления того, какие " +"версии Python поддерживает проект, эта информация используется только для " +"поиска и просмотра проектов на PyPI, но не для установки проектов. Чтобы " +"действительно ограничить, на каких версиях Python может быть установлен " +"проект, используйте аргумент :ref:`requires-python`." + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" +"Чтобы предотвратить загрузку пакета в PyPI, используйте специальный " +"классификатор ``Private :: Do Not Upload``. PyPI всегда будет отклонять " +"пакеты с классификаторами, начинающимися с ``Private ::``." + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "``urls``" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" +"Список URL-адресов, связанных с вашим проектом, отображаемый на левой " +"боковой панели страницы проекта PyPI." + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" +"См. :ref:`well-known-labels` для списка меток, о которых PyPI и другие " +"инструменты упаковки знают, и `PyPI's project metadata docs `_ для обработки URL, " +"специфичных для PyPI." + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" +"Обратите внимание, что если метка содержит пробелы, ее нужно заключить в " +"кавычки, например, ``Website = «https://example.com»``, но ``«Официальный " +"сайт» = «https://example.com»``." + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" +"Пользователям рекомендуется использовать :ref:`well-known-labels` для URL-" +"адресов своих проектов, где это уместно, поскольку потребители метаданных " +"(например, индексов пакетов) могут специализировать их представление." + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" +"Например, в следующих метаданных ни ``MyHomepage``, ни ``«Download Link»`` " +"не являются известными метками, поэтому они будут отображены дословно:" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" +"В то время как в этих метаданных ``HomePage`` и ``DOWNLOAD`` имеют " +"общеизвестные эквиваленты (``homepage`` и ``download``), и могут быть " +"представлены с учетом этой семантики (домашняя страница проекта и его " +"внешнее место загрузки, соответственно)." + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "Расширенные плагины" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" +"Некоторые пакеты могут быть расширены с помощью плагинов. В качестве примера " +"можно привести Pytest_ и Pygments_. Чтобы создать такой плагин, нужно " +"объявить его в подтаблице ``[project.entry-points]`` следующим образом:" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" +"Дополнительную информацию см. в :ref:`Руководство по плагинам `." + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "Полный пример" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" +"Подумайте дважды, прежде чем применять здесь верхнюю границу вроде " +"``requires-python = \"<= 3.10\"``. ``Эта запись в блоге `` содержит некоторую информацию о возможных проблемах." + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +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’ьих пакетов" + +#: ../source/index.rst:25 +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." +msgstr "" +"Добро пожаловать в *Руководство пользователя по упаковке Python*, коллекцию " +"руководств и ссылок, которые помогут вам распространять и устанавливать " +"пакеты Python с помощью современных инструментов." + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" +"Это руководство поддерживается на `GitHub`_ силами :doc:`Python Packaging " +"Authority `. Мы с радостью принимаем :doc:`дополнения и отзывы " +"`. 😊" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "Обзор и поток" + +#: ../source/index.rst:40 +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." +msgstr "" +"Понимание упаковки Python - это путешествие. Терпение и постоянное " +"совершенствование - ключ к успеху. Разделы \"Обзор\" и \"Поток\" служат " +"отправной точкой для понимания экосистемы упаковки Python." + +#: ../source/index.rst:44 +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." +msgstr "" +"В :doc:`обзор` рассказывается об упаковке Python и ее использовании при " +"подготовке и распространении проектов. Этот раздел поможет вам понять, как " +"выбрать инструменты и процессы, наиболее подходящие для вашего случая " +"использования. В нем рассказывается о том, что такое упаковка, какие " +"проблемы она решает, а также о ключевых моментах." + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" +"Чтобы получить представление о рабочем процессе, используемом для публикации " +"вашего кода, смотрите :doc:`packaging flow `." + +#: ../source/index.rst:57 +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:" +msgstr "" +"Учебники рассказывают о шагах, необходимых для выполнения проекта в первый " +"раз. Учебники призваны помочь вам добиться успеха и стать отправной точкой " +"для дальнейших исследований. Раздел :doc:`tutorials/index` включает:" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "A :doc:`учебник по установке пакетов `" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" +"Учебник по управлению зависимостями приложений ` в проекте с контролем версий" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" +"Учебник по упаковке и распространению вашего " +"проекта" + +#: ../source/index.rst:71 +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." +msgstr "" +"Руководства содержат шаги по выполнению конкретной задачи. Руководства в " +"большей степени ориентированы на пользователей, которые уже знакомы с " +"упаковкой Python и ищут конкретную информацию." + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" +"Раздел :doc:`guides/index` содержит инструкции \"как делать\" в трех " +"основных областях: установка пакетов; сборка и распространение пакетов; " +"различные темы." + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "Объяснения и обсуждения" + +#: ../source/index.rst:82 +#, fuzzy +#| msgid "" +#| "The :doc:`discussions/index` section for in-depth explanations and " +#| "discussion about topics, such as:" +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" +"Раздел :doc:`discussions/index` для подробного объяснения и обсуждения таких " +"тем, как:" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr ":doc:`обсуждения/развертывание-python-приложений`" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr ": документ:`обсуждения/pip-vs-easy-install`" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "Ссылка" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" +"Раздел :doc:`specifications/index` для спецификаций совместимости упаковки." + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" +"Список :doc:`других проектов `, поддерживаемых членами Python " +"Packaging Authority." + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" +"В :doc:`глоссарии` содержатся определения терминов, используемых в упаковке " +"Python." + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "Обзор проектов" + +#: ../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/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "Проекты PyPA" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "bandersnatch" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Документы `__ | `Выпуски `__ | `GitHub `__ | `PyPI `__" + +#: ../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:37 +msgid "build" +msgstr "построить" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +":any:`Docs ` | `Проблемы `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" +"``build`` - это совместимый с :pep:`517` сборщик пакетов на Python. Он " +"предоставляет CLI для создания пакетов, а также Python API." + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "cibuildwheel" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" +"`Документы `__ | `Проблемы `__ | `GitHub `__ | `PyPI `__ | " +"`Обсуждения `__ | `Discord " +"#cibuildwheel `__" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" +"``cibuildwheel`` - это Python-пакет, который собирает :term:`колеса ` " +"для всех распространенных платформ и версий Python на большинстве CI-систем. " +"Также смотрите :ref:`multibuild`." + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "distlib" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +":doc:`Документы ` | `Проблемы `__ | `GitHub `__ | `PyPI " +"`__" + +#: ../source/key_projects.rst:73 +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." +msgstr "" +"``distlib`` - это библиотека, реализующая низкоуровневые функции, связанные " +"с упаковкой и распространением программ на Python. ``distlib`` реализует " +"несколько соответствующих PEP (стандарты Python Enhancement Proposal) и " +"полезна разработчикам сторонних средств упаковки для создания и загрузки " +"бинарных и исходных :term:`distributions `, достижения " +"совместимости, разрешения зависимостей, управления ресурсами пакета и " +"выполнения других подобных функций." + +#: ../source/key_projects.rst:82 +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." +msgstr "" +"В отличие от более строгого проекта :ref:`packaging` (см. ниже), который " +"специально реализует современные стандарты совместимости упаковки Python, " +"``distlib`` также пытается обеспечить разумное обратное поведение, когда " +"требуется работать со старыми пакетами и метаданными, которые появились до " +"современных стандартов совместимости и попадают в подмножество пакетов, " +"несовместимых с этими стандартами." + +#: ../source/key_projects.rst:93 +msgid "distutils" +msgstr "distutils" + +#: ../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/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 "" +"Из-за сложностей, связанных с поддержкой системы упаковки, в которой " +"обновления функций тесно связаны с обновлениями времени выполнения языка, " +"прямое использование :ref:`distutils` активно не рекомендуется, а " +"предпочтительной заменой является :ref:`Setuptools`. :ref:`Setuptools` не " +"только предоставляет возможности, которых нет в обычном :ref:`distutils` " +"(такие как объявление зависимостей и объявление точек входа), но и " +"обеспечивает согласованный интерфейс сборки и набор функций для всех " +"поддерживаемых версий Python." + +#: ../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 "" +"Следовательно, :ref:`distutils` был устаревшим в Python 3.10 с " +"помощью :pep:`632` и был :doc:`удален ` из стандартной " +"библиотеки в Python 3.12. Setuptools включает в себя автономную копию " +"distutils, и она внедряется даже на Python < 3.12, если вы сначала " +"импортируете setuptools или используете pip." + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "flit" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" +"`Документы `__ | `Проблемы `__ | `PyPI `__" + +#: ../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. Он фокусируется на том, чтобы \"сделать легкие вещи " +"легкими `_ для упаковки\". Flit может сгенерировать " +"конфигурационный файл для быстрой настройки простого проекта, собрать " +"исходные дистрибутивы и колеса и загрузить их в PyPI." + +#: ../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` для сборки " +"дистрибутивов или :ref:`twine` для их загрузки на PyPI. Flit требует Python " +"3, но вы можете использовать его для распространения модулей для Python 2, " +"если они могут быть импортированы на Python 3." + +#: ../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 года на платформе `tidelift `__, а средства отправляются в PSF и предназначаются " +"для использования в PyPA." + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "hatch" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Документы `__ | `GitHub `__ | `PyPI `__" + +#: ../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:`build " +"backend ` Hatchling для конфигурирования, версионирования, " +"указания зависимостей и публикации пакетов в PyPI. Его система плагинов " +"позволяет легко расширять функциональность." + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "packaging" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +":doc:`Документы ` | `Проблемы `__ | `GitHub `__ | " +"`PyPI `__" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" +"Основные утилиты для Python упаковки, используемой:ref:`pip'' " +"и :ref:`setuptools'." + +#: ../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. Большинство пользователей Python используют эту библиотеку " +"без необходимости ее явного вызова; разработчики других перечисленных здесь " +"инструментов для упаковки, распространения и установки Python часто " +"используют ее функциональность для анализа, обнаружения и другой обработки " +"атрибутов зависимостей." + +#: ../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 "" +"Этот проект фокусируется на реализации современных стандартов совместимости " +"упаковки Python, определенных в :ref:`packaging-specifications`, и будет " +"сообщать об ошибках для достаточно старых унаследованных пакетов, " +"несовместимых с этими стандартами. В отличие от этого, проект :ref:`distlib` " +"- это более свободная библиотека, которая пытается обеспечить правдоподобное " +"прочтение неоднозначных метаданных в тех случаях, когда :ref:`packaging` " +"вместо этого сообщит об ошибке." + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "pip" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Документы `__ | `Проблемы `__ | `GitHub `__ | `PyPI `__" + +#: ../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, входящий в состав " +"современных версий Python." + +#: ../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 "" +"Он предоставляет основные функции для поиска, загрузки и установки пакетов " +"из PyPI и других индексов пакетов Python, а также может быть включен в " +"широкий спектр рабочих процессов разработки с помощью интерфейса командной " +"строки (CLI)." + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "Pipenv" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +msgstr "" +":doc:`Документы ` | `Источник `__ | `Проблемы `__ | `PyPI " +"`__" + +#: ../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``, а также проверять CVE в ``Pipfile`` с помощью `safety " +"`_." + +#: ../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/key_projects.rst:225 +msgid "Pipfile" +msgstr "Pipfile" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "`Исходный код `__" + +#: ../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/key_projects.rst:236 +msgid "pipx" +msgstr "pipx" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" + +#: ../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/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" +":doc:`Документы <индекс>` | `Вопросы `__ | `GitHub `__" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "Это руководство!" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "readme_renderer" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" +"`GitHub и документация `__ | `PyPI " +"`__" + +#: ../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`` - это библиотека, которую разработчики пакетов " +"используют для рендеринга файлов пользовательской документации (README) в " +"HTML из языков разметки, таких как Markdown или reStructuredText. " +"Разработчики вызывают ее самостоятельно или через :ref:`twine`, как часть " +"процесса управления релизами, чтобы проверить, что описания их пакетов будут " +"правильно отображаться на PyPI." + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "Инструменты настройки" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Документы `__ | `Проблемы " +"`__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" +"Setuptools (включающий ``easy_install``) - это набор улучшений для Python " +"distutils, которые позволяют вам легче собирать и распространять " +"Python :term:`distributions `, особенно те, которые " +"имеют зависимости от других пакетов." + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "trove-classifiers" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" +"`Проблемы `__ | `GitHub " +"`__ | `PyPI `__" + +#: ../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 " +"`_, которые сопровождающие проектов " +"используют для :ref:`систематического описания своих проектов `, чтобы пользователи могли лучше находить проекты, " +"соответствующие их потребностям, на PyPI." + +#: ../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 `_. На трекере `issue tracker `_ проекта ведутся обсуждения предлагаемых " +"классификаторов и запросы на новые классификаторы." + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "twine" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Документы `__ | `Проблемы `__ | `GitHub `__ | `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 Package Index или другие индексы пакетов Python. Это " +"программа командной строки, которая передает файлы программ и метаданные в " +"веб-интерфейс. Разработчики используют его, потому что это официальный " +"инструмент загрузки PyPI, он быстрый и безопасный, его поддерживают, и он " +"надежно работает." + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "virtualenv" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Документация `__ | " +"`Замечания `__ | `GitHub `__ | `PyPI `__" + +#: ../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 - это инструмент для создания изолированных Python :term:`Virtual " +"Environments <Виртуальная среда>`, подобно :ref:`venv`. В отличие " +"от :ref:`venv`, virtualenv может создавать виртуальные среды для других " +"версий Python, которые он находит с помощью переменной окружения PATH. Он " +"также предоставляет удобные функции для настройки, поддержки, дублирования и " +"устранения неполадок в виртуальных средах. Для получения дополнительной " +"информации см. раздел :ref:`Создание и использование виртуальных сред`." + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "Warehouse" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" +"`Документы `__ | `Проблемы `__ | `GitHub `__" + +#: ../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 Package Index (PyPI)`. " +"Она размещена на сайте `pypi.org `_. Источник по " +"умолчанию для загрузки :ref:`pip`." + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "wheel" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Документы `__ | `Проблемы `__ | `GitHub `__ | `PyPI `__" + +#: ../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 предлагает расширение " +"``bdist_wheel`` :ref:`setuptools`` для создания дистрибутивов :term:`wheel " +"`. Кроме того, он предлагает собственную утилиту командной строки " +"для создания и установки колес." + +#: ../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 "" +"См. также `auditwheel `__, инструмент, " +"который разработчики пакетов используют для проверки и исправления пакетов " +"Python, которые они создают в формате бинарного колеса. Он предоставляет " +"функциональность для обнаружения зависимостей, проверки метаданных на " +"соответствие, а также исправления колеса и метаданных для правильного " +"связывания и включения внешних общих библиотек в пакет." + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "Проекты, не связанные с PyPA" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "buildout" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" +"`Документы `__ | `Проблемы `__ | `PyPI `__ | `GitHub `__" + +#: ../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 "" +"Buildout - это система сборки на основе Python для создания, сборки и " +"развертывания приложений из нескольких частей, некоторые из которых могут " +"быть не на основе Python. Она позволяет создать конфигурацию сборки и " +"воспроизвести то же самое программное обеспечение позже." + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "conda" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr ":doc:`Документы `" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" +"Conda - это система управления пакетами, зависимостями и окружением для " +"любого языка - Python, R, Ruby, C/C++, Fortran и других. Она написана на " +"языке Python и широко используется в сообществе научных вычислений на Python " +"благодаря поддержке непитоновских компилируемых библиотек и расширений. На " +"нем основан дистрибутив `Anaconda `__ " +"Python от Anaconda, Inc. Изначально он был ориентирован на научное " +"сообщество, но также может использоваться самостоятельно или вместе с " +"системами :doc:`miniconda `, `miniforge `_ или `pixi `_. Он доступен для " +"систем Windows, Mac и Linux." + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" +"Conda является совершенно отдельным инструментом от :ref:`pip`, virtualenv и " +"wheel, но предоставляет многие из их объединенных возможностей, таких как " +"управление пакетами, управление виртуальным окружением и развертывание " +"бинарных расширений и другого бинарного кода." + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" +"Conda не устанавливает пакеты из PyPI - она может управлять только пакетами, " +"созданными специально для conda, которые могут быть доступны на «канале " +"conda», например, размещенном на `anaconda.org `__, " +"или на локальном (например, интранет) сервере пакетов. В дополнение к " +"каналам «по умолчанию», управляемым `Anaconda, Inc. `__, существует широкий спектр пакетов из поддерживаемого " +"сообществом проекта `conda-forge `__" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" +"Обратите внимание, что :ref:`pip` может быть установлен и работать бок о бок " +"с conda для управления :term:`distributions ` из PyPI. " +"Также можно собирать пакеты conda из исходных пакетов Python с помощью таких " +"инструментов, как `conda skeleton `__: " +"инструмент для автоматического создания пакетов conda из пакетов Python, " +"доступных на PyPI." + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "devpi" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" +"`Документы `__ | :gh:`Проблемы ` | `PyPI `__" + +#: ../source/key_projects.rst:441 +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." +msgstr "" +"devpi - это мощный PyPI-совместимый сервер и прокси-кэш PyPI с " +"дополнительным инструментом командной строки для управления процессами " +"упаковки, тестирования и выпуска на Python. devpi также предоставляет веб-" +"интерфейс с возможностью просмотра и поиска. devpi поддерживает " +"зеркалирование PyPI, несколько индексов пакетов <Пакетный индекс>` с " +"наследованием, синхронизацию между этими индексами, репликацию индекса и " +"восстановление после отказа, а также загрузку пакетов." + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "dumb-pypi" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" +"`GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:457 +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 - это простой : термин:`пакетный индекс <Пакетный индекс>` " +"генератор статических файлов сайта, который затем должен быть размещен на " +"статическом файловом веб-сервере, чтобы стать пакетным индексом. Он " +"поддерживает обслуживание хэша, основных метаданных и yank-статуса." + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "enscons" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" +":gh:`Source ` | :gh:`Проблемы ` | " +"`PyPI `__" + +#: ../source/key_projects.rst:470 +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 - это инструмент для упаковки на Python, основанный на `SCons`_. Он " +"собирает :ref:`pip`-совместимые исходные дистрибутивы и колеса без " +"использования distutils или setuptools, включая дистрибутивы с расширениями " +"C. Enscons имеет другую архитектуру и философию, чем :ref:`distutils`. " +"Вместо того, чтобы добавлять функции сборки в систему упаковки Python, " +"enscons добавляет упаковку Python в систему сборки общего назначения. " +"Enscons помогает вам создавать sdists, которые могут быть автоматически " +"собраны :ref:`pip`, и колеса, которые не зависят от enscons." + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "Flask-Pypi-Proxy" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" +"`документация `__ | :gh:`GitHub " +"` | `PyPI `__" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "Не поддерживается, проект сдан в архив" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" +"Flask-Pypi-Proxy - это : термин:`индекс пакета <Индекс пакета>` в качестве " +"кэшированного прокси для PyPI." + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "Hashdist" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" +"`Документы `__ | `GitHub " +"`__" + +#: ../source/key_projects.rst:504 +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истам лучше всего думать о " +"Hashdist как о более мощном гибриде :ref:`virtualenv` и :ref:`buildout`. Он " +"нацелен на решение проблемы установки научного программного обеспечения и " +"делает распространение пакетов нестационарным, кэшируемым и ветвящимся. " +"Используется некоторыми исследователями, но с 2016 года не поддерживается." + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "Maturin" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" +"`Документы `__ | `GitHub `__" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" +"Maturin - это бэкенд для сборки модулей расширения Rust, также написанный на " +"Rust. Он поддерживает сборку колес для python 3.7+ под Windows, Linux, macOS " +"и FreeBSD, может загружать их в PyPI и имеет базовую поддержку PyPy и " +"GraalPy." + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "meson-python" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" +"`Документы `__ | `GitHub " +"`__" + +#: ../source/key_projects.rst:534 +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/key_projects.rst:544 +msgid "multibuild" +msgstr "multibuild" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "`GitHub `__" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" +"Multibuild - это набор CI-скриптов для сборки и тестирования " +"Python :term:`wheels ` для Linux, macOS и (менее гибко) Windows. " +"Также смотрите :ref:`cibuildwheel`." + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "nginx_pypi_cache" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr ":gh:`GitHub `" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" +"nginx_pypi_cache - это : термин:`пакетный индекс <пакетный индекс>` " +"кэширующего прокси, использующего `nginx `_." + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "pdm" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Документы `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:570 +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. Он " +"использует :term:`pyproject.toml` для хранения метаданных проекта, как " +"определено в :pep:`621`." + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Документы `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:582 +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 - это инструмент для генерации :file:`.pex` (Python EXecutable) файлов, " +"автономных окружений Python в духе :ref:`virtualenv`. Файлы PEX - " +"это :doc:`zipapps `, которые делают развертывание " +"приложений Python таким же простым, как ``cp``. Один PEX-файл может " +"поддерживать несколько целевых платформ и может быть создан из " +"стандартных :ref:`pip`-разрешаемых требований, файла блокировки, созданного " +"с помощью ``pex3 lock ...`` или даже другого PEX. В PEX-файлы могут быть " +"встроены инструменты, поддерживающие превращение PEX-файла в стандартный " +"venv, построение графиков зависимостей и многое другое." + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "pip-инструменты" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Документы `__ | `GitHub " +"`__ | `PyPI `__" + +#: ../source/key_projects.rst:600 +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." +msgstr "" +"pip-tools - это набор инструментов, предназначенных для системных " +"администраторов Python и менеджеров релизов, которые особенно хотят " +"сохранить детерминированность своих сборок и при этом быть в курсе новых " +"версий своих зависимостей. Пользователи могут указать конкретный релиз своих " +"зависимостей через хэш, удобно составить правильно оформленный список " +"требований из информации в других частях своей программы, обновить все " +"зависимости (функция, которую :ref:`pip` в настоящее время не " +"предоставляет), а также создать слои ограничений, которым должна подчиняться " +"программа." + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "pip2pi" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +":gh:`GitHub <волевой/pip2pi>` | `PyPI `__" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" +"pip2pi - это сервер : термин:`индекс пакетов <Индекс пакетов>`, на котором " +"вручную синхронизируются определенные пакеты." + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "piwheels" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" +"Веб-сайт `__ | :doc:`Docs ` | " +"`GitHub `__" + +#: ../source/key_projects.rst:629 +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 "" +"piwheels - это веб-сайт и программное обеспечение, лежащее в его основе, " +"которое собирает пакеты дистрибутива исходного кода с PyPI и компилирует их " +"в бинарные диски, оптимизированные для установки на компьютеры Raspberry Pi. " +"В Raspberry Pi OS предварительно настроен pip на использование piwheels.org " +"в качестве дополнительного индекса к PyPI." + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "поэзия" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Документы `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:644 +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." +msgstr "" +"poetry - это инструмент командной строки для установки и изоляции " +"зависимостей, а также сборки и упаковки пакетов Python. Он использует " +"``pyproject.toml`` и, вместо того, чтобы зависеть от функциональности " +"разрешителя в :ref:`pip``, предоставляет свой собственный разрешитель " +"зависимостей. Он пытается ускорить процесс установки и разрешения " +"зависимостей, локально кэшируя метаданные о зависимостях." + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "proxpi" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +":gh:`GitHub ` | `PyPI `__" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" +"proxpi - это простой : термин:`индекс пакетов <Индекс пакетов>`, который " +"проксирует PyPI и другие индексы с кэшированием." + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "Pulp-python" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" +"`Документация `__ | :gh:`GitHub " +"` | `PyPI `__." + +#: ../source/key_projects.rst:671 +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." +msgstr "" +"Pulp-python - это плагин Python : термин:`пакетный индекс <Пакетный индекс>` " +"для `Pulp `_. Pulp-python поддерживает зеркала, " +"поддерживаемые локальным или `AWS S3`_, загрузку пакетов и проксирование к " +"нескольким индексам пакетов." + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "Облако PyPI" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" +"`Документация `__ | :gh:`GitHub ` | `PyPI `__." + +#: ../source/key_projects.rst:687 +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." +msgstr "" +"PyPI Облако - это : термин:`индекс пакетов <Индекс пакетов>` сервер, " +"поддерживающий `AWS S3`_ или другой облачный сервис хранения, или локальные " +"файлы. PyPI Облако поддерживает перенаправление/кэширование прокси для PyPI, " +"а также аутентификацию и авторизацию." + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "pypiprivate" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +":gh:`GitHub ` | `PyPI `__" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" +"pypiprivate обслуживает локальную (или размещенную на `AWS S3`_ директорию " +"пакетов как : термин:`пакетный индекс <Пакетный индекс>`." + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "pypiserver" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" +"`GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:711 +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." +msgstr "" +"pypiserver - это минималистичное приложение, которое служит в качестве " +"частного Python : термин:`индекс пакетов <Пакетный индекс>` (из локальной " +"директории) в организациях, реализуя простой API и интерфейс браузера. Вы " +"можете загружать частные пакеты с помощью стандартных инструментов загрузки, " +"а пользователи могут скачивать и устанавливать их с помощью : ссылка:`pip`, " +"не публикуя их публично. Организации, использующие pypiserver, обычно " +"загружают пакеты как с pypiserver, так и с PyPI." + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "PyScaffold" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Документы `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:728 +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/key_projects.rst:739 +msgid "pywharf" +msgstr "pywharf" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +":gh:`GitHub ` | `PyPI `__" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" +"pywharf - это сервер : термин:`пакетный индекс <Пакетный индекс>`, " +"обслуживающий файлы локально или с `GitHub `_." + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "scikit-build" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Документы `__ | `GitHub " +"`__ | `PyPI `__" + +#: ../source/key_projects.rst:758 +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 - это :ref:`setuptools` обертка для CPython, которая собирает " +"расширения C/C++/Fortran/Cython. Она использует `cmake `__ (доступен на PyPI) для обеспечения лучшей поддержки " +"дополнительных компиляторов, систем сборки, кросс-компиляции, а также поиска " +"зависимостей и связанных с ними требований к сборке. Для ускорения и " +"распараллеливания сборки больших проектов пользователь может установить " +"`ninja `__ (также доступен на PyPI)." + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "scikit-build-core" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" +"`Документы `__ | " +"`GitHub `__ | `PyPI " +"`__" + +#: ../source/key_projects.rst:775 +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." +msgstr "" +"Scikit-build-core - это бэкенд сборки для расширений CPython C/C++/Fortran/" +"Cython. Он позволяет пользователям писать расширения с помощью `cmake " +"`__ (доступен на PyPI), обеспечивая лучшую " +"поддержку дополнительных компиляторов, систем сборки, кросс-компиляции, а " +"также поиска зависимостей и связанных с ними требований к сборке. CMake/" +"Ninja автоматически загружаются с PyPI, если не доступны в системе." + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "shiv" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Документы `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:791 +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." +msgstr "" +"shiv - это утилита командной строки для создания полностью самодостаточных " +"Python zipapps, как описано в :pep:`441`, но с включением всех зависимостей. " +"Ее основная цель - сделать распространение Python-приложений и инструментов " +"командной строки быстрым и легким." + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "simpleindex" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +":gh:`GitHub ` | `PyPI `__" + +#: ../source/key_projects.rst:804 +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." +msgstr "" +"simpleindex - это : термин:`индекс пакетов <Пакетный индекс>`, который " +"направляет URL к нескольким индексам пакетов (включая PyPI), обслуживает " +"локальные (или размещенные в облаке, например, `AWS S3`_, с помощью " +"пользовательского плагина) каталоги пакетов, а также поддерживает " +"пользовательские плагины." + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" +":doc:`Документы ` | `GitHub `__ " +"| `Paper `__ | `Slides `__" + +#: ../source/key_projects.rst:819 +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 похож на Homebrew, но пакеты " +"написаны на Python и параметризованы, что позволяет легко менять местами " +"компиляторы, версии библиотек, параметры сборки и т. д. На одной системе " +"может сосуществовать произвольное количество версий пакетов. Spack был " +"разработан для быстрого создания высокопроизводительных научных приложений " +"на кластерах и суперкомпьютерах." + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" +"Spack нет в PyPI (пока), но он не требует установки и может быть использован " +"сразу после клонирования с GitHub." + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "zest.releaser" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Документы `__ | `GitHub " +"`__ | `PyPI `__" + +#: ../source/key_projects.rst:839 +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." +msgstr "" +"``zest.releaser`` - это инструмент для выпуска пакетов на Python, " +"предоставляющий слой абстракции поверх :ref:`twine``. Разработчики Python " +"используют ``zest.releaser`` для автоматизации увеличения номеров версий " +"пакетов, обновления журналов изменений, маркировки релизов в системе " +"контроля исходного кода и загрузки новых пакетов в PyPI." + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "Проекты в стандартное библиотеке" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "ensurepip" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" +"`Документация `__ | " +"`Замечания `__" + +#: ../source/key_projects.rst:856 +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." +msgstr "" +"Пакет стандартной библиотеки Python, обеспечивающий поддержку " +"загрузки :ref:`pip` в существующую установку Python или виртуальную среду. " +"В большинстве случаев конечные пользователи не будут использовать этот " +"модуль, скорее он будет использоваться во время сборки дистрибутива Python." + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "http.server" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" +": Док:`Документы ` | :gh:`Выпуски `" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" +"Пакет и интерфейс командной строки, который может размещать каталог в виде " +"сайта, например, как : термин:`пакетный индекс <Пакетный индекс>` " +"(см. :ссылка:`Хостинг собственного простого репозитория`)." + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "venv" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" +"`Документация `__ | `Замечания " +"`__" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" +"Пакет в стандартной библиотеке Python (начиная с Python 3.3) для " +"создания :term:`виртуальных сред `. Для получения " +"дополнительной информации см. раздел :ref:`Создание и использование " +"виртуальных сред`." + +#: ../source/news.rst:2 +msgid "News" +msgstr "Новости" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" +"В настоящее время этот документ не обновляется. Ранее в этом документе " +"освещались изменения в упаковке Python." + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "Сентябрь 2019" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" +"Добавлено руководство по публикации дистрибутивов через GitHub Actions. " +"(:pr:`647`)" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "Август 2019" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" +"Обновлено для использования :file:`python3 -m` при установке pipx. " +"(:pr:`631`)" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "Июль 2019" + +#: ../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 "Обновлена версия Sphinx и удален pypa.io intersphinx. (:pr:`625`)" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "Упоминается :file:`find_namespace_packages`. (:pr:`622`)" + +#: ../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" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "Исправлены некоторые опечатки. (:pr:`620`)" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "Май 2019" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" +"В учебник по упаковке добавлено использование :file:`python_requires`. " +"(:pr:`613`)" + +#: ../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" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" +"Добавлено упоминание о :file:`shiv` в разделе ключевых проектов. (:pr:`608`)" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "Уменьшен акцент на virtualenv. (:pr:`606`)" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "Март 2019" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" +"Переместите опцию версии руководства для одиночного сорсинга в Python 3. " +"(:pr:`605`)" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "Покрытые детали RTD для внесения вклада. (:pr:`600`)" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "Февраль 2019" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" +"Подробно расскажите о различиях между учебным пособием и реальным процессом " +"упаковки. (:pr:`602`)" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "Добавлены инструкции по установке приложений Python CLI. (:pr:`594`)" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "Январь 2019" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "В учебник по упаковке добавлен :file:`--no-deps`. (:pr:`593`)" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "Обновлены Сфинкс и Нокс. (:pr:`591`)" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "Ссылка на Twine из Python3. (:pr:`581`)" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "Декабрь 2018" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "Никаких программистов в офисе!" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "Ноябрь 2018" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" +"Удалена ссылка на целевую страницу с руководством по миграции PyPI. " +"(:pr:`575`)" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "Заменена bumpversion на bump2version. (:pr:`572`)" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "Добавлен пример версии пакета с одним источником. (:pr:`573`)" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "Добавлено руководство по созданию документации. (:pr:`568`)" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "Октябрь 2018" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "Обновлено имя пакета Nox. (:pr:`566`)" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "Упоминание расширений Sphinx в руководствах. (:pr:`562`)" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "Сентябрь 2018" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "Добавлен раздел о проверке разметки RST. (:pr:`554`)" + +#: ../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. (:pr:`556`)" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "Замененная команда tar с рабочей командой. (:pr:`552')" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" +"Заменены на двойные кавычки в pip install SomeProject==1.4. (:pr:`550`)" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "Август 2018" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "Удалена рекомендация хранить пароли в открытом виде. (:pr:`546`)" + +#: ../source/news.rst:81 +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 "Обновлена версия Python, поддерживаемая virtualenv. (:pr:`538`)" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "Добавлен набросок/черновик новой страницы \"Обзор\". (:pr:`519`)" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "Июль 2018" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "Улучшена документация по бинарным расширениям. (:pr:`531`)" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "Добавлена scikit-build в ключевые проекты. (:pr:`530`)" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "Июнь 2018" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "Исправлены категории interop PEP для pypa.io. (:pr:`527`)" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "Обновлены пояснения к описаниям в формате Markdown. (:pr:`522`)" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "Май 2018" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "Замечены проблемы с Provides-Dist и Obsoletes-Dist. (:pr:`513`)" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" +"Убрано устаревшее предупреждение о смешивании версий Python с Pipenv. " +"(:pr:`501`)" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "Упрощенный учебник по упаковке. (:pr:`498`)" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" +"Обновлены инструкции для пользователей Windows для большей ясности. " +"(:pr:`493`)" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "Обновлено описание раздела лицензии для полноты. (:pr:`492`)" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "В раздел вкладов добавлен документ в стиле спецификации. (:pr:`489`)" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" +"Добавлены типы документации в руководство по внесению вкладов. (:pr:`485`)" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "Апрель 2018" + +#: ../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 "Добавлены инструкции для Хранилища. (:pr:`471`)" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "Удалены ссылки на GPG из руководства по публикации. (:pr:`466`)" + +#: ../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/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" +"Добавлено руководство по постепенному отказу от версий Python. (:pr:`459`)" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "Сделан вариант Description-Content-Type по умолчанию GFM. (:pr:`462`)" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "Март 2018" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "Обновлена \"Установка научных пакетов\". (:pr:`455`)" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" +"Добавлен :file:`long_description_content_type`, чтобы следовать PEP 556. " +"(:pr:`457`)" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "Уточнен классификатор длинных описаний на pypi.org. (:pr:`456`)" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" +"Обновление спецификации Core Metadata в соответствии с PEP 556. (:pr:`412`)" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "Февраль 2018" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" +"Добавлены python3-venv и python3-pip в инструкции по установке Debian. " +"(:pr:`445`)" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "Обновлена информация о миграции PyPI. (:pr:`439`)" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" +"Добавлено предупреждение об управлении несколькими версиями с помощью " +"pipenv. (:pr:`430`)" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "Добавлен пример нескольких писем в Core Metadata. (:pr:`429`)" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "Добавлено объяснение \"legacy\" в test.pypi.org/legacy. (:pr:`426`)" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "Январь 2018" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "Добавлена ссылка на список классификаторов PyPI. (:pr:`425`)" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "Обновлено пояснение в README.rst. (:pr:`419`)" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "Декабрь 2017" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" +"Заменено :file:`~` на :file:`$HOME` в руководствах и учебниках. (:pr:`418`)" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" +"Уточнено, какие поля могут использоваться с маркерами окружения. (:pr:`416`)" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "Обновлен раздел Requires-Python. (:pr:`414`)" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "Добавлена страница новостей (:pr:`404`)" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "Ноябрь 2017" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" +"Представлен новый учебник по управлению зависимостями на основе Pipenv. " +"(:pr:`402`)" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" +"Обновлен учебник *Версия пакета единого источника*.чтобы отразить текущую " +"стратегию pip. (:pr:`400`)" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" +"Добавлена документация об аргументе ``py_modules`` в ``setup``. (:pr:`398`)" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "Упрощена формулировка раздела :file:`manifest.in`. (:pr:`395`)" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "Октябрь 2017" + +#: ../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/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" +"Создано новое руководство по управлению пакетами с помощью ``pip`` и " +"``virtualenv``. (:pr:`385`)" + +#: ../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" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" +"Рекомендовано использовать ``readme_renderer`` для " +"проверки :file:`README.rst`. (:pr:`379`)" + +#: ../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" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" +"Добавлен новый, экспериментальный учебник по установке пакетов с помощью " +"``Pipenv``. (:pr:`369`)" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "Добавлено новое руководство по использованию ``TestPyPI``. (:pr:`366`)" + +#: ../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" + +#: ../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 "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" +"Обновлено ``readme`` этого руководства с инструкциями о том, как собрать " +"руководство локально. (:pr:`356`)" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" +"Сделали новый URL ``TestPyPI`` более заметным, добавив на главную страницу " +"заметку о pypi.org. (:pr:`354`)" + +#: ../source/news.rst:187 +msgid "" +"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" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "Добавлен документ о переносе загрузок в :file:`PyPI.org`. (:pr:`339`)" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "Добавлена документация для ``python_requires``. (:pr:`338`)" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" +"Добавлено примечание о миграции на PyPI в руководстве *Рекомендации " +"инструментов*. (:pr:`335`)" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" +"Добавлено примечание о том, что :file:`manifest.in` не влияет на колеса. " +"(: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 "Расширен раздел, посвященный аргументу ``имя``. (: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`)" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "Май 2017" + +#: ../source/news.rst:206 +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`)" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" +"Документированы различия между ``pip`` и ``easy_install`` для индексов по " +"проектам. (:pr:`233`)" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "Апрель 2017" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" +"Добавлена конфигурация travis для тестирования pull-запросов. (:pr:`300`)" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" +"Упоминание о необходимости использования пакета ``wheel`` для создания колес " +"(:pr:`299`)" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" +"Удалена ссылка на ``twine register`` в руководстве *Распространение " +"пакетов*. (:pr:`271`)" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "Добавлена тема по обнаружению плагинов. (:pr:`294`, :pr:`296`)" + +#: ../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 "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" +"Обновлена документация по режиму разработки, чтобы упомянуть, что порядок " +"локальных пакетов имеет значение. (:pr:`208`)" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" +"Преобразование ссылки readthedocs для их миграции на ``.org`` -> ``.io`` для " +"размещенных проектов (:pr:`239`)" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" +"Поменяли местами порядок аргументов :file:`setup.py` для команды upload, так " +"как порядок имеет значение. (:pr:`260`)" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" +"Объяснено, как устанавливать из неподдерживаемых источников с помощью " +"вспомогательного приложения. (:pr:`289`)" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "Март 2017" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "Покрытие ``manylinux1`` в *Platform Wheels*. (:pr:`283`)" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "Февраль 2017" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "Добавлен :pep:`518` (:pr:`281`)" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "Обзор упаковки Python" + +#: ../source/overview.rst:7 +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." +msgstr "" +"Будучи языком программирования общего назначения, Python предназначен для " +"разнообразного использования. Вы можете создавать веб-сайты, промышленных " +"роботов, игры для своих друзей и многое другое, используя одну и ту же " +"базовую технологию." + +#: ../source/overview.rst:12 +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." +msgstr "" +"Гибкость Python - вот почему первым шагом в каждом проекте на Python должно " +"быть обдумывание аудитории проекта и соответствующего окружения, в котором " +"он будет работать. Может показаться странным думать об упаковке до написания " +"кода, но этот процесс позволяет избежать головной боли в будущем." + +#: ../source/overview.rst:18 +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." +msgstr "" +"В этом обзоре представлено дерево решений общего назначения для рассуждений " +"о множестве вариантов упаковки Python. Читайте дальше, чтобы выбрать лучшую " +"технологию для вашего следующего проекта." + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "Мысли о развёртывании" + +#: ../source/overview.rst:25 +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:" +msgstr "" +"Пакеты существуют для того, чтобы их устанавливали (или *развертывали*), " +"поэтому прежде чем упаковывать что-либо, вам нужно получить ответы на " +"вопросы по развертыванию, приведенные ниже:" + +#: ../source/overview.rst:29 +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?" +msgstr "" +"Кто будет пользоваться вашим программным обеспечением? Будет ли ваше " +"программное обеспечение устанавливаться другими разработчиками, " +"занимающимися разработкой программного обеспечения, операторами в центре " +"обработки данных или другими людьми, менее подкованными в вопросах " +"программного обеспечения?" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" +"Ваше программное обеспечение устанавливается индивидуально или большими " +"партиями?" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "Python'ьи библиотеки и инструменты для упаковки" + +#: ../source/overview.rst:45 +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`." +msgstr "" +"Возможно, вы слышали о PyPI, ``setup.py`` и ``wheel`` файлах. Это лишь " +"некоторые из инструментов, предоставляемых экосистемой Python для " +"распространения кода Python среди разработчиков, о которых вы можете " +"прочитать в :doc:`guides/distributing-packages-using-setuptools`." + +#: ../source/overview.rst:50 +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`." +msgstr "" +"Следующие подходы к упаковке предназначены для библиотек и инструментов, " +"используемых технической аудиторией в условиях разработки. Если вы ищете " +"способы упаковки Python для нетехнической аудитории и/или в производственных " +"условиях, переходите к :ref:`packaging-applications`." + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "Модули Python'а" + +#: ../source/overview.rst:58 +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." +msgstr "" +"Файл Python, если он опирается только на стандартную библиотеку, может быть " +"распространен и использован повторно. Вам также нужно убедиться, что он " +"написан для правильной версии Python и опирается только на стандартную " +"библиотеку." + +#: ../source/overview.rst:63 +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 " +"`." +msgstr "" +"Это отлично подходит для обмена простыми скриптами и фрагментами между " +"людьми, у которых обе версии Python совместимы (например, по электронной " +"почте, через StackOverflow или GitHub gists). Есть даже целые библиотеки " +"Python, которые предлагают такую возможность, " +"например :doc:`bottle.py` и :doc:`boltons " +"`." + +#: ../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/overview.rst:75 +msgid "Python source distributions" +msgstr "Дистрибутивы с исходным кодом Python" + +#: ../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:`Import Package`." + +#: ../source/overview.rst:81 +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." +msgstr "" +"Поскольку пакеты состоят из нескольких файлов, их сложнее распространять. " +"Большинство протоколов поддерживают передачу только одного файла за раз " +"(когда вы в последний раз нажимали на ссылку и она загружала несколько " +"файлов?). Легче получить неполную передачу, и сложнее гарантировать " +"целостность кода в месте назначения." + +#: ../source/overview.rst:87 +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." +msgstr "" +"Если ваш код содержит только чистый код Python, и вы знаете, что ваша среда " +"развертывания поддерживает вашу версию Python, то вы можете использовать " +"собственные средства упаковки Python для создания " +"*source* :term:`Distribution Package`, или *sdist* для краткости." + +#: ../source/overview.rst:92 +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." +msgstr "" +"Python'овские *sdists* - это сжатые архивы (файлы ``.tar.gz``), содержащие " +"один или несколько пакетов или модулей. Если ваш код - это чистый Python, и " +"вы зависите только от других пакетов Python, вы можете обратиться к " +"спецификации :ref:`source-distribution-format`, чтобы узнать больше." + +#: ../source/overview.rst:97 +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." +msgstr "" +"Если вы полагаетесь на какой-либо не-Python код или не-Python пакеты " +"(например, `libxml2 `_ в случае `lxml " +"`_, или BLAS библиотеки в случае `numpy " +"`_), вам нужно будет использовать формат, " +"подробно описанный в следующем разделе, который также имеет много " +"преимуществ для чисто-Python библиотек." + +#: ../source/overview.rst:104 +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!" +msgstr "" +"Python и PyPI поддерживают несколько дистрибутивов, предоставляющих " +"различные реализации одного и того же пакета. Например, неосновной, но " +"многозначительный дистрибутив `PIL `_ " +"предоставляет пакет PIL, как и `Pillow `_, " +"активно поддерживаемый форк PIL!" + +#: ../source/overview.rst:111 +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``." +msgstr "" +"Эта суперспособность упаковки Python позволяет Pillow стать полноценной " +"заменой PIL, просто изменив ``install_requires`` или ``requirements.txt`` в " +"вашем проекте." + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "Бинарные дистрибутивы Python" + +#: ../source/overview.rst:118 +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." +msgstr "" +"Практическая мощь Python во многом обусловлена его способностью " +"интегрироваться с экосистемой программного обеспечения, в частности с " +"библиотеками, написанными на C, C++, Fortran, Rust и других языках." + +#: ../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." +msgstr "" +"Не у всех разработчиков есть нужные инструменты или опыт для создания " +"компонентов, написанных на этих компилируемых языках, поэтому Python " +"создал :term:`Wheel`, формат пакета, предназначенный для поставки библиотек " +"со скомпилированными артефактами. На самом деле, программа установки пакетов " +"Python, ``pip``, всегда предпочитает wheels, потому что установка всегда " +"быстрее, поэтому даже чисто питоновские пакеты лучше работают с wheels." + +#: ../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 "" +"Лучше всего, когда бинарные дистрибутивы сопровождаются дистрибутивами с " +"исходным кодом. Даже если вы не выкладываете \"колеса\" своего кода для " +"каждой операционной системы, выкладывая sdist, вы даете возможность " +"пользователям других платформ собрать его для себя. По умолчанию " +"рекомендуется публиковать архивы sdist и wheel вместе, *за исключением " +"случаев, когда вы создаете артефакты для очень специфического случая " +"использования, когда вы знаете, что получателю нужно только одно или другое." + +#: ../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." +msgstr "" +"Python и PyPI позволяют легко загружать и wheels, и sdists вместе. Просто " +"следуйте руководству :doc:`tutorials/packaging-projects`." + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" +"Краткое описание возможностей Python по упаковке инструментов и библиотек." + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" +"Рекомендуемые в Python технологии упаковки встроенных библиотек и " +"инструментов. Отрывок из книги `Градиент упаковки (2017) `_." + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "Упаковка Python'ьих приложений" + +#: ../source/overview.rst:154 +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." +msgstr "" +"До сих пор мы обсуждали только встроенные средства распространения Python. " +"Исходя из нашего вступления, вы можете сделать вывод, что эти встроенные " +"подходы предназначены только для сред, в которых есть Python, и для " +"аудитории, которая знает, как устанавливать пакеты Python." + +#: ../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/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 в основном создана для распространения " +"многократно используемого кода, называемого библиотеками, между " +"разработчиками. Вы можете создавать **инструменты**, или базовые приложения " +"для разработчиков, поверх упаковки библиотек Python, используя такие " +"технологии, как :doc:`setuptools entry_points `." + +#: ../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." +msgstr "" +"Библиотеки - это строительные блоки, а не готовые приложения. Для " +"распространения приложений существует целый мир новых технологий." + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "В зависимости от фреймворка" + +#: ../source/overview.rst:180 +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." +msgstr "" +"Некоторые типы приложений Python, такие как бэкенды веб-сайтов и другие " +"сетевые сервисы, достаточно распространены, чтобы для их разработки и " +"упаковки существовали фреймворки. Другие типы приложений, такие как " +"динамические веб-фронтенды и мобильные клиенты, достаточно сложны, чтобы " +"фреймворк стал не просто удобством." + +#: ../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." +msgstr "" +"Во всех этих случаях имеет смысл работать в обратном направлении, начиная с " +"истории упаковки и развертывания фреймворка. Некоторые фреймворки включают в " +"себя систему развертывания, в которой используются технологии, описанные в " +"остальной части руководства. В этих случаях вам лучше обратиться к " +"руководству по упаковке вашего фреймворка, чтобы получить наиболее простой и " +"надежный опыт производства." + +#: ../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." +msgstr "" +"Если вам интересно, как эти платформы и фреймворки работают \"под капотом\", " +"вы всегда можете прочитать разделы дальше." + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "Сервисные платформы" + +#: ../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 "" +"Если вы разрабатываете для \"Платформы как сервиса `_\" или \"PaaS\", вам следует следовать " +"соответствующим руководствам по упаковке. Эти типы платформ берут на себя " +"заботу об упаковке и развертывании, если вы следуете их шаблонам. " +"Большинство программ не подходит ни под один из этих шаблонов, поэтому " +"существуют все остальные варианты, описанные ниже." + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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/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/overview.rst:220 +#, fuzzy +msgid "`Kivy `_" +msgstr "`Kivy `_" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "`Beeware `_" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "`Brython `_" + +#: ../source/overview.rst:223 +#, fuzzy +msgid "`Flexx `_" +msgstr "`Flexx `_" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "В зависимости от предустановленного Python'а" + +#: ../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/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "Технологии, поддерживающие эту модель:" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr ":gh:`PEX ` (исполняемый файл Python)" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" +":doc:`zipapp ` (не помогает управлять зависимостями, " +"требует Python 3.5+)" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr ":gh:`shiv ` (требуется Python 3)" + +#: ../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/overview.rst:249 +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 "" +"В общем случае уменьшение зависимости от целевой системы увеличивает размер " +"нашего пакета, поэтому решения здесь расположены примерно по возрастанию " +"размера выхода." + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" +"В зависимости от отдельной экосистемы распространения программного " +"обеспечения" + +#: ../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, не имели " +"встроенных средств управления пакетами. Лишь недавно в этих ОС появились так " +"называемые \"магазины приложений\", но даже они ориентированы на " +"потребительские приложения и мало что предлагают разработчикам." + +#: ../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/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "Инструкции по созданию и публикации для экосистемы Anaconda:" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" +"`Создание библиотек и приложений с помощью conda `_" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" +"`Переход родного пакета Python на Anaconda `_" + +#: ../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/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" +"`ActiveState ActivePython `_" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "`WinPython `_" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "Поставка собственного исполняемого файла Python'а" + +#: ../source/overview.rst:290 +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." +msgstr "" +"Вычислительная техника, как мы ее знаем, определяется способностью выполнять " +"программы. Каждая операционная система поддерживает один или несколько " +"форматов программ, которые она может выполнять." + +#: ../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/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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "Выбор морозильных камер Python:" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" +"`pyInstaller `_ – " +"кроссплатформенный" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" +"`cx_Freeze `_ - " +"Кроссплатформенный" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" +"`constructor `_ - Для инсталляторов " +"командной строки" + +#: ../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 "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" +"Большинство из вышеперечисленного подразумевает однопользовательское " +"развертывание. Для многокомпонентных серверных приложений смотрите :gh:`Chef " +"Omnibus `." + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "Поставка собственного пользовательского пространства" + +#: ../source/overview.rst:321 +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*." +msgstr "" +"Все больше операционных систем, включая Linux, Mac OS и Windows, могут быть " +"настроены на запуск приложений, упакованных в легкие образы, с помощью " +"относительно современной схемы, часто называемой `виртуализацией на уровне " +"операционной системы` `_, или *контейнеризацией*." + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" +"Эти методы в основном не зависят от Python, поскольку они упаковывают целые " +"файловые системы ОС, а не только Python или пакеты Python." + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" +"Наиболее широкое распространение эта технология получила на серверах под " +"управлением Linux, где она зародилась и где представленные ниже технологии " +"работают лучше всего:" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "`AppImage `_" + +#: ../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 +#, fuzzy +#| 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." +msgid "" +"Most desktop 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 "" +"Большинство операционных систем поддерживают ту или иную форму классической " +"виртуализации, позволяя запускать приложения, упакованные в образы, " +"содержащие полноценную операционную систему. Запуск таких виртуальных машин, " +"или ВМ, является зрелым подходом, широко распространенным в средах центров " +"обработки данных." + +#: ../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:" +msgstr "" +"Эти технологии в основном предназначены для крупномасштабных развертываний в " +"центрах обработки данных, хотя некоторые сложные приложения могут извлечь " +"выгоду из такой упаковки. Технологии не зависят от Python и включают в себя:" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" +"`VHD `_, `AMI `_, и :doc:`другие форматы " +"`" + +#: ../source/overview.rst:356 +#, fuzzy +#| msgid "" +#| "`OpenStack `_ - A cloud " +#| "management system in Python, with extensive VM support" +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" +"`OpenStack `_ - система " +"управления облаком на Python, с широкой поддержкой виртуальных машин" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "Поставка собственного оборудования" + +#: ../source/overview.rst:362 +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." +msgstr "" +"Самым универсальным способом доставки программного обеспечения является его " +"установка на какое-либо оборудование. Таким образом, пользователю вашей " +"программы потребуется только электричество." + +#: ../source/overview.rst:366 +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/overview.rst:370 +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/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" +"Краткое описание технологий, используемых для упаковки приложений Python." + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" +"Упрощенный набор технологий, используемых для упаковки приложений на Python." + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "Как насчёт..." + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "Пакетов операционной системы" + +#: ../source/overview.rst:390 +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:`зависимость от отдельной экосистемы`, некоторые " +"операционные системы имеют собственные менеджеры пакетов. Если вы очень " +"уверены в операционной системе, на которую ориентируетесь, вы можете " +"напрямую зависеть от такого формата, как `deb `_ (для Debian, Ubuntu и т.д.) или `RPM `_ (для Red Hat, Fedora и т.д.), и " +"использовать этот встроенный менеджер пакетов для установки и даже " +"развертывания. Вы даже можете использовать `FPM `_ для генерации deb и RPM из одного " +"источника." + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" +"В большинстве pipконвейеров развертывания менеджер пакетов ОС является лишь " +"одним из элементов головоломки." + +#: ../source/overview.rst:407 +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." +msgstr "" +":doc:`Virtualenvs ` были незаменимым " +"инструментом для многих поколений разработчиков Python, но постепенно " +"исчезают из поля зрения, поскольку их обволакивают инструменты более " +"высокого уровня. В частности, при упаковке virtualenvs используются в " +"качестве примитива в :doc:`инструменте dh-virtualenv ` и `osnap `_, оба " +"из которых оборачивают virtualenvs в самодостаточный способ." + +#: ../source/overview.rst:416 +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." +msgstr "" +"При развертывании на производстве не стоит полагаться на запуск ``python -m " +"pip install`` из интернета в virtualenv, как это можно сделать в среде " +"разработки. В обзоре выше есть много лучших решений." + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "Безопасность" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" +"Чем дальше вниз по градиенту, тем сложнее обновлять компоненты вашего " +"пакета. Все более тесно связано друг с другом." + +#: ../source/overview.rst:426 +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 `_." +msgstr "" +"Например, если возникает проблема безопасности ядра, а вы развертываете " +"контейнеры, ядро хост-системы можно обновить, не требуя новой сборки от " +"имени приложения. Если же вы развертываете образы виртуальных машин, вам " +"потребуется новая сборка. Вопрос о том, делает ли эта динамика один из " +"вариантов более безопасным, все еще остается немного старым спором, " +"восходящим к до сих пор не решенному вопросу `статического и динамического " +"связывания `_." + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "Заключение" + +#: ../source/overview.rst:437 +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." +msgstr "" +"Упаковка в Python имеет репутацию не очень удобной. Это впечатление в " +"основном является побочным продуктом универсальности Python. Как только вы " +"поймете естественные границы между каждым решением для упаковки, вы начнете " +"понимать, что разнообразный ландшафт - это небольшая цена, которую " +"программисты на Python платят за использование одного из самых " +"сбалансированных и гибких языков." + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "Формат распространения двоичных пакетов" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" +"Эта страница определяет формат распространения бинарных пакетов Python, " +"также называемый форматом колеса." + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" +"Колесо - это архив формата ZIP со специальным именем файла и расширением " +"``.whl``. Он содержит один дистрибутив почти в том виде, в каком он будет " +"установлен согласно PEP 376 при определенной схеме установки. Хотя " +"рекомендуется использовать специализированный инсталлятор, файл wheel может " +"быть установлен простой распаковкой в site-пакеты стандартным инструментом " +"'unzip', сохраняя при этом достаточно информации для того, чтобы разложить " +"его содержимое по конечным путям в любое последующее время." + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "Детали" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "Установка колеса 'distribution-1.0-py32-none-any.whl'" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "Установка колес условно состоит из двух этапов:" + +#: ../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 "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" +"Проверка совместимости программы установки с Wheel-Version. Предупреждение, " +"если минорная версия больше, прерывание, если мажорная версия больше." + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" +"Если Root-Is-Purelib == 'true', распакуйте архив в purelib (site-packages)." + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "Иначе распакуйте архив в platlib (site-packages)." + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "Распространение." + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" +"Распакованный архив включает ``distribution-1.0.dist-info/`` и (если есть " +"данные) ``distribution-1.0.data/``." + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" +"Переместите каждое поддерево из ``распределение-1.0. данные/`` на путь " +"назначения. Каждый подкаталог ``распределение-1.0. данные/`` является ключом " +"к дикте директорий назначения, например ``распределение-1.0. данные/(purelib|" +"platlib|headers|scripts|data)``. Эти подкаталоги являются : ссылка:`путями " +"установки, определенными sysconfig `." + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" +"Если применимо, обновите скрипты, начинающиеся с ``#!python``, чтобы они " +"указывали на правильный интерпретатор." + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" +"Обновите ``distribution-1.0.dist-info/RECORD`` с установленными путями." + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "Удалите пустой каталог ``distribution-1.0.data``." + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" +"Скомпилируйте все установленные .py в .pyc. (Деинсталляторы должны быть " +"достаточно умны, чтобы удалять .pyc, даже если он не упомянут в RECORD)" + +#: ../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 "" +"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 "" +"В wheel скрипты упаковываются в ``{distribution}-{version}.data/scripts/``. " +"Если первая строка файла в ``scripts/`` начинается с ``b'#!python'``, " +"перепишите ее, чтобы она указывала на правильный интерпретатор. " +"Установщикам Unix может потребоваться добавить бит +x к этим файлам, если " +"архив был создан под Windows." + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" +"Допускается использование соглашения ``b'#!pythonw'``. ``b'#!pythonw'`` " +"указывает на графический, а не консольный сценарий." + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "Генерируйте обертки для скриптов." + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" +"В колесе скрипты, упакованные в Unix-системы, конечно, не будут иметь " +"сопровождающих .exe-оберток. Установщики Windows могут захотеть добавить их " +"во время установки." + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "Рекомендуемые функции архиватора" + +#: ../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 "" +"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 "" +"Архиваторам рекомендуется помещать файлы ``.dist-info`` физически в конец " +"архива. Это позволяет использовать некоторые потенциально интересные трюки " +"ZIP, включая возможность изменять метаданные, не переписывая весь архив." + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "Формат файла" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "Соглашение об именах файлов" + +#: ../source/specifications/binary-distribution-format.rst:92 +msgid "" +"The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" +"{abi tag}-{platform tag}.whl``." +msgstr "" +"Имя файла колеса - ``{distribution}-{version}(-{build tag})?-{python tag}-" +"{abi tag}-{platform tag}.whl``." + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "distribution" +msgstr "дистрибутив" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "Имя дистрибутива, например, 'django', 'pyramid'." + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../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 "" +"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 "" +"Необязательный номер сборки. Должен начинаться с цифры. Действует как " +"ограничитель, если два имени файлов wheel одинаковы по всем остальным " +"параметрам (т. е. по имени, версии и другим тегам). Сортируется как пустой " +"кортеж, если не указан, иначе сортируется как кортеж из двух элементов, где " +"первый элемент - начальные цифры в виде ``int'', а второй элемент - остаток " +"тега в виде ``str''." + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" +"Частым случаем использования номеров сборок является перестроение бинарного " +"дистрибутива из-за изменения среды сборки, например, при использовании " +"образа manylinux для сборки дистрибутивов, использующих предварительные " +"версии CPython." + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" +"Номера сборок не являются частью версии дистрибутива, поэтому на них сложно " +"ссылаться извне, особенно за пределами экосистемы инструментов и стандартов " +"Python. Чаще всего внешние ссылки на дистрибутив требуются при устранении " +"уязвимости в системе безопасности." + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" +"Из-за этого ограничения новые дистрибутивы, на которые необходимо ссылаться " +"извне, **не должны** использовать номера сборок при сборке нового " +"дистрибутива. Вместо этого в таких случаях следует создавать **новую версию " +"дистрибутива**." + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "реализация языка и тег версии" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "Например, 'py27', 'py2', 'py3'." + +#: ../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/binary-distribution-format.rst:135 +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." +msgstr "" +"Например, ``distribution-1.0-1-py27-none-any.whl`` - это первая сборка " +"пакета под названием \"distribution\", совместимая с Python 2.7 (любой " +"реализацией Python 2.7), без ABI (чистый Python), на любой архитектуре " +"процессора." + +#: ../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/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "Экранирование и Юникод" + +#: ../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/binary-distribution-format.rst:150 +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." +msgstr "" +"В именах дистрибутивов любые пробелы символов ``-_.`` (HYPHEN-MINUS, LOW " +"LINE и FULL STOP) должны быть заменены на ``_`` (LOW LINE), а прописные " +"символы должны быть заменены на соответствующие строчные. Это эквивалентно " +"регулярной :ref:`нормализации имени <имя-нормализация>` с последующей " +"заменой ``-`` на ``_``. Инструменты, использующие колеса, должны быть готовы " +"принять ``.`` (FULL STOP) и заглавные буквы, так как они были разрешены в " +"более ранней версии этой спецификации." + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" +"Номера версий должны быть нормализованы в соответствии с :ref:`Спецификация " +"спецификатора версии `. Нормализованные номера версий не " +"могут содержать ``-``." + +#: ../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: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 "" +"Утилиты, создающие колеса, должны убедиться, что компоненты имени файла не " +"содержат ``-``, так как в противном случае результирующий файл может быть " +"обработан некорректно." + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" +"Имя архивного файла имеет формат Unicode. Пройдет некоторое время, прежде " +"чем инструменты будут обновлены для поддержки имен файлов, отличных от " +"ASCII, но в данной спецификации они поддерживаются." + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" +"Имена файлов *внутри* архива кодируются как UTF-8. Хотя некоторые " +"распространенные ZIP-клиенты не отображают имена файлов в кодировке UTF-8, " +"эта кодировка поддерживается как спецификацией ZIP, так и ``zipfile`` в " +"Python." + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "Содержимое файлов" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" +"Содержимое файла wheel, где {distribution} заменено на :ref:`нормализованное " +"название ` пакета, например ``beaglevote``, а {version} " +"заменено на его :ref:`нормализованную версию `, например ``1.0.0``, (с символами тире/``-`` замененными на " +"символы подчеркивания/``_`` в обоих полях) состоит из:" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" +"``/``, корень архива, содержит все файлы, которые должны быть установлены в " +"``purelib`` или ``platlib``, как указано в ``WHEEL``. ``purelib`` и " +"``platlib`` обычно являются ``сайт-пакетами``." + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "``{distribution}-{version}.dist-info/`` содержит метаданные." + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" +":file:`{distribution}-{version}.dist-info/licenses/` содержит файлы лицензий." + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" +"``{distribution}-{version}.data/`` содержит один подкаталог для каждого " +"непустого ключа схемы установки, который еще не покрыт, где имя подкаталога " +"является индексом в словаре путей установки (например, ``data``, ``cripts``, " +"``headers``, ``purelib``, ``platlib``)." + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" +"Python-скрипты должны находиться в ``scripts` и начинаться с ``b'#!python``, " +"чтобы во время установки можно было сгенерировать обертку скрипта и " +"переписать ``#!python``. Они могут иметь любое расширение или не иметь " +"его. Каталог ``scripts`` может содержать только обычные файлы." + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" +"``{distribution}-{version}.dist-info/METADATA`` - это метаданные формата " +"Metadata версии 1.1 или выше." + +#: ../source/specifications/binary-distribution-format.rst:199 +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`` - это метаданные о самом архиве " +"в том же базовом формате key: value::" + +#: ../source/specifications/binary-distribution-format.rst:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "``Wheel-Version`` - это номер версии спецификации Wheel." + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" +"``Генератор`` - это имя и, опционально, версия программы, создавшей архив." + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" +"``Root-Is-Purelib`` имеет значение true, если каталог верхнего уровня архива " +"должен быть установлен в purelib; в противном случае корень должен быть " +"установлен в platlib." + +#: ../source/specifications/binary-distribution-format.rst:215 +msgid "" +"``Tag`` is the wheel's expanded compatibility tags; in the example the " +"filename would contain ``py2.py3-none-any``." +msgstr "" +"``Tag`` - это расширенные теги совместимости колеса; в примере имя файла " +"будет содержать ``py2.py3-none-any``." + +#: ../source/specifications/binary-distribution-format.rst:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" +"``Build`` - это номер сборки и опускается, если номер сборки отсутствует." + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" +"Программа установки колеса должна предупреждать, если Wheel-Version больше, " +"чем поддерживаемая ею версия, и должна выходить из строя, если Wheel-Version " +"имеет большую мажорную версию, чем поддерживаемая ею версия." + +#: ../source/specifications/binary-distribution-format.rst:221 +msgid "" +"Wheel, being an installation format that is intended to work across multiple " +"versions of Python, does not generally include .pyc files." +msgstr "" +"Wheel, будучи форматом установки, предназначенным для работы с несколькими " +"версиями Python, обычно не включает файлы .pyc." + +#: ../source/specifications/binary-distribution-format.rst:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "Колесо не содержит setup.py или setup.cfg." + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" +"Эта версия спецификации wheel основана на схемах установки distutils и не " +"определяет, как устанавливать файлы в другие места. Схема предлагает " +"супернабор функций, предоставляемых существующими бинарными форматами " +"wininst и egg." + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "Директория .dist-info" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" +"Каталоги Wheel .dist-info включают в себя как минимум METADATA, WHEEL и " +"RECORD." + +#: ../source/specifications/binary-distribution-format.rst:236 +msgid "" +"METADATA is the package metadata, the same format as PKG-INFO as found at " +"the root of sdists." +msgstr "" +"METADATA - это метаданные пакета, в том же формате, что и PKG-INFO, которые " +"находятся в корне sdists." + +#: ../source/specifications/binary-distribution-format.rst:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "WHEEL - это метаданные колеса, специфичные для сборки пакета." + +#: ../source/specifications/binary-distribution-format.rst:239 +#, fuzzy +#| 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." +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." +msgstr "" +"RECORD - это список (почти) всех файлов в колесе и их защищенных хэшей. В " +"отличие от PEP 376, каждый файл, кроме RECORD, который не может содержать " +"хэш самого себя, должен содержать свой хэш. Алгоритм хэша должен быть " +"sha256 или лучше; в частности, md5 и sha1 не допускаются, так как " +"подписанные файлы колеса полагаются на надежные хэши в RECORD для " +"подтверждения целостности архива." + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "В архив не включены файлы PEP 376 \"INSTALLER\" и \"REQUESTED\"." + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +#, fuzzy +#| 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." +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" +"Во время извлечения программа установки колес сверяет все хэши в RECORD с " +"содержимым файлов. Помимо RECORD и его сигнатур, установка завершится " +"неудачей, если какой-либо файл в архиве не упомянут и не захеширован " +"правильно в RECORD." + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +#, fuzzy +#| msgid "Project name" +msgid "Subdirectory name" +msgstr "Название проекта" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#, fuzzy +#| msgid "``license``" +msgid "``licenses``" +msgstr "``лицензия``" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +#, fuzzy +#| msgid "``license-files``" +msgid "``license_files``" +msgstr "``лицензионные файлы``" + +#: ../source/specifications/binary-distribution-format.rst:266 +#, fuzzy +#| msgid "``LIB``" +msgid "``LICENSES``" +msgstr "``LIB``" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "Каталог :file:`.dist-info/licenses/`" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" +"Если версия метаданных 2.4 или выше и указано одно или несколько полей " +"``License-File``, каталог :file:`.dist-info/` ДОЛЖЕН содержать " +"подкаталог :file:`licenses/`, который ДОЛЖЕН содержать файлы, перечисленные " +"в полях ``License-File`` в файле :file:`METADATA`` по их соответствующим " +"путям относительно каталога :file:`licenses/`." + +#: ../source/specifications/binary-distribution-format.rst:280 +#, fuzzy +#| msgid "The :file:`.dist-info/licenses/` directory" +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "Каталог :file:`.dist-info/licenses/`" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "Директория .data" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" +"Все файлы, которые обычно не устанавливаются внутри пакетов сайта, " +"помещаются в каталог .data, названный так же, как и каталог .dist-info, но с " +"расширением .data/::" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" +"Каталог .data содержит подкаталоги со скриптами, заголовками, документацией " +"и прочим из дистрибутива. Во время установки содержимое этих подкаталогов " +"переносится на путь назначения." + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "ЧаВо" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" +"Wheel определяет каталог .data. Должен ли я поместить туда все свои данные?" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" +"Эта спецификация не имеет своего мнения о том, как вы должны организовывать " +"свой код. Каталог .data - это просто место для любых файлов, которые обычно " +"не устанавливаются в ``сайт-пакеты`` или в PYTHONPATH. Другими словами, вы " +"можете продолжать использовать ``pkgutil.get_data(package, resource)``, даже " +"если *эти* файлы обычно не будут распространяться в директории *wheel'а* " +"``.data``." + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "Как обстоят дела с \"purelib\" и \"platlib\"?" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" +"Wheel сохраняет различие между \"purelib\" и \"platlib\", что важно для " +"некоторых платформ. Например, Fedora устанавливает пакеты чистого Python в '/" +"usr/lib/pythonX.Y/site-packages', а платформозависимые пакеты - в '/usr/" +"lib64/pythonX.Y/site-packages'." + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" +"Колесо с \"Root-Is-Purelib: false\" со всеми своими файлами в ``{name}-" +"{version}.data/purelib`` эквивалентно колесу с \"Root-Is-Purelib: true\" с " +"теми же файлами в корне, и законно иметь файлы как в категории \"purelib\", " +"так и в категории \"platlib\"." + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" +"На практике колесо должно иметь только один из \"purelib\" или \"platlib\" в " +"зависимости от того, является ли оно чистым Python или нет, и эти файлы " +"должны находиться в корне с соответствующей настройкой для \"Root-is-" +"purelib\"." + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "Можно ли импортировать код Python непосредственно из файла wheel?" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" +"Технически, из-за сочетания поддержки установки через простое извлечение и " +"использования формата архива, совместимого с ``zipimport``, подмножество " +"файлов колеса *до* поддерживает размещение непосредственно в ```sys.path``. " +"Однако, хотя такое поведение является естественным следствием дизайна " +"формата, полагаться на него, как правило, не рекомендуется." + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" +"Во-первых, wheel *is* разработан в первую очередь как формат дистрибутива, " +"поэтому пропуск шага установки также означает намеренный отказ от " +"использования функций, предполагающих полную установку (например, " +"возможность использовать стандартные инструменты вроде ``pip`` и " +"``virtualenv`` для захвата и управления зависимостями таким образом, чтобы " +"их можно было правильно отслеживать для целей аудита и обновления " +"безопасности, или полная интеграция со стандартным механизмом сборки для C-" +"расширений путем публикации заголовочных файлов в соответствующем месте)." + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" +"Во-вторых, хотя некоторые программы на Python написаны так, что поддерживают " +"запуск непосредственно из zip-архива, все равно часто код пишется в " +"предположении, что он полностью установлен. Когда это предположение " +"нарушается при попытке запустить программу из zip-архива, сбои часто бывают " +"неясными и трудно диагностируемыми (особенно когда они происходят в " +"библиотеках сторонних разработчиков). Два наиболее распространенных " +"источника проблем с этим - тот факт, что импорт расширений C из zip-архива " +"*не* поддерживается CPython (поскольку это не поддерживается напрямую " +"механизмом динамической загрузки на любой платформе) и что при запуске из " +"zip-архива атрибут ``__file__`` ссылается уже не на обычный путь к файловой " +"системе, а на комбинированный путь, включающий как расположение zip-архива в " +"файловой системе, так и относительный путь к модулю внутри архива. Даже если " +"программа корректно использует абстрактные API ресурсов внутри, " +"взаимодействие с внешними компонентами все равно может потребовать наличия " +"реального файла на диске." + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" +"Как и в случае с метаклассами, monkeypatching и импортерами metapath, если " +"вы еще не уверены, что вам нужно воспользоваться этой возможностью, она вам " +"почти наверняка не понадобится. Если же вы *решили* воспользоваться ею, " +"имейте в виду, что многие проекты потребуют воспроизвести сбой с полностью " +"установленным пакетом, прежде чем принять его за настоящую ошибку." + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "История" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "Февраль 2013 г: Эта спецификация была одобрена через :pep:`427`." + +#: ../source/specifications/binary-distribution-format.rst:383 +msgid "" +"February 2021: The rules on escaping in wheel filenames were revised, to " +"bring them into line with what popular tools actually do." +msgstr "" +"Февраль 2021 года: Правила экранирования в именах файлов wheel были " +"пересмотрены, чтобы привести их в соответствие с тем, что на самом деле " +"делают популярные инструменты." + +#: ../source/specifications/binary-distribution-format.rst:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" +"Декабрь 2024: Уточнено, что папка ``scripts`` должна содержать только " +"обычные файлы (ожидаемое поведение инструментов потребления при встрече с " +"симлинками или подкаталогами в этой папке формально не определено, и поэтому " +"может отличаться для разных инструментов)." + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" +"Декабрь 2024 года: Каталог :file:`.dist-info/licenses/` был указан " +"через :pep:`639`." + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" +"Январь 2025 года: Уточнено, что имя и версия должны быть нормализованы для " +"директорий ``.dist-info`` и ``.data``." + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "Приложение" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "Пример реализации urlsafe-base64-nopad::" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "Пример" + +#: ../source/specifications/build-details/index.rst:35 +#, fuzzy +#| msgid "Changes" +msgid "Changelog" +msgstr "Изменения" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "Спецификация" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +#, fuzzy +#| msgid "JSON Schema" +msgid "Schema" +msgstr "Схема JSON" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Project" +msgid "*object*" +msgstr "Проект" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Semantic versioning" +msgid "Schema version." +msgstr "Семантическая версификация" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "enscons" +msgid "const" +msgstr "enscons" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Examples" +msgid "examples" +msgstr "Примеры" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "python" +msgid "bin/python" +msgstr "python" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "platform tag" +msgid "**platform**" +msgstr "тег платформы" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "platform tag" +msgid "System platform string." +msgstr "тег платформы" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "linux_x86_64" +msgid "linux-x86\\_64" +msgstr "linux_x86_64" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Version" +msgid "**version**" +msgstr "Версия" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Versioning" +msgid "version\\_info" +msgstr "Версионирование" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Release" +msgid "releaselevel" +msgstr "Выпуск" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Mercurial" +msgid "serial" +msgstr "Mercurial" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "**Numbers**" +msgid "*number*" +msgstr "**Числа**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Additional notes" +msgid "additionalProperties" +msgstr "Дополнительные замечания" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Implementation Notes" +msgid "**implementation**" +msgstr "Примечания к реализации" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "python" +msgid "cpython" +msgstr "python" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "abi tag" +msgid "abi" +msgstr "метка abi" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "**Headings**" +msgid "**flags**" +msgstr "**Заголовки**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Versions" +msgid "extensions" +msgstr "Версии" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "python" +msgid "libpython" +msgstr "python" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "``dynamic``" +msgid "dynamic" +msgstr "``динамический``" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Building binary extensions" +msgid "link\\_extensions" +msgstr "Создание бинарных расширений" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "**Numbers**" +msgid "**headers**" +msgstr "**Числа**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Arbitrary equality" +msgid "arbitrary\\_data" +msgstr "Произвольное равенство" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "Спецификации основных метаданных" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" +"Поля, определенные в следующей спецификации, должны считаться " +"действительными, полными и не подлежащими изменению. К обязательным полям " +"относятся:" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "``Имя``" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "Все остальные поля являются необязательными." + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" +"Стандартный формат файлов для метаданных (в том числе в :doc:`wheels ` и :doc:`installed projects `) основан на формате заголовков электронной почты. Однако форматы " +"электронной почты неоднократно пересматривались, и какой именно почтовый RFC " +"применяется к метаданным упаковки, не уточняется. В отсутствие точного " +"определения практический стандарт устанавливается тем, что может разобрать " +"модуль стандартной библиотеки :mod:`python:email.parser`, используя " +"политику :data:`~.python:email.policy.compat32`." + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" +"При сериализации метаданных в поток байтов (например, для сохранения в файл) " +"строки должны быть сериализованы с использованием кодировки UTF-8." + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" +"Хотя в :pep:`566` определен способ преобразования метаданных в JSON-" +"совместимый словарь, он пока не используется в качестве стандартного формата " +"обмена. Необходимость работы инструментов с многолетними существующими " +"пакетами затрудняет переход на новый формат." + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" +"*Интерпретация старых метаданных:* В :pep:`566` спецификация формата поля " +"спецификатора версии была смягчена, чтобы принять синтаксис, используемый " +"популярными издательскими инструментами (а именно, убрать требование, что " +"спецификаторы версии должны быть окружены круглыми скобками). Потребители " +"метаданных могут захотеть использовать более мягкие правила форматирования " +"даже для файлов метаданных, которые номинально меньше версии 2.1." + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "Metadata-Version" + +#: ../source/specifications/core-metadata.rst:52 +#, fuzzy +#| msgid "" +#| "Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +#| "\"2.1\", \"2.2\", \"2.3\", and \"2.4\"." +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" +"Версия формата файла; допустимые значения: «1.0», «1.1», «1.2», «2.1», " +"«2.2», «2.3» и «2.4»." + +#: ../source/specifications/core-metadata.rst:55 +#, fuzzy +#| 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)." +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)." +msgstr "" +"Автоматизированные инструменты, потребляющие метаданные, ДОЛЖНЫ " +"предупреждать, если ``metadata_version`` больше, чем самая высокая " +"поддерживаемая ими версия, и ДОЛЖНЫ отказать, если ``metadata_version`` " +"имеет большую основную версию, чем самая высокая поддерживаемая ими версия " +"(как описано в :ref:`Спецификация спецификатора версии `, основная версия - это значение перед первой точкой)." + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" +"Для более широкой совместимости инструменты сборки MAY выбирают для создания " +"метаданных дистрибутива самую низкую версию метаданных, которая включает все " +"необходимые поля." + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "Пример::" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "Имя" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "Добавлены ограничения на формат из :ref:`формат имени <имя-формат>`." + +#: ../source/specifications/core-metadata.rst:80 +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 "" +"Имя дистрибутива. Поле имени является основным идентификатором дистрибутива. " +"Оно должно соответствовать спецификации :ref:`формата имени `." + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" +"Для сравнения имена должны быть :ref:`нормализованы <имя-нормализация>` " +"перед сравнением." + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "Версия" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" +"Строка, содержащая номер версии дистрибутива. Это поле должно быть в " +"формате, указанном в :ref:`Спецификация спецификатора версии `." + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "Динамический (многократное использование)" + +#: ../source/specifications/core-metadata.rst:113 +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:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" +"При нахождении в метаданных исходного дистрибутива действуют следующие " +"правила:" + +#: ../source/specifications/core-metadata.rst:120 +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 "" +"Если поле *не* помечено как ``динамическое'', то значение этого поля в любом " +"колесе, построенном из sdist, ДОЛЖНО совпадать со значением в sdist. Если " +"поле отсутствует в sdist и не помечено как ``динамическое'', то оно НЕ " +"ДОЛЖНО присутствовать в колесе." + +#: ../source/specifications/core-metadata.rst:124 +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 "" +"Если поле помечено как ``динамическое'', оно может содержать любое " +"допустимое значение в колесе, собранном из sdist (в том числе не " +"присутствовать вообще)." + +#: ../source/specifications/core-metadata.rst:127 +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)." + +#: ../source/specifications/core-metadata.rst:131 +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 " +"или в других колесах для проекта." + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "Полные подробности семантики ``Dynamic`` описаны в :pep:`643`." + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "Platform (можно использовать несколько раз)" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" +"Спецификация платформы, описывающая операционную систему, поддерживаемую " +"дистрибутивом, которая не указана в классификаторах Trove \"Операционная " +"система\". См. раздел \"Классификатор\" ниже." + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "Примеры::" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "Supported-Platform (можно использовать несколько раз)" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" +"Бинарные дистрибутивы, содержащие файл PKG-INFO, будут использовать поле " +"Supported-Platform в своих метаданных для указания ОС и CPU, для которых был " +"скомпилирован бинарный дистрибутив. Семантика поля Supported-Platform не " +"определена в данном PEP." + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "Краткое описание" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "Однострочная сводка того, что делает дистрибутив." + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "Это поле может быть указано в теле сообщения." + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" +"Более длинное описание дистрибутива, которое может состоять из нескольких " +"абзацев. Программы, работающие с метаданными, не должны устанавливать " +"максимальный размер этого поля, однако людям не стоит включать в описание " +"инструкцию по эксплуатации." + +#: ../source/specifications/core-metadata.rst:217 +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/core-metadata.rst:223 +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]_." +msgstr "" +"Для поддержки пустых строк и строк с отступами в соответствии с форматом RFC " +"822 любой символ CRLF должен быть дополнен 7 пробелами, за которыми следует " +"символ pipe (\"|\"). В результате поле Description кодируется в свернутое " +"поле, которое может быть интерпретировано синтаксическим анализатором RFC822 " +"[2]_." + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" +"Эта кодировка подразумевает, что все случаи, когда за CRLF следуют 7 " +"пробелов и символ pipe, должны быть заменены одним CRLF, когда поле " +"разворачивается с помощью устройства чтения RFC822." + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" +"В качестве альтернативы описание дистрибутива может быть представлено в теле " +"сообщения (т. е. после полностью пустой строки, следующей за заголовками, " +"без отступов или другого специального форматирования)." + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "Description-Content-Type" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" +"Строка, указывающая синтаксис разметки (если таковая имеется), используемый " +"в описании дистрибутива, чтобы инструменты могли грамотно отобразить " +"описание." + +#: ../source/specifications/core-metadata.rst:260 +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) `_, а также мог преобразовывать reST в HTML. Однако " +"часто авторы дистрибутивов пишут описание в формате `Markdown `_ (:rfc:`7763`), так как многие сайты " +"хостинга кода выдают Markdown README, и авторы могут использовать этот файл " +"для описания. PyPI не распознавал этот формат и поэтому не мог корректно " +"отобразить описание. Это привело к тому, что многие пакеты на PyPI имели " +"плохо отрисованные описания, когда Markdown оставался простым текстом или, " +"что еще хуже, пытался быть отрисованным как reST. Это поле позволяет автору " +"дистрибутива указать формат описания, открывая возможность для PyPI и других " +"инструментов отображать Markdown и другие форматы." + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" +"Формат этого поля такой же, как у заголовка ``Content-Type`` в HTTP (т.е.: " +"`RFC 1341 `_). " +"Вкратце это означает, что оно имеет часть ``тип/подтип``, а затем может " +"иметь несколько параметров:" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "Формат::" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "Часть ``тип/подтип`` имеет только несколько допустимых значений:" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "``text/plain``" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "``text/x-rst``" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "``text/markdown``" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" +"Параметр ``charset'' может использоваться для указания кодировки описания. " +"Единственным допустимым значением является ``UTF-8``. Если значение опущено, " +"то предполагается, что оно равно ``UTF-8``." + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" +"Другие параметры могут быть специфичны для выбранного подтипа. Например, для " +"подтипа ``markdown`` есть необязательный параметр ``variant``, который " +"позволяет указать используемый вариант Markdown (по умолчанию ``GFM``, если " +"не указан). В настоящее время распознаются два варианта:" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "``GFM`` для :rfc:``GitHub-flavored Markdown <7764#section-3.2>`" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "``CommonMark`` для :rfc:``CommonMark <7764#section-3.5>`" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" +"Если ``Description-Content-Type`` не указан, то приложения должны попытаться " +"отобразить его как ``text/x-rst; charset=UTF-8`` и вернуться к ``text/" +"plain``, если он не является корректным rst." + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" +"Если ``Description-Content-Type`` является нераспознанным значением, то " +"предполагаемый тип содержимого - ``text/plain`` (хотя PyPI, вероятно, " +"отклонит все, что имеет нераспознанное значение)." + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" +"Если ``Description-Content-Type`` имеет значение ``text/markdown``, а " +"``вариант`` не указан или имеет нераспознанное значение, то предполагаемым " +"``вариантом`` будет ``GFM``." + +#: ../source/specifications/core-metadata.rst:329 +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/core-metadata.rst:338 +msgid "Keywords" +msgstr "Ключевые слова" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" +"Список дополнительных ключевых слов, разделенных запятыми, которые будут " +"использоваться для облегчения поиска дистрибутива в большом каталоге." + +#: ../source/specifications/core-metadata.rst:351 +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/core-metadata.rst:360 +msgid "Author" +msgstr "Автор" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" +"Строка, содержащая, как минимум, имя автора; может быть указана " +"дополнительная контактная информация." + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "Author-email" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" +"Строка, содержащая адрес электронной почты автора. Может содержать имя и " +"адрес электронной почты в законных формах для заголовка RFC-822 ``From:``." + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" +"Согласно RFC-822, это поле может содержать несколько адресов электронной " +"почты, разделенных запятыми::" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "Сопровождающий" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" +"Строка, содержащая, как минимум, имя сопровождающего; может быть " +"предоставлена дополнительная контактная информация." + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" +"Обратите внимание, что это поле предназначено для использования, когда " +"проект поддерживается кем-то, кроме оригинального автора: его следует " +"опустить, если оно идентично ``Author``." + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "Maintainer-email" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" +"Строка, содержащая адрес электронной почты сопровождающего. Может содержать " +"имя и адрес электронной почты в законных формах для заголовка RFC-822 " +"``From:``." + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" +"Обратите внимание, что это поле предназначено для использования, когда " +"проект поддерживается кем-то, кроме оригинального автора: оно должно быть " +"опущено, если оно идентично ``Author-email``." + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "Лицензия" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "в пользу ``лицензии-выражения``." + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" +"Начиная с версии Metadata 2.4, ``License`` и ``License-Expression`` являются " +"взаимоисключающими. Если указаны оба значения, инструменты, анализирующие " +"метаданные, будут игнорировать ``Лицензию``, а PyPI будет отклонять " +"загрузки. Смотрите `PEP 639 `__." + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" +"Текст, указывающий на лицензию, распространяемую на дистрибутив, если " +"лицензия не является выбором из классификаторов \"License\" Trove. " +"См. :ref:``Классификатор`` ` ниже. Это поле также может " +"использоваться для указания конкретной версии лицензии, названной через поле " +"``Классификатор'', или для указания разновидности или исключения из такой " +"лицензии." + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "License-Expression" + +#: ../source/specifications/core-metadata.rst:482 +#, fuzzy +#| msgid "" +#| "Text string that is a valid SPDX license expression as defined " +#| "in :pep:`639`. Tools SHOULD validate and perform case normalization of " +#| "the expression." +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" +"Текстовая строка, которая является действительным выражением лицензии SPDX, " +"как определено в :pep:`639`. Инструменты ДОЛЖНЫ проверять и выполнять " +"нормализацию регистра выражения." + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "Лицензия-файл (многократное использование)" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" +"Каждая запись представляет собой строковое представление пути к файлу, " +"связанному с лицензией. Путь находится в дереве исходных текстов проекта, " +"относительно корневого каталога проекта. Подробности см. в :pep:`639`." + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "Classifier (можно использовать несколько раз)" + +#: ../source/specifications/core-metadata.rst:532 +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`, а Python Package " +"Index публикует динамический список `определенных в данный момент " +"классификаторов` `__." + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" +"Использование классификаторов ``License ::`` устарело начиная с версии " +"Metadata 2.4, вместо них используйте ``License-Expression``. См. `PEP 639 " +"`_." + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "За этим полем может следовать маркер окружения после точки с запятой." + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "Requires-Dist (можно использовать несколько раз)" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" +"Спецификация формата полей была смягчена, чтобы принять синтаксис, " +"используемый популярными издательскими инструментами." + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" +"Каждая запись содержит строку с названием другого проекта distutils, " +"необходимого для данного дистрибутива." + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "Формат строки требований содержит от одной до четырех частей:" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" +"Название проекта в том же формате, что и поле ``Имя:``. Единственная " +"обязательная часть." + +#: ../source/specifications/core-metadata.rst:567 +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/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" +"Спецификатор версии. Инструменты, разбирающие формат, должны принимать " +"необязательные круглые скобки вокруг него, но инструменты, генерирующие его, " +"не должны использовать круглые скобки." + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" +"Маркер окружения после точки с запятой. Это означает, что требование " +"необходимо только в указанных условиях." + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "Подробную информацию о допустимом формате см. в :pep:`508`." + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" +"Имена проектов должны соответствовать именам, найденным в `Python Package " +"Index`_." + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" +"Спецификаторы версий должны следовать правилам, описанным в :doc:`version-" +"specifiers`." + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "Requires-Python" + +#: ../source/specifications/core-metadata.rst:600 +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:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "Значение должно быть в формате, указанном в :doc:`version-specifiers`." + +#: ../source/specifications/core-metadata.rst:606 +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/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "За этим полем не может следовать маркер окружения." + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "Requires-External (можно использовать несколько раз)" + +#: ../source/specifications/core-metadata.rst:623 +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/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" +"Формат строки требований - это имя внешней зависимости, за которым в круглых " +"скобках по желанию следует объявление версии." + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" +"Поскольку они ссылаются на релизы программного обеспечения, отличного от " +"Python, номера версий в этом поле **не обязаны соответствовать формату, " +"указанному в :ref:`Спецификация спецификатора версии `: " +"они должны соответствовать схеме версий, используемой внешней зависимостью." + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" +"Обратите внимание, что нет никаких особых правил относительно используемых " +"строк." + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "Project-URL (можно использовать несколько раз)" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" +"Строка, содержащая просматриваемый URL-адрес проекта и его метку, " +"разделенные запятой." + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" +"Этикетка представляет собой свободный текст, ограниченный 32 символами." + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" +"Начиная с :pep:`753`, потребители метаданных проекта (такие как Python " +"Package Index) могут использовать стандартный процесс нормализации для " +"обнаружения «известных» меток, которые затем могут быть представлены в " +"особом виде при выводе на экран. См. :ref:`well-known-project-urls`." + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "Provides-Extra (можно использовать несколько раз)" + +#: ../source/specifications/core-metadata.rst:677 +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/core-metadata.rst:682 +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/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" +"Указанное имя можно использовать, чтобы сделать зависимость зависимой от " +"того, была ли запрошена необязательная функция." + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +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/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" +"Разрешается указывать ``Provides-Extra:`` без ссылки на него в каком-либо " +"``Requires-Dist:``." + +#: ../source/specifications/core-metadata.rst:715 +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/core-metadata.rst:720 +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." +msgstr "" +"При чтении данных для старых версий метаданных инструменты ДОЛЖНЫ " +"предупреждать, что значения для этого поля будут недопустимы в новых версиях " +"метаданных. Если значение будет недействительным в соответствии с правилами " +"для ``Имя:`` в любой основной версии метаданных, пользователь ДОЛЖЕН быть " +"предупрежден, а значение проигнорировано, чтобы избежать двусмысленности. " +"Инструментальные средства МОГУТ выдавать ошибку при чтении недопустимого " +"имени для старых версий метаданных." + +#: ../source/specifications/core-metadata.rst:730 +#, fuzzy +#| msgid "Supported-Platform (multiple use)" +msgid "Import-Name (multiple use)" +msgstr "Supported-Platform (можно использовать несколько раз)" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +#, fuzzy +#| msgid "Supported-Platform (multiple use)" +msgid "Import-Namespace (multiple use)" +msgstr "Supported-Platform (можно использовать несколько раз)" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "Редко используемые поля" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" +"Поля в этом разделе в настоящее время используются редко, поскольку их " +"дизайн был вдохновлен аналогичными механизмами в системах управления " +"пакетами Linux, и совершенно не ясно, как инструменты должны " +"интерпретировать их в контексте открытого индексного сервера, такого как " +"`PyPI `__." + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" +"В результате популярные инструменты установки полностью игнорируют их, что, " +"в свою очередь, не стимулирует издателей пакетов устанавливать их должным " +"образом. Тем не менее, они сохранены в спецификации метаданных, поскольку " +"все еще потенциально полезны в информационных целях, а также могут быть " +"использованы по своему первоначальному назначению в сочетании с курируемым " +"репозиторием пакетов." + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "Provides-Dist (можно использовать несколько раз)" + +#: ../source/specifications/core-metadata.rst:847 +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, который " +"содержится в этом дистрибутиве. Это поле *должно* включать проект, " +"указанный в поле ``Имя``, за которым следует версия : Имя (Версия)." + +#: ../source/specifications/core-metadata.rst:852 +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/core-metadata.rst:859 +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." +msgstr "" +"Дистрибутив может также предоставлять \"виртуальное\" имя проекта, которое " +"не соответствует ни одному отдельно распространяемому проекту: такое имя " +"может использоваться для обозначения абстрактной возможности, которая может " +"быть предоставлена одним из нескольких проектов. Например, несколько " +"проектов могут поставлять привязки к РСУБД для использования данной ORM: " +"каждый проект может объявить, что он предоставляет ``ORM-bindings'', " +"позволяя другим проектам зависеть только от наличия хотя бы одной из этих " +"привязок." + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" +"Может быть указано объявление версии, которое должно соответствовать " +"правилам, описанным в :doc:`version-specifiers`. Номер версии дистрибутива " +"будет подразумеваться, если он не указан." + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "Obsoletes-Dist (можно использовать несколько раз)" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" +"Каждая запись содержит строку, описывающую дистрибутив проекта distutils, " +"который этот дистрибутив делает устаревшим, что означает, что эти два " +"проекта не должны быть установлены одновременно." + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" +"Декларации версий могут быть предоставлены. Номера версий должны быть в " +"формате, указанном в :doc:`version-specifiers`." + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" +"Чаще всего это поле используется в случае изменения названия проекта, " +"например, когда Gorgon 2.3 переходит в Torqued Python 1.0. При установке " +"Torqued Python дистрибутив Gorgon должен быть удален." + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "Утраченные поля" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" +"Устаревших полей следует избегать, но они являются действительными полями " +"метаданных. Они могут быть удалены в будущих версиях основного стандарта " +"метаданных (в этом случае они будут действительны только в файлах, в которых " +"указана версия метаданных, предшествующая удалению). Инструменты ДОЛЖНЫ " +"предупреждать пользователей об использовании устаревших полей." + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "Home-page" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" +"Согласно :pep:`753`, вместо этого используйте :ref:`core-metadata-project-" +"url`." + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "Строка, содержащая URL-адрес главной страницы дистрибутива." + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "Download-URL" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" +"Строка, содержащая URL, с которого можно загрузить данную версию " +"дистрибутива. (Это означает, что URL не может быть чем-то вроде «``.../" +"BeagleVote-latest.tgz``», а вместо этого должен быть «``.../" +"BeagleVote-0.45.tgz``».)" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "Требуется" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "в пользу ``Requires-Dist``" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" +"Каждая запись содержит строку, описывающую другой модуль или пакет, " +"необходимый для данного пакета." + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" +"Формат строки требований идентичен формату имени модуля или пакета, " +"используемого с помощью оператора ``импорта``, за которым в круглых скобках " +"по желанию следует объявление версии." + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" +"Объявление версии представляет собой ряд условных операторов и номеров " +"версий, разделенных запятыми. Условные операторы должны быть одним из \"<\", " +"\">\"', \"<=\", \">=\", \"==\" и \"!=\". Номера версий должны иметь формат, " +"принятый классом ``distutils.version.StrictVersion``: два или три числовых " +"компонента, разделенных точками, с необязательным тегом \"pre-release\" на " +"конце, состоящим из буквы 'a' или 'b', за которой следует число. Примеры " +"номеров версий: \"1.0\", \"2.3a2\", \"1.3.99\"," + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" +"Можно указать любое количество условных операторов, например, строка " +"\">1.0, !=1.3.4, <2.0\" является законным объявлением версии." + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" +"Возможными строками требований являются все следующие: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." + +#: ../source/specifications/core-metadata.rst:980 +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/core-metadata.rst:993 +msgid "Provides" +msgstr "Предоставляет" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "в пользу ``Provides-Dist``" + +#: ../source/specifications/core-metadata.rst:999 +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/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "Обзоры" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "в пользу ``Obsoletes-Dist``" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" +"Каждая запись содержит строку, описывающую пакет или модуль, который этот " +"пакет делает устаревшим, что означает, что эти два пакета не должны быть " +"установлены одновременно. Могут быть предоставлены объявления версий." + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" +"Чаще всего это поле используется в случае изменения названия пакета, " +"например, Gorgon 2.3 переходит в Torqued Python 1.0. При установке Torqued " +"Python пакет Gorgon должен быть удален." + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "Март 2001: Core metadata 1.0 был одобрен через :pep:`241`." + +#: ../source/specifications/core-metadata.rst:1039 +#, fuzzy +#| msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`:" +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "Апрель 2003 года: Core metadata 1.1 был одобрен через :pep:`314`:" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "Февраль 2010 г: Core metadata 1.2 был одобрен через :pep:`345`." + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "Февраль 2018 г: Core metadata 2.1 был одобрен через :pep:`566`." + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "Добавлены ``Description-Content-Type`` и ``Provides-Extra``." + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "Добавлен метод canonical для преобразования метаданных в JSON." + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "Ограничение грамматики поля ``Имя``." + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "Октябрь 2020 года: Core metadata 2.2 был одобрен через :pep:`643`." + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "Добавлено поле ``Динамика``." + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "Март 2022: Core metadata 2.3 был одобрен через :pep:`685`." + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "Ограниченные дополнительные имена, подлежащие нормализации." + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "Август 2024 года: Core metadata 2.4 был одобрен через :pep:`639`." + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "Добавлено поле ``Лицензия-выражение``." + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "Добавлено поле ``Лицензионный файл``." + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +#, fuzzy +#| msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "Октябрь 2020 года: Core metadata 2.2 был одобрен через :pep:`643`." + +#: ../source/specifications/core-metadata.rst:1068 +#, fuzzy +#| msgid "Added the ``Dynamic`` field." +msgid "Added the ``Import-Name`` field." +msgstr "Добавлено поле ``Динамика``." + +#: ../source/specifications/core-metadata.rst:1069 +#, fuzzy +#| msgid "Added the ``Dynamic`` field." +msgid "Added the ``Import-Namespace`` field." +msgstr "Добавлено поле ``Динамика``." + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "Разметка reStructuredText: https://docutils.sourceforge.io/" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "Длинные поля заголовка RFC 822: :rfc:`822#section-3.1.1`" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "Группы зависимости" + +#: ../source/specifications/dependency-groups.rst:7 +#, fuzzy +#| msgid "" +#| "This specification defines Dependency Groups, a mechanism for storing " +#| "package requirements in ``pyproject.toml`` files such that they are not " +#| "included in project metadata when it is built." +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" +"Эта спецификация определяет Dependency Groups, механизм для хранения " +"требований к пакетам в файлах ``pyproject.toml`` таким образом, чтобы они не " +"включались в метаданные проекта при его сборке." + +#: ../source/specifications/dependency-groups.rst:11 +#, fuzzy +#| msgid "" +#| "Dependency Groups are suitable for internal development use-cases like " +#| "linting and testing, as well as for projects which are not built for " +#| "distribution, like collections of related scripts." +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" +"Группы зависимостей подходят для использования во внутренней разработке, " +"например, для линтинга и тестирования, а также для проектов, которые не " +"предназначены для распространения, например, для коллекций связанных " +"скриптов." + +#: ../source/specifications/dependency-groups.rst:15 +#, fuzzy +#| msgid "" +#| "Fundamentally, Dependency Groups should be thought of as being a " +#| "standardized subset of the capabilities of ``requirements.txt`` files " +#| "(which are ``pip``-specific)." +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" +"По сути, группы зависимостей следует рассматривать как стандартизированное " +"подмножество возможностей файлов ``requirements.txt`` (которые являются " +"специфическими для ``pip``)." + +#: ../source/specifications/dependency-groups.rst:25 +#, fuzzy +#| msgid "This is a simple table which shows a ``test`` group::" +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "Это простая таблица, которая показывает группу ``тест``::" + +#: ../source/specifications/dependency-groups.rst:31 +#, fuzzy +#| msgid "and a similar table which defines ``test`` and ``coverage`` groups::" +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "и аналогичная таблица, определяющая группы ``тестов`` и ``покрытий``::" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "Таблица ``[dependency-groups]``" + +#: ../source/specifications/dependency-groups.rst:41 +#, fuzzy +#| msgid "" +#| "Dependency Groups are defined as a table in ``pyproject.toml`` named " +#| "``dependency-groups``. The ``dependency-groups`` table contains an " +#| "arbitrary number of user-defined keys, each of which has, as its value, a " +#| "list of requirements." +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" +"Группы зависимостей определяются в виде таблицы в файле ``pyproject.toml`` с " +"именем ``dependency-groups``. Таблица ``dependency-groups`` содержит " +"произвольное количество определяемых пользователем ключей, каждый из которых " +"имеет в качестве значения список требований." + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" +"Ключи ``[dependency-groups]``, иногда также называемые «именами групп», " +"должны быть :ref:`valid non-normalized names `. Инструменты, " +"работающие с группами зависимостей, ДОЛЖНЫ :ref:`normalize ` эти имена перед сравнением." + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" +"Инструменты ДОЛЖНЫ предпочитать представлять пользователям оригинальное, " +"ненормализованное имя, а если после нормализации обнаруживаются дубликаты " +"имен, инструменты ДОЛЖНЫ выдавать ошибку." + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" +"Списки требований, значения в ``[dependency-groups]``, могут содержать " +"строки, таблицы (``dict`` в Python) или смесь строк и таблиц. Строки должны " +"быть валидными :ref:`dependency specifiers `, а " +"таблицы должны быть валидными Dependency Group Includes." + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "Группа зависимости Включает" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" +"Группа зависимостей Include включает другую группу зависимостей в текущую " +"группу." + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" +"Включенная группа - это таблица с одним ключом, ``«include-group»``, " +"значением которого является строка, имя другой группы зависимостей." + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" +"Включения определяются как точно эквивалентные содержимому именованной " +"группы зависимостей, вставленные в текущую группу в месте расположения " +"включения. Например, если ``foo = [«a», «b»]`` - это одна группа, а ``bar = " +"[«c», {include-group = «foo»}, «d»]`` - другая, то ``bar`` должен " +"оцениваться как ``[«c», «a», „b“, «d»]`` при раскрытии Dependency Group " +"Includes." + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" +"Включения групп зависимостей могут указывать один и тот же пакет несколько " +"раз. Инструменты НЕ ДОЛЖНЫ дедуплицировать или иным образом изменять " +"содержимое списка, созданного включением. Например, в следующей таблице:" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" +"Разрешенное значение ``all`` ДОЛЖНО быть ``[«foo», „foo“, «foo>1.0», " +"«foo<1.0»]``. Инструменты должны работать с таким списком точно так же, как " +"и в любом другом случае, когда их просят обработать одно и то же требование " +"несколько раз с разными ограничениями на версию." + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" +"Dependency Group Includes может включать группы, содержащие Dependency Group " +"Includes, в этом случае эти включения также должны быть расширены. " +"Dependency Group Includes НЕ ДОЛЖНЫ включать циклы, и инструменты ДОЛЖНЫ " +"сообщать об ошибке, если они обнаруживают цикл." + +#: ../source/specifications/dependency-groups.rst:102 +msgid "Package Building" +msgstr "Создание пакета" + +#: ../source/specifications/dependency-groups.rst:104 +#, fuzzy +#| msgid "" +#| "Build backends MUST NOT include Dependency Group data in built " +#| "distributions as package metadata. This means that sdist ``PKG-INFO`` and " +#| "wheel ``METADATA`` files should not include referenceable fields " +#| "containing Dependency Groups." +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" +"Бэкенды сборки НЕ ДОЛЖНЫ включать данные о группах зависимостей в собранные " +"дистрибутивы в качестве метаданных пакета. Это означает, что файлы sdist " +"``PKG-INFO`` и wheel ``METADATA`` не должны содержать ссылаемые поля, " +"содержащие Dependency Groups." + +#: ../source/specifications/dependency-groups.rst:108 +#, fuzzy +#| msgid "" +#| "It is, however, valid to use Dependency Groups in the evaluation of " +#| "dynamic metadata, and ``pyproject.toml`` files included in sdists will " +#| "still contain ``[dependency-groups]``. However, the table's contents are " +#| "not part of a built package's interfaces." +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" +"Однако использование групп зависимостей при оценке динамических метаданных " +"допустимо, и файлы ``pyproject.toml``, включенные в sdists, по-прежнему " +"будут содержать ``[dependency-groups]``. Однако содержимое таблицы не " +"является частью интерфейсов собранного пакета." + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "Установка групп зависимостей и дополнительных функций" + +#: ../source/specifications/dependency-groups.rst:116 +#, fuzzy +#| msgid "" +#| "There is no syntax or specification-defined interface for installing or " +#| "referring to Dependency Groups. Tools are expected to provide dedicated " +#| "interfaces for this purpose." +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" +"Не существует синтаксиса или определенного спецификацией интерфейса для " +"установки или обращения к группам зависимостей. Ожидается, что инструменты " +"будут предоставлять специальные интерфейсы для этой цели." + +#: ../source/specifications/dependency-groups.rst:120 +#, fuzzy +#| msgid "" +#| "Tools MAY choose to provide the same or similar interfaces for " +#| "interacting with Dependency Groups as they do for managing extras. Tools " +#| "authors are advised that the specification does not forbid having an " +#| "extra whose name matches a Dependency Group. Separately, users are " +#| "advised to avoid creating Dependency Groups whose names match extras, and " +#| "tools MAY treat such matching as an error." +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" +"Инструменты МОГУТ предоставлять те же или подобные интерфейсы для " +"взаимодействия с группами зависимостей, что и для управления дополнениями. " +"Авторам инструментов рекомендуется обратить внимание на то, что спецификация " +"не запрещает иметь экстра, имя которого совпадает с группой зависимостей. " +"Отдельно пользователям рекомендуется избегать создания групп зависимостей, " +"имена которых совпадают с именами дополнений, а инструменты МОГУТ " +"рассматривать такое совпадение как ошибку." + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "Проверка и совместимость" + +#: ../source/specifications/dependency-groups.rst:130 +#, fuzzy +#| msgid "" +#| "Tools supporting Dependency Groups may want to validate data before using " +#| "it. When implementing such validation, authors should be aware of the " +#| "possibility of future extensions to the specification, so that they do " +#| "not unnecessarily emit errors or warnings." +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" +"Инструменты, поддерживающие группы зависимостей, могут захотеть проверять " +"данные перед их использованием. При реализации такой проверки авторы должны " +"учитывать возможность будущих расширений спецификации, чтобы не выдавать " +"ненужных ошибок или предупреждений." + +#: ../source/specifications/dependency-groups.rst:135 +#, fuzzy +#| msgid "" +#| "Tools SHOULD error when evaluating or processing unrecognized data in " +#| "Dependency Groups." +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" +"Инструменты ДОЛЖНЫ ошибаться при оценке или обработке нераспознанных данных " +"в группах зависимостей." + +#: ../source/specifications/dependency-groups.rst:138 +#, fuzzy +#| msgid "" +#| "Tools SHOULD NOT eagerly validate the contents of *all* Dependency Groups " +#| "unless they have a need to do so." +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" +"Инструментальные средства НЕ ДОЛЖНЫ с нетерпением проверять содержимое " +"*всех* групп зависимостей, если у них нет необходимости в этом." + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" +"Это означает, что при наличии следующих данных большинство инструментов " +"должны разрешить использование группы ``foo`` и ошибаться только в случае " +"использования группы ``bar``:" + +#: ../source/specifications/dependency-groups.rst:152 +#, fuzzy +#| msgid "" +#| "There are several known cases of tools which have good cause to be " +#| "stricter. Linters and validators are an example, as their purpose is to " +#| "validate the contents of all Dependency Groups." +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" +"Известно несколько случаев, когда инструменты имеют все основания быть более " +"строгими. Примером могут служить линеры и валидаторы, поскольку их задача - " +"проверять содержимое всех групп зависимостей." + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +msgid "Reference Implementation" +msgstr "Справочное осуществление" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" +"Следующая реализация справочника выводит содержимое группы зависимостей в " +"stdout с разграничением по новой строке. Таким образом, на выходе получаются " +"корректные данные ``requirements.txt``." + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "Октябрь 2024 года: Эта спецификация была одобрена через :pep:`735`." + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "Спецификаторы зависимостей" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" +"Этот документ описывает формат спецификаторов зависимостей, изначально " +"указанный в :pep:`508`." + +#: ../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/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" +"Определенный язык - это компактный формат, основанный на строках, который " +"уже широко используется в файлах требований pip, хотя мы не указываем " +"обработку опций командной строки, которую допускают эти файлы. Есть одна " +"оговорка - форма URL-ссылки, указанная в :ref:`Спецификация спецификатора " +"версий `, на самом деле не реализована в pip, но мы " +"используем этот формат, а не текущий родной формат pip." + +#: ../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 "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" +"Спецификация зависимостей всегда указывает имя дистрибутива. Она может " +"включать дополнения, которые расширяют зависимости именованного дистрибутива " +"для включения дополнительных возможностей. Установленная версия может " +"контролироваться с помощью ограничений версии или указания URL-адреса " +"конкретного артефакта для установки. Наконец, зависимость может быть " +"обусловлена с помощью маркеров окружения." + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "Грамматика" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" +"Сначала мы кратко рассмотрим грамматику, а затем углубимся в семантику " +"каждого раздела." + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" +"Спецификация дистрибутива записывается в виде ASCII-текста. Мы используем " +"грамматику parsley [#parsley]_, чтобы обеспечить точную грамматику. " +"Предполагается, что спецификация будет встроена в более крупную систему, " +"которая предлагает такие возможности, как комментарии, поддержка нескольких " +"строк через продолжения или другие подобные возможности." + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" +"Полная грамматика, включая аннотации для построения полезного дерева " +"разбора, приведена в конце этого документа." + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" +"Версии могут быть указаны в соответствии с правилами спецификации " +"спецификатора версий `. (Примечание: URI определены " +"в :rfc:`std-66 <3986>`)::" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" +"Маркеры среды позволяют сделать так, чтобы спецификация действовала только в " +"некоторых средах::" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" +"Дополнительные компоненты дистрибутива могут быть указаны с помощью поля " +"extras::" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" +"Неразрывные пробельные символы в большинстве случаев являются " +"необязательными и не имеют смыслового значения. Единственным исключением " +"является определение конца требования URL." + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "Имена" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" +"Имена дистрибутивов Python в настоящее время определены в :pep:`345`. Имена " +"выступают в качестве основного идентификатора дистрибутивов. Они " +"присутствуют во всех спецификациях зависимостей, и их достаточно, чтобы быть " +"самостоятельной спецификацией. Однако PyPI накладывает строгие ограничения " +"на имена - они должны соответствовать регистронезависимому регексу, иначе " +"они не будут приняты. Соответственно, в этом документе мы ограничиваем " +"допустимые значения для идентификаторов этим regex. Полное переопределение " +"имени может произойти в будущем PEP для метаданных. Регекс (выполняется с " +"re.IGNORECASE) выглядит так::" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "Дополнительно" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" +"Экстра - это необязательная часть дистрибутива. Дистрибутивы могут указывать " +"столько дополнений, сколько захотят, и каждое дополнение приводит к " +"объявлению дополнительных зависимостей дистрибутива, **когда** дополнение " +"используется в спецификации зависимостей. Например::" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" +"Дополнения объединяют зависимости, которые они определяют, с зависимостями " +"дистрибутива, к которому они присоединены. Приведенный выше пример приведет " +"к установке requests, собственных зависимостей запросов, а также любых " +"зависимостей, перечисленных в дополнении запросы \"безопасности\"." + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" +"Если перечислено несколько дополнений, все зависимости объединяются вместе." + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "Версии" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" +"Более подробно о номерах версий и их сравнении см. в :ref:`Спецификация " +"спецификаторов версий `. Спецификаторы версий " +"ограничивают версии дистрибутива, которые могут быть использованы. Они " +"применяются только к дистрибутивам, которые ищутся по имени, а не по URL. " +"Сравнение версий также используется в функции маркеров. Необязательные " +"скобки вокруг версии присутствуют для совместимости с :pep:`345`, но не " +"должны генерироваться, а только приниматься." + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "Маркеры окружающей среды" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" +"Маркеры окружения позволяют спецификации зависимости предоставить правило, " +"описывающее, когда зависимость должна быть использована. Например, " +"рассмотрим пакет, которому нужен argparse. В Python 2.7 argparse " +"присутствует всегда. В более старых версиях Python он должен быть установлен " +"как зависимость. Это можно выразить так::" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" +"Маркерное выражение оценивается либо в True, либо в False. Если оно имеет " +"значение False, спецификация зависимости должна быть проигнорирована." + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" +"Язык маркеров вдохновлен самим Python и выбран за возможность безопасной " +"оценки без запуска произвольного кода, который может стать уязвимостью " +"безопасности. Впервые маркеры были стандартизированы в :pep:`345`. В этом " +"документе исправлены некоторые проблемы, которые были замечены в " +"конструкции, описанной в :pep:`426`." + +#: ../source/specifications/dependency-specifiers.rst:199 +#, fuzzy +#| msgid "" +#| "Comparisons in marker expressions are typed by the comparison operator. " +#| "The operators that are not in perform the same " +#| "as they do for strings in Python. The operators use the " +#| "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::" +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" +"Сравнения в маркерных выражениях типизируются оператором сравнения. " +"Операторы , не входящие в , работают так же, как и " +"для строк в Python. Операторы используют правила сравнения " +"версий из спецификации спецификаторов версий `, когда " +"они определены (то есть когда обе стороны имеют корректный спецификатор " +"версии). Если поведение этой спецификации не определено, а оператор " +"существует в Python, то оператор возвращается к поведению Python. В " +"противном случае должна быть выдана ошибка. Например, следующие действия " +"приведут к ошибкам::" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" +"Пользовательские константы всегда кодируются как строки с кавычками ````` " +"или `````````. Обратите внимание, что экранирование обратной косой черты не " +"определено, но существующие реализации поддерживают его. Они не включены в " +"эту спецификацию, потому что добавляют сложности, и в настоящее время в них " +"нет видимой необходимости. Точно так же мы не определяем поддержку символов, " +"отличных от ASCII: все переменные времени выполнения, на которые мы " +"ссылаемся, должны быть только ASCII." + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" +"Переменные в грамматике маркеров, такие как \"os_name\", разрешаются в " +"значения, которые ищутся во времени выполнения Python. За исключением " +"\"extra\", все значения определены во всех современных версиях Python - если " +"значение не определено, это ошибка в реализации маркеров." + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" +"Неизвестные переменные должны вызывать ошибку, а не приводить к сравнению, " +"которое оценивается как True или False." + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" +"Переменные, значение которых не может быть вычислено в данной реализации " +"Python, должны оцениваться как ``0`` для версий, и как пустая строка для " +"всех остальных переменных." + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" +"Переменная \"extra\" - особенная. Она используется колесами для сигнализации " +"о том, какие спецификации применяются к данной extra в файле ``METADATA`` " +"колеса, но поскольку файл ``METADATA`` основан на черновой " +"версии :pep:`426``, текущей спецификации для этого не существует. Независимо " +"от этого, вне контекста, где происходит такая специальная обработка, " +"переменная \"extra\" должна приводить к ошибке, как и все остальные " +"неизвестные переменные." + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "Маркер" + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "Эквивалент Python" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "Образцовые значения" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "``ос_название``" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr ":py: данные:`ос. название`" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "``posix``, ``java``" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "``системная платформа``" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr ":py: данные:`sys. платформа`" + +#: ../source/specifications/dependency-specifiers.rst:258 +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/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "``платформа_машины``" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr ":py:func:`платформа.машина()`" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "``x86_64``" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "``платформа_python_имплементация``" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr ":py:func:`платформа.python_имплементация()`" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "``CPython``, ``Jython``" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "``платформа_выпуска``" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr ":py:func:`платформа. релиз()`" + +#: ../source/specifications/dependency-specifiers.rst:271 +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/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "``платформа_системы``" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr ":py:func:`платформа.система()`" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "``Linux``, ``Windows``, ``Java``" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "``платформа_версия``" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr ":py:func:`платформа.версия()`" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "``python_версия``" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "``'.'.join(platform.python_version_tuple()[:2])``" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +#, fuzzy +#| msgid "Version specifiers" +msgid ":ref:`Version `" +msgstr "Спецификаторы версии" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "``3.4``, ``2.7``" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "``python_полная_версия``" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr ":py:func:`платформа. python_версия()`" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "``3.4.0``, ``3.5.0b1``" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "``имя_реализации``" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr ":py: данные:`sys.имплементация. название `" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "``cpython``" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "``Версия_реализации``" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "смотрите определение ниже" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "``экстра``" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" +"Ошибка, за исключением случаев, когда она определена контекстом, " +"интерпретирующим спецификацию." + +#: ../source/specifications/dependency-specifiers.rst:302 +#, fuzzy +#| msgid "``pyproject.toml``" +msgid "``toml``" +msgstr "``pyproject.toml``" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +#, fuzzy +#| msgid "``extra``" +msgid "``extras``" +msgstr "``экстра``" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +#, fuzzy +#| msgid "``dependencies``" +msgid "``dependency_groups``" +msgstr "``зависимости``" + +#: ../source/specifications/dependency-specifiers.rst:312 +#, fuzzy +#| msgid "``test``" +msgid "``{\"test\"}``" +msgstr "``тест``" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" +"Маркерная переменная ``имплементация_версия`` получена из :py: " +"данные:`sys.имплементация.версия `:" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" +"Этот раздел маркеров окружения, первоначально определенный через :pep:`508`, " +"заменяет раздел маркеров окружения в :pep:`345`." + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "Полная грамматика" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "Полная грамматика петрушки::" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "Тестовая программа - если грамматика находится в строке ``grammar``:" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "Ноябрь 2015 г: Эта спецификация была одобрена через :pep:`508`." + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" +"Июль 2019: Определение ``python_version`` было ``изменено `` с ``platform.python_version()[:3]`` на " +"``'.'.join(platform.python_version_tuple()[:2])``, чтобы учесть " +"потенциальные будущие версии Python с двузначными мажорными и минорными " +"версиями (например, 3.10). [#future_versions]_" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" +"Июнь 2024 года: Определение ``версии_малого`` было изменено, чтобы разрешить " +"запятые в конце, что соответствует поведению реализации Python, которая " +"используется с конца 2022 года." + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" +"pip, рекомендуемая программа установки пакетов Python (http://" +"pip.readthedocs.org/en/stable/)" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "Библиотека PEG Петрушка. (https://pypi.python.org/pypi/parsley/)" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" +"В будущих версиях Python могут возникнуть проблемы с определением маркерной " +"переменной среды ``python_version`` (https://github.com/python/peps/issues/" +"560)" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "Запись прямого URL-адреса происхождения установленных дистрибутивов" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" +"Этот документ определяет файл :file:`direct_url.json` в директории ``*.dist-" +"info`` установленного дистрибутива для записи прямого URL Origin " +"дистрибутива. Общая структура и использование директорий ``*.dist-info`` " +"описаны в :ref:`recording-installed-packages``." + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" +"Файл :file:`direct_url.json` ДОЛЖЕН создаваться в каталоге :file:`*.dist-" +"info` установщиками при установке дистрибутива из требования, указывающего " +"прямую URL-ссылку (включая VCS URL)." + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" +"Этот файл НЕ ДОЛЖЕН создаваться при установке дистрибутива из требований " +"другого типа (т.е. имя плюс спецификатор версии)." + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" +"Этот JSON-файл ДОЛЖЕН быть кодировкой UTF-8, :rfc:`8259` совместимой с " +"сериализацией :doc:`direct-url-data-structure`." + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" +"Если запрашиваемый URL имеет схему file:// и указывает на локальный каталог, " +"который содержит VCS checkout, программы установки НЕ ДОЛЖНЫ пытаться " +"вывести какую-либо VCS информацию и, следовательно, НЕ ДОЛЖНЫ выводить какую-" +"либо связанную с VCS информацию (например, ``vcs_info``) " +"в :file:`direct_url.json``." + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" +"Как правило, программы установки должны по возможности сохранять информацию, " +"которая была предоставлена в запрошенном URL при " +"генерации :file:`direct_url.json`. Например, переменные окружения " +"user:password должны быть сохранены, а ``запрашиваемая_ревизия`` должна как " +"можно точнее отражать ревизию, указанную в запрошенном URL. Однако эта " +"информация может быть *обогащена* более точными данными, такими как " +"``commit_id``." + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "Примеры команд pip и их влияние на direct_url.json" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "Команды, генерирующие файл ``direct_url.json``:" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (в этом случае ``url`` будет локальным " +"каталогом, в который был клонирован git-репозиторий, а ``dir_info`` будет " +"присутствовать с ``\"editable\": true`` и не будет установлено ``vcs_info``)" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "Команды, которые *не* генерируют ``direct_url.json``" + +#: ../source/specifications/direct-url.rst:62 +#, fuzzy +msgid "``pip install app``" +msgstr "Используйте ``pip`` для установки Pipenv:" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "Март 2020 года: Эта спецификация была одобрена через :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 "" +"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 "" +"Этот документ определяет JSON-сериализуемую абстрактную структуру данных, " +"которая может представлять URL-адреса проектов python и артефактов " +"распространения, таких как деревья исходных текстов VCS, локальные деревья " +"исходных текстов, дистрибутивы исходных текстов и колеса." + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" +"На момент написания статьи формально не определено, как объединить части " +"этой структуры данных в единый URL, который можно передавать инструментам. " +"Общим представлением является формат URL pip (`VCS Support `_), другие примеры приведены в : ссылка:`Спецификация " +"спецификатора версии <версия-спецификаторы>`." + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" +"Структура данных прямого URL ДОЛЖНА представлять собой словарь, " +"сериализуемый в JSON в соответствии с :rfc:`8259`." + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +msgstr "" +"Он ДОЛЖЕН содержать как минимум два поля. Первое - ``url``, с типом " +"``string``. Его содержимое должно быть правильным URL в соответствии со " +"стандартом URL `_." + +#: ../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`` является архивом исходного кода или колесом), " +"или ``dir_info`` (если ``url`` является локальным каталогом). Эти " +"информационные поля имеют в качестве значения (возможно, пустой) подсловарь, " +"возможные ключи которого определены ниже." + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "Соображения безопасности" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" +"При сохранении ``url`` должен быть очищен от любой конфиденциальной " +"информации об аутентификации в целях безопасности." + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" +"Однако секция user:password в URL МОЖЕТ состоять из переменных окружения, " +"соответствующих следующему регулярному выражению:" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" +"Кроме того, секция user:password в URL может быть известной строкой, не " +"связанной с безопасностью. Типичным примером является ``git`` в случае " +"такого URL, как ``ssh://git@gitlab.com/user/repo``." + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "VCS URLs" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" +"Когда ``url`` ссылается на VCS-репозиторий, ключ ``vcs_info`` ДОЛЖЕН " +"присутствовать в виде словаря со следующими ключами:" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" +"Ключ ``vcs`` (тип ``string``) ДОЛЖЕН присутствовать, содержащий имя VCS " +"(т.е. одно из ``git``, ``hg``, ``bzr``, ``svn``). Другие VCS ДОЛЖНЫ быть " +"зарегистрированы путем написания PEP для изменения этой спецификации. " +"Значение ``url`` ДОЛЖНО быть совместимым с соответствующей VCS, чтобы " +"установщик мог передать его без преобразования команде проверки/загрузки VCS." + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This field MUST match the revision requested by the user and MUST NOT exist " +"when the user did not select a specific revision." +msgstr "" +"Ключ ``запрошенная_ревизия`` (тип ``строка``) МОЖЕТ присутствовать, называя " +"ветку/тег/реф/коммит/ревизию/etc (в формате, совместимом с VCS). Это поле " +"ДОЛЖНО соответствовать ревизии, запрошенной пользователем, и НЕ ДОЛЖНО " +"существовать, если пользователь не выбрал конкретную ревизию." + +#: ../source/specifications/direct-url-data-structure.rst:70 +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-hash, то такой commit-hash ДОЛЖЕН " +"использоваться в качестве ``commit_id``, чтобы ссылаться на неизменяемую " +"версию исходного кода." + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "Архивные URL" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" +"Когда ``url`` ссылается на исходный архив или колесо, ключ ``archive_info`` " +"ДОЛЖЕН присутствовать в виде словаря со следующими ключами:" + +#: ../source/specifications/direct-url-data-structure.rst:85 +msgid "" +"A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a " +"hex encoded digest of the file." +msgstr "" +"Ключ ``hashes`` ДОЛЖЕН присутствовать в виде словаря, сопоставляющего имя " +"хэша с шестнадцатеричным дайджестом файла." + +#: ../source/specifications/direct-url-data-structure.rst:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "Эти имена хэшей ДОЛЖНЫ быть всегда приведены к нижнему регистру." + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" +"В качестве ключа для словаря хэшей можно использовать любой алгоритм, " +"доступный через :py:mod:`hashlib` (в частности, те, которые можно передать " +"в :py:func:`hashlib.new()` и которые не требуют дополнительных параметров). " +"По крайней мере, один безопасный алгоритм из :py:data:`hashlib. " +"алгоритмы_гарантированы` ДОЛЖЕН быть всегда включен. На момент написания " +"статьи рекомендуется ``sha256`." + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" +"Устаревший ключ ``hash`` (тип ``string``) МОЖЕТ присутствовать в целях " +"обратной совместимости, со значением ``=``." + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" +"Производители структуры данных ДОЛЖНЫ выдавать ключ ``hashes`` независимо от " +"того, один или несколько хэшей доступны. Производители ДОЛЖНЫ продолжать " +"выдавать ключ ``hash`` в тех контекстах, где они делали это раньше, чтобы " +"сохранить обратную совместимость для существующих клиентов." + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" +"Если присутствуют ключи ``hash`` и ``hashes``, хэш, представленный в ключе " +"``hash``, ДОЛЖЕН присутствовать и в словаре ``hashes``, поэтому пользователи " +"могут рассматривать ключ ``hashes``, только если он присутствует, и " +"возвращаться к ``hash`` в противном случае." + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "Локальные каталоги" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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/direct-url-data-structure.rst:119 +msgid "" +"``editable`` (type: ``boolean``): ``true`` if the distribution was/is to be " +"installed in editable mode, ``false`` otherwise. If absent, default to " +"``false``." +msgstr "" +"``editable`` (тип: ``boolean``): ``true``, если дистрибутив был/будет " +"установлен в редактируемом режиме, ``false`` в противном случае. Если " +"отсутствует, то по умолчанию ``false``." + +#: ../source/specifications/direct-url-data-structure.rst:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" +"Когда ``url`` ссылается на локальный каталог, он ДОЛЖЕН иметь схему ``file`` " +"и соответствовать :rfc:`8089`. В частности, компонент пути должен быть " +"абсолютным. Символьные ссылки ДОЛЖНЫ сохраняться при преобразовании " +"относительных путей в абсолютные." + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "Проекты в подкаталогах" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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 "" +"Поле верхнего уровня ``поддиректория`` МОЖЕТ содержать путь к каталогу, " +"относительно корня VCS-репозитория, исходного архива или локального " +"каталога, чтобы указать, где находится ``pyproject.toml`` или ``setup.py``." + +#: ../source/specifications/direct-url-data-structure.rst:139 +msgid "Registered VCS" +msgstr "Зарегистрированный VCS" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" +"В этом разделе перечислены зарегистрированные VCS; расширенная, специфичная " +"для VCS информация о том, как использовать поля ``vcs``, " +"``requested_revision`` и другие поля ``vcs_info``; и в некоторых случаях " +"дополнительные специфичные для VCS поля. Инструменты МОГУТ поддерживать " +"другие VCS, хотя РЕКОМЕНДУЕТСЯ регистрировать их путем написания PEP для " +"изменения этой спецификации. Поле ``vcs`` ДОЛЖНО представлять собой имя " +"команды (в нижнем регистре). Дополнительные поля, необходимые для поддержки " +"такой VCS, ДОЛЖНЫ иметь префикс с именем команды VCS." + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "Git" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "Домашняя страница" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "https://git-scm.com/" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "команда vcs" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "git" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "поле ``vcs``" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "поле ``запрошенный_пересмотр``" + +#: ../source/specifications/direct-url-data-structure.rst:163 +msgid "" +"A tag name, branch name, Git ref, commit hash, shortened commit hash, or " +"other commit-ish." +msgstr "" +"Имя тега, имя ветки, Git ref, хэш коммита, сокращённый хэш коммита или " +"другое имя коммита." + +#: ../source/specifications/direct-url-data-structure.rst:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "поле ``commit_id``" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "Хэш фиксации (40 шестнадцатеричных символов sha1)." + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" +"Инструменты могут использовать команды ``git show-ref`` и ``git symbolic-" +"ref``, чтобы определить, соответствует ли ``запрашиваемая_ревизия`` Git-" +"рефлекту. В свою очередь, ссылка, начинающаяся с ``refs/tags/``, " +"соответствует тегу, а ссылка, начинающаяся с ``refs/remotes/origin/`` после " +"клонирования, соответствует ветке." + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "Mercurial" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "https://www.mercurial-scm.org/" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "hg" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" +"Имя тега, имя ветки, идентификатор набора изменений, сокращенный " +"идентификатор набора изменений." + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "Идентификатор набора изменений (40 шестнадцатеричных символов)." + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "Bazaar" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "https://www.breezy-vcs.org/" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "bzr" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "Имя тега, имя ветки, идентификатор ревизии." + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "Идентификатор ревизии." + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "svn" + +#: ../source/specifications/direct-url-data-structure.rst:226 +msgid "" +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." +msgstr "" +"``requested_revision`` должен быть совместим с опцией ``vn checkout`` ``--" +"revision``. В Subversion ветка или тег являются частью ``url``." + +#: ../source/specifications/direct-url-data-structure.rst:230 +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/direct-url-data-structure.rst:235 +msgid "JSON Schema" +msgstr "Схема JSON" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" +"Следующая JSON-схема может быть использована для проверки содержимого файла " +"``direct_url.json``:" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "Архив источников:" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "URL-адрес Git с тегом и хэшем фиксации:" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "Локальный справочник:" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "Локальная директория в режиме редактирования:" + +#: ../source/specifications/direct-url-data-structure.rst:294 +msgid "" +"March 2020: This specification was approved through :pep:`610`, defining the " +"``direct_url.json`` metadata file." +msgstr "" +"Март 2020 года: Эта спецификация была одобрена через :pep:`610`, определяя " +"файл метаданных ``direct_url.json``." + +#: ../source/specifications/direct-url-data-structure.rst:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" +"Январь 2023 года: Добавлен ключ ``archive_info.hashes`` (``discussion " +"`_)." + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "Спецификация точек входа" + +#: ../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/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/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/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. метаданные`. Теперь он определен как " +"спецификация совместимости PyPA, чтобы позволить инструментам сборки, " +"отличным от ``setuptools``, публиковать совместимые " +"с :py:mod:`importlib.метаданные` метаданные точки входа, а библиотекам " +"времени выполнения, отличным от :py:mod:`importlib. метаданные``, переносимо " +"читать опубликованные метаданные точки входа (потенциально с различными " +"стратегиями кэширования и разрешения конфликтов)." + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "Модель данных" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "Концептуально точка входа определяется тремя необходимыми свойствами:" + +#: ../source/specifications/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 "" +"Группа **группа**, к которой принадлежит точка входа, указывает, какого рода " +"объект она предоставляет. Например, группа ``console_scripts`` предназначена " +"для точек входа, ссылающихся на функции, которые могут быть использованы в " +"качестве команды, а ``pygments.styles`` - это группа для классов, " +"определяющих стили pygments. Потребитель обычно определяет ожидаемый " +"интерфейс. Чтобы избежать столкновений, потребители, определяющие новую " +"группу, должны использовать имена, начинающиеся с имени PyPI, принадлежащего " +"проекту-потребителю, за которым следует ``.``. Имена групп должны " +"представлять собой одну или несколько групп букв, цифр и символов " +"подчеркивания, разделенных точками (regex ``^\\w+(\\.\\w+)*$``)." + +#: ../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** идентифицирует эту точку входа в своей группе. Точное значение " +"этого параметра зависит от пользователя. Для консольных скриптов имя точки " +"входа - это команда, которая будет использована для ее запуска. В пределах " +"дистрибутива имена точек входа должны быть уникальными. Если разные " +"дистрибутивы предоставляют одно и то же имя, потребитель решает, как " +"справиться с такими конфликтами. Имя может содержать любые символы, кроме " +"``=``, но оно не может начинаться или заканчиваться любым символом пробела, " +"а также начинаться с ``[``. Для новых точек входа рекомендуется использовать " +"только буквы, цифры, символы подчеркивания, точки и тире (regex ``[\\w.-]" +"+``)." + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" +"Ссылка **объект** указывает на объект Python. Она имеет вид " +"``importable.module`` или ``importable.module:object.attr``. Каждая из " +"частей, разделенных точками и двоеточием, является допустимым " +"идентификатором Python. Он предназначен для поиска следующим образом::" + +#: ../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/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** - это набор строк, " +"определяющих необязательные возможности дистрибутива, предоставляющего точку " +"входа. Если они указаны, то точка входа требует зависимостей от этих " +"\"дополнений\". См. поле метаданных :ref:`metadata_provides_extra`." + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" +"Использовать extras в качестве точки входа больше не рекомендуется. " +"Потребители должны поддерживать их разбор из существующих дистрибутивов, но " +"затем могут их игнорировать. Новые инструменты публикации не должны " +"поддерживать указание дополнений. Функциональность работы с дополнениями " +"была привязана к модели setuptools по управлению \"яичными\" пакетами, но " +"новые инструменты, такие как pip и virtualenv, используют другую модель." + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "Формат файла" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" +"Точки входа определяются в файле :file:`entry_points.txt` в " +"каталоге :file:`*.dist-info` дистрибутива. Это каталог, описанный " +"в :ref:`recording-installed-packages` для установленных дистрибутивов, и " +"в :ref:`binary-distribution-format` для колес. В файле используется " +"кодировка UTF-8." + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" +"Содержимое файла имеет формат INI, читаемый модулем " +"Python :mod:`configparser`. Однако по умолчанию configparser рассматривает " +"имена как нечувствительные к регистру, в то время как имена точек входа " +"чувствительны к регистру. Конфигурационный парсер с учетом регистра может " +"быть сделан следующим образом::" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" +"В файле точек входа всегда должно использоваться ``=`` для разделения имен и " +"значений (в то время как configparser также позволяет использовать ``:``)." + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" +"Секции конфигурационного файла представляют собой группы точек входа, имена " +"- это имена, а значения кодируют как ссылку на объект, так и необязательные " +"дополнения. Если используются дополнительные параметры, они представляют " +"собой список, разделенный запятыми, заключенный в квадратные скобки." + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" +"Внутри значения читатели должны принимать и игнорировать пробелы (включая " +"несколько последовательных пробелов) до или после двоеточия, между ссылкой " +"на объект и левой квадратной скобкой, между дополнительными именами и " +"разграничивающими их квадратными скобками и двоеточиями, а также после " +"правой квадратной скобки. Синтаксис для extras формально указан в :pep:`508` " +"(как ``extras``), а ограничения на значения указаны в :pep:`685`. Для " +"инструментов, записывающих файл, рекомендуется вставлять пробел только между " +"ссылкой на объект и левой квадратной скобкой." + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "Используйте для скриптов" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" +"Две группы точек входа имеют особое значение при упаковке: " +"``console_scripts`` и ``gui_scripts``. В обеих группах имя точки входа " +"должно быть пригодно для использования в качестве команды в системной " +"оболочке после установки пакета. Ссылка на объект указывает на функцию, " +"которая будет вызвана без аргументов при выполнении этой команды. Функция " +"может возвращать целое число, которое будет использоваться в качестве кода " +"завершения процесса, а возврат ``None`` эквивалентен возврату ``0``." + +#: ../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 "" +"Например, точка входа ``mycmd = mymod:main`` создаст команду ``mycmd``, " +"запускающую скрипт следующего вида::" + +#: ../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 "" +"Разница между ``консольные скрипты`` и ``gui_скрипты`` влияет только на " +"системы Windows. ``консольные_скрипты`` обернуты в консольный исполняемый " +"файл, поэтому они подключаются к консоли и могут использовать :py: " +"данные:`sys.stdin`, :py: данные:`sys.stdout` и :py: данные:`sys.stderr` для " +"ввода и вывода. ``gui_скрипты`` оборачиваются в исполняемый файл GUI, " +"поэтому их можно запускать без консоли, но они не могут использовать " +"стандартные потоки, если код приложения не перенаправит их. На других " +"платформах такого различия нет." + +#: ../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`` в каталог scripts схемы установки. Они не отвечают за " +"размещение этого каталога в переменной окружения ``PATH'', которая " +"определяет, где находятся инструменты командной строки." + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" +"Поскольку файлы создаются на основе имен, а некоторые файловые системы не " +"чувствительны к регистру, пакеты должны избегать использования имен в этих " +"группах, отличающихся только регистром. Поведение инструментов установки, " +"когда имена отличаются только регистром, не определено." + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" +"Октябрь 2017 г: Эта спецификация была написана для формализации существующей " +"функции точек входа в setuptools (discussion_)." + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "Внешне управляемые среды" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" +"В то время как некоторые установки 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." +msgstr "" +"Попытка использовать обычные средства упаковки Python для работы с такими " +"средами может в лучшем случае привести к путанице, а в худшем - к поломке " +"всей базовой операционной системы. Документация и руководства по " +"совместимости помогают решить такие проблемы." + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" +"Эта спецификация определяет файл-маркер ``EXTERNALLY-MANAGED``, который " +"позволяет установке Python указать таким специфичным для Python " +"инструментам, как ``pip``, что они не устанавливают и не удаляют пакеты в " +"среду установки интерпретатора по умолчанию, а вместо этого должны направить " +"конечного пользователя на использование :ref:`virtual-environments`." + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" +"Он также стандартизирует интерпретацию схем ``sysconfig``, чтобы, если " +"менеджер пакетов, специфичный для Python, собирается установить пакет в " +"контексте всего интерпретатора, он мог сделать это таким образом, чтобы " +"избежать конфликта с внешним менеджером пакетов и снизить риск поломки " +"программ, поставляемых внешним менеджером пакетов." + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "Терминология" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" +"Некоторые термины, используемые в данной спецификации, имеют несколько " +"значений в контекстах, которые она охватывает. Для ясности в данной " +"спецификации следующие термины используются особым образом:" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "distro" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" +"Сокращение от \"дистрибутив\", собрание различных программ, в идеале " +"предназначенных для совместной работы, включая (в контексте, относящемся к " +"данному документу) сам интерпретатор Python, программы, написанные на " +"Python, и программы, написанные на других языках. Именно в этом смысле " +"используются такие фразы, как \"Дистрибутив Linux\" или \"Дистрибутив " +"программного обеспечения Berkeley.\"" + +#: ../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. Он также может быть оверлейным дистрибутивом, " +"который устанавливается поверх существующей ОС, например Homebrew или " +"MacPorts." + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" +"В этом документе используется краткий термин \"дистрибутив\", потому что " +"термин \"дистрибутив\" имеет другое значение в контексте упаковки Python: " +"исходный или бинарный дистрибутив отдельной части программного обеспечения " +"языка Python, то есть в смысле ``setuptools.dist.Distribution`` или " +"\"sdist\". Чтобы избежать путаницы, в этом документе вообще не используется " +"обычный термин \"дистрибутив\". В смысле упаковки Python в нем используется " +"полная фраза \"дистрибутив\" или просто \"пакет\" (см. ниже)." + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" +"Поставщик дистрибутива - команда или компания, которая собирает и публикует " +"программное обеспечение и вносит в него необходимые изменения, - является " +"его **дистрибьютором**." + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "пакет" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" +"Единица программного обеспечения, которая может быть установлена и " +"использована в Python. То есть, это относится к тому, что специфические для " +"Python средства упаковки обычно называют :term:`distribution package` или " +"просто \"дистрибутив\"; разговорное сокращение \"пакет\" используется в " +"смысле индекса пакетов Python." + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" +"В этом документе слово \"пакет\" не используется в смысле импортируемого " +"имени, содержащего модули Python, хотя во многих случаях дистрибутив состоит " +"из одного импортируемого пакета с тем же именем." + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" +"В этом документе обычно не используется термин \"пакет\" для обозначения " +"единиц установки менеджером пакетов дистрибутива (таких как файлы ``.deb`` " +"или ``.rpm``). При необходимости используется формулировка \"пакет " +"дистрибутива\". (Опять же, во многих случаях пакет Python поставляется " +"внутри пакета дистрибутива с именем типа ``python-`` плюс имя пакета Python.)" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "Python-специфический менеджер пакетов" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" +"Инструмент для установки, обновления и/или удаления пакетов Python в " +"соответствии со стандартами упаковки Python. Наиболее популярным менеджером " +"пакетов для Python является pip_; другие примеры включают старую команду " +"`_, а также прямое использование команды ``setup.py``." + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" +"(Обратите внимание, что команда ``easy_install`` была удалена в версии " +"setuptools 52, выпущенной 23 января 2021 года.)" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" +"(Conda_ - это немного особый случай, поскольку команда ``conda`` может " +"устанавливать не только пакеты Python, что делает ее в некотором смысле " +"похожей на менеджер пакетов дистрибутива. Поскольку команда ``conda`` обычно " +"работает только с окружениями, созданными Conda, большинство проблем, " +"описанных в этом документе, не относятся к ``conda``, когда она выступает в " +"роли менеджера пакетов для Python.)" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "менеджер пакетов дистрибутива" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" +"Инструмент для установки, обновления и/или удаления пакетов дистрибутива в " +"установленном экземпляре этого дистрибутива, который способен устанавливать " +"пакеты Python, а также пакеты, не относящиеся к Python, и поэтому обычно " +"имеет свою собственную базу данных установленного программного обеспечения, " +"не связанную с :ref:`базой данных установленных дистрибутивов `. Примерами могут служить ``apt``, ``dpkg``, ``dnf``, " +"``rpm``, ``pacman`` и ``brew``. Основная особенность заключается в том, что " +"если пакет был установлен менеджером пакетов дистрибутива, то его удаление " +"или обновление таким образом, чтобы удовлетворить специфический менеджер " +"пакетов Python, обычно приводит к тому, что менеджер пакетов дистрибутива " +"оказывается в противоречивом состоянии." + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" +"В этом документе также используются такие фразы, как \"внешний менеджер " +"пакетов\" или \"менеджер пакетов системы\" для обозначения менеджера пакетов " +"дистрибутива в определенных контекстах." + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "тень" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" +"Затенение установленного пакета Python заключается в том, чтобы заставить " +"другой пакет быть предпочтительным для импорта без удаления каких-либо " +"файлов из затененного пакета. Для этого требуется несколько записей в " +"``sys.path``: если пакет A 2.0 устанавливает модуль ``a.py`` в одной записи " +"``sys.path``, а пакет A 1.0 устанавливает модуль ``a.py`` в более поздней " +"записи ``sys.path``, то ``import a`` возвращает модуль из первого, и мы " +"говорим, что A 2.0 затеняет A 1.0." + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "Эта спецификация имеет двоякое значение." + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" +"Во-первых, он описывает **способ для дистрибьюторов интерпретатора Python " +"пометить этот интерпретатор как имеющий пакеты, управляемые средствами, " +"внешними по отношению к Python**, так что специфичные для Python инструменты " +"вроде pip не должны изменять установленные пакеты в глобальном ``sys.path` " +"интерпретатора любым способом (добавлять, обновлять/понижать или удалять), " +"если это специально не запрещено. Он также предоставляет дистрибьютору " +"возможность указать, как использовать виртуальное окружение в качестве " +"альтернативы." + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" +"Это механизм выбора: по умолчанию интерпретатор Python, скомпилированный из " +"исходных текстов, не будет помечен таким образом, и поэтому запуск ``pip " +"install`` с самокомпилирующимся интерпретатором или с дистрибутивом, который " +"явно не пометил свой интерпретатор, будет работать так, как он всегда " +"работал." + +#: ../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 "" +"Во-вторых, оно устанавливает правило, что при установке пакетов в глобальный " +"контекст интерпретатора (либо в немаркированный интерпретатор, либо при " +"переопределении маркировки), **специфичные для Python менеджеры пакетов " +"должны изменять или удалять файлы только в тех каталогах схемы sysconfig, в " +"которых они создавали бы файлы**. Это позволяет распространителю " +"интерпретатора Python создать два каталога, один для собственных управляемых " +"пакетов, другой для неуправляемых пакетов, устанавливаемых конечным " +"пользователем, и гарантировать, что установка неуправляемых пакетов не будет " +"удалять (или перезаписывать) файлы, принадлежащие внешнему менеджеру пакетов." + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "Пометка интерпретатора как использующего внешний менеджер пакетов" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" +"Прежде чем программа установки пакетов, специфичная для Python (то есть " +"инструмент, такой как pip, а не внешний инструмент, такой как apt), " +"установит пакет в определенный контекст Python, она должна по умолчанию " +"выполнить следующие проверки:" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" +"Работает ли он вне виртуальной среды? Это можно определить по тому, что " +"``sys.prefix == sys.base_prefix``." + +#: ../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 "" +"Есть ли файл ``EXTERNALLY-MANAGED`` в каталоге, определяемом " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" +"Если оба эти условия верны, программа установки должна выйти с сообщением об " +"ошибке, указывающим на то, что установка пакетов в каталог этого " +"интерпретатора Python вне виртуальной среды запрещена." + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" +"Программа установки должна иметь возможность отменить эти правила, например, " +"флаг командной строки ``--break-system-packages``. Эта опция не должна быть " +"включена по умолчанию и должна нести в себе некоторый подтекст, что ее " +"использование рискованно." + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" +"Файл ``EXTERNALLY-MANAGED`` - это файл метаданных в стиле INI, " +"предназначенный для разбора модулем configparser_ стандартной библиотеки. " +"Если файл может быть разобран модулем " +"``configparser.ConfigParser(interpolation=None)`` с использованием кодировки " +"UTF-8 и содержит секцию ``[externally-managed]``, то программа установки " +"должна искать сообщение об ошибке, указанное в файле, и выводить его как " +"часть своей ошибки. Если первый элемент кортежа, возвращаемого функцией " +"``locale.getlocale(locale.LC_MESSAGES)``, т.е. код языка, не является " +"``None``, то программа должна искать сообщение об ошибке как значение ключа " +"с именем ``Error-``, за которым следует код языка. Если такого ключа не " +"существует, а код языка содержит подчеркивание или дефис, то следует искать " +"ключ с именем ``Error-``, за которым следует часть кода языка перед " +"подчеркиванием или дефисом. Если ни один из них не найден, или если код " +"языка - ``None``, следует искать ключ с простым именем ``Error``." + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" +"Если программа установки не может найти сообщение об ошибке в файле (либо " +"потому, что файл не может быть разобран, либо потому, что не существует " +"подходящего ключа ошибки), то программа установки должна просто использовать " +"собственное предопределенное сообщение об ошибке, которое должно предложить " +"пользователю создать виртуальную среду для установки пакетов." + +#: ../source/specifications/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 an ``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 "" +"Распространители программного обеспечения, у которых есть неспецифичный для " +"Python менеджер пакетов, управляющий библиотеками в ``sys.path` их пакета " +"Python, должны, как правило, поставлять файл ``EXTERNALLY-MANAGED`` в их " +"стандартном каталоге библиотек. Например, Debian может поставлять файл в ``/" +"usr/lib/python3.9/EXTERNALLY-MANAGED``, состоящий из чего-то вроде" + +#: ../source/specifications/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" +"который предоставляет полезную и относящуюся к дистрибутиву информацию " +"пользователю, пытающемуся установить пакет. По желанию в том же файле можно " +"предоставить переводы:" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" +"В некоторых случаях, например, при использовании образов контейнеров с одним " +"приложением, которые не обновляются после создания, дистрибьютор может не " +"поставлять файл ``EXTERNALLY-MANAGED``, чтобы пользователи могли " +"устанавливать все, что им нравится (как и сейчас), без необходимости вручную " +"отменять это правило." + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "Запись только в целевую схему ``sysconfig``" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" +"Обычно программа установки пакетов Python устанавливает их в каталоги по " +"схеме, возвращаемой пакетом стандартной библиотеки ``sysconfig`. Обычно это " +"схема, возвращаемая ``sysconfig.get_default_scheme()``, но в зависимости от " +"конфигурации (например, ``pip install --user``) она может использовать " +"другую схему." + +#: ../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 "" +"Если программа установки выполняет установку в схему ``sysconfig``, эта " +"спецификация заявляет, что программа установки никогда не должна изменять " +"или удалять файлы за пределами этой схемы. Например, если он обновляет " +"пакет, а пакет уже установлен в каталог вне этой схемы (возможно, в каталог " +"из другой схемы), он должен оставить существующие файлы в покое." + +#: ../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/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 "" +"Если программа установки выполняет установку в местоположение вне схемы " +"``sysconfig` (например, ``pip install --target``), то этот подраздел не " +"применяется." + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "Рекомендации по дистрибутивам" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" +"Этот раздел не является нормативным. В нем представлены лучшие практики, " +"которым, по нашему мнению, должны следовать дистрибутивы, если у них нет " +"особых причин для обратного." + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "Пометьте установку как управляемую извне" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" +"Дистры должны создать файл ``EXTERNALLY-MANAGED`` в своем каталоге " +"``stdlib``." + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "Направляйте пользователей в виртуальную среду" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" +"Файл должен содержать полезное и соответствующее дистрибутиву сообщение об " +"ошибке, указывающее как на установку общесистемных пакетов через менеджер " +"пакетов дистрибутива, так и на настройку виртуального окружения. Если ваш " +"дистрибутив часто используется пользователями в состоянии, когда команда " +"``python3`` доступна (и особенно когда доступны ``pip`` или ``get-pip``), но " +"``python3 -m venv`` не работает, в сообщении должно быть четко указано, как " +"заставить ``python3 -m venv`` работать правильно." + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" +"Рассмотрим упаковку pipx_, инструмента для установки приложений на языке " +"Python, и предложение его в качестве ошибки. pipx автоматически создает " +"виртуальную среду только для этого приложения, что гораздо лучше по " +"умолчанию для конечных пользователей, которые хотят установить некоторое " +"программное обеспечение на языке Python (которого нет в дистрибутиве), но " +"сами не являются пользователями Python. Упаковка pipx в дистрибутив " +"позволяет избежать иронии, когда пользователям предлагается ``pip install --" +"user --break-system-packages pipx``, чтобы *избежать* нарушения системных " +"пакетов. Подумайте о том, чтобы пакет / окружение Python для конечных " +"пользователей вашего дистрибутива (например, ``python3`` на Fedora или " +"``python3-full`` на Debian) зависел от pipx." + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "Храните файл маркера в образах контейнеров" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" +"Дистры, выпускающие официальные образы для контейнеров с одним приложением " +"(например, образы контейнеров Docker), должны хранить файл ``EXTERNALLY-" +"MANAGED``, желательно таким образом, чтобы он не исчезал, если пользователь " +"этого образа устанавливает обновления пакетов внутри образа (подумайте о " +"``RUN apt-get dist-upgrade``)." + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "Создайте отдельные каталоги дистрибутива и локального каталога" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" +"Дистры должны поместить два отдельных пути в ``sys.path`` системного " +"интерпретатора, один для пакетов, установленных в дистрибутиве, и один для " +"пакетов, установленных локальным системным администратором, и настроить " +"``sysconfig.get_default_scheme()`` так, чтобы он указывал на последний путь. " +"Это гарантирует, что такие инструменты, как pip, не будут изменять " +"установленные в дистрибутиве пакеты. Путь для локального системного " +"администратора должен находиться перед путем для дистрибутива в " +"``sys.path``, чтобы локальные установки имели предпочтение перед пакетами " +"дистрибутива." + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" +"Например, Fedora и Debian (и их производные) реализуют это разделение, " +"используя ``/usr/local`` для локально установленных пакетов и ``/usr`` для " +"пакетов, установленных в дистрибутиве. Fedora использует ``/usr/local/lib/" +"python3.x/site-packages`` против ``/usr/lib/python3.x/site-packages``. " +"(Debian использует ``/usr/local/lib/python3/dist-packages`` против ``/usr/" +"local/lib/python3/dist-packages``. ``/usr/lib/python3/dist-packages`` как " +"дополнительный уровень отделения от локально скомпилированного " +"интерпретатора Python: если вы собираете и устанавливаете CPython в ``/usr/" +"local/bin``, он будет смотреть на ``/usr/local/lib/python3/site-packages``, " +"а Debian хочет быть уверен, что пакеты, установленные через локально " +"собранный интерпретатор, не появятся в ```sys.path`` для интерпретатора " +"дистрибутива.)" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" +"Обратите внимание, что разделение ``/usr/local`` и ``/usr`` аналогично тому, " +"как переменная окружения ``PATH`` обычно включает ``/usr/local/bin:/usr/" +"bin``, а недистро-программы устанавливаются в ``/usr/local`` по умолчанию. " +"Такое разделение ``рекомендовано Стандартом иерархии файловых систем``." + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" +"Это можно сделать двумя способами. Первый - если вы собираете и упаковываете " +"библиотеки Python напрямую (например, ваши помощники по упаковке " +"распаковывают колесо или вызывают ``setup.py install``), организуйте для " +"этих инструментов использование каталога, который не входит в схему " +"``sysconfig``, но все еще находится в ``sys.path``." + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" +"Другой вариант - организовать изменение схемы ``sysconfig`` по умолчанию при " +"запуске внутри сборки пакета по сравнению с запуском на установленной " +"системе. Крючки настройки ``sysconfig`` из bpo-43976_ должны упростить эту " +"задачу (после принятия и реализации): сделайте так, чтобы ваш инструмент " +"упаковки устанавливал переменную окружения или какую-то другую определяемую " +"конфигурацию, и определите функцию ``get_preferred_schemes``, чтобы она " +"возвращала другую схему при вызове изнутри сборки пакета. Тогда вы сможете " +"использовать ``pip install`` как часть упаковки вашего дистрибутива." + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" +"Мы предлагаем добавить опцию ``--scheme=...`` для указания pip запускаться " +"по определенной схеме. (О том, как pip в настоящее время определяет схемы, " +"см. ниже в разделе ``Примечания к реализации``.) Когда это будет доступно, " +"для локального тестирования и, возможно, для реальной упаковки вы сможете " +"запускать что-то вроде ``pip install --scheme=posix_distro`` для явной " +"установки пакета в расположение вашего дистрибутива (в обход " +"``get_preferred_schemes``). Также, при крайней необходимости, можно " +"использовать ``pip uninstall --scheme=posix_distro``, чтобы с помощью pip " +"удалить пакеты из управляемого системой каталога." + +#: ../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 "" +"Чтобы установить пакеты с помощью pip, вам также потребуется либо подавить " +"файл-маркер ``EXTERNALLY-MANAGED``, чтобы позволить pip запуститься, либо " +"переопределить его в командной строке. Вы можете использовать те же средства " +"для подавления маркерного файла в chroots сборки, что и в образах " +"контейнеров." + +#: ../source/specifications/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" +"Преимущество автоматической настройки (подавление файла-маркера в среде " +"сборки и автоматическое возвращение ``get_preferred_schemes`` схемы вашего " +"дистрибутива) заключается в том, что не украшенная ``pip install`` будет " +"работать внутри сборки пакета, что в целом означает, что немодифицированный " +"сценарий сборки upstream, который случайно вызовет ``pip install``, сделает " +"все правильно. Конечно, вы можете просто убедиться, что ваш процесс упаковки " +"всегда вызывает ``pip install --scheme=posix_distro --break-system-" +"packages``, что тоже будет работать." + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" +"Лучший подход здесь во многом зависит от конвенций и механизмов упаковки в " +"вашем дистрибутиве." + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" +"Аналогично, пути ``sysconfig``, которые не предназначены для импортируемого " +"кода Python - то есть ``include``, ``platinclude``, ``cripts`` и ``data`` - " +"также должны иметь два варианта, один для использования в дистрибутиве, " +"другой для локально установленного программного обеспечения, и дистрибутив " +"должен быть настроен так, чтобы оба были пригодны для использования. " +"Например, типичный FHS-совместимый дистрибутив будет использовать ``/usr/" +"local/include`` для стандартной схемы ``include`` и ``/usr/include`` для " +"упакованных в дистрибутив заголовков и помещать оба в путь поиска " +"компилятора, а также будет использовать ``/usr/local/bin`` для стандартной " +"схемы ``cripts`` и ``/usr/bin`` для упакованных в дистрибутив точек входа и " +"помещать обе в ``$PATH``." + +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" +msgstr "Примечания к реализации" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" +"Этот раздел не является нормативным и содержит примечания, относящиеся как к " +"спецификации, так и к потенциальным реализациям." + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" +"В настоящее время (по состоянию на май 2021 года) pip не предоставляет " +"возможности напрямую выбрать целевую схему ``sysconfig``, но у него есть три " +"способа поиска схем при установке:" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "``pip install``" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" +"Вызывает ``sysconfig.get_default_scheme()``, который обычно (в upstream " +"CPython и большинстве современных дистрибутивов) совпадает с " +"``get_preferred_scheme('prefix')``." + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "``pip install --prefix=/some/path``" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "Вызывает ``sysconfig.get_preferred_scheme('prefix')``." + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "``pip install --user``" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "Вызывает ``sysconfig.get_preferred_scheme('user')``." + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" +"Наконец, ``pip install --target=/some/path`` записывает непосредственно в ``/" +"some/path`` без поиска каких-либо схем." + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" +"В Debian в настоящее время существует `патч, изменяющий место установки по " +"умолчанию в виртуальном окружении`__, используя несколько эвристик (включая " +"проверку переменной окружения ``VIRTUAL_ENV``), в основном для того, чтобы " +"каталог, используемый в виртуальном окружении, оставался ``ite-packages``, а " +"не ``dist-packages``. Это не особенно влияет на данное предложение, " +"поскольку реализация этого патча фактически не изменяет схему ``sysconfig`` " +"по умолчанию, и, в частности, не изменяет результат " +"``sysconfig.get_path(\"stdlib\")``." + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" +"В настоящее время Fedora содержит `патч для изменения места установки по " +"умолчанию, если не запущен внутри rpmbuild`__, который используется для " +"реализации подхода с двумя системными каталогами. Концептуально это тот же " +"крючок, что и в bpo-43976_, только реализованный в виде исправления кода к " +"``distutils``, а не в виде изменения схемы ``sysconfig``." + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" +"Реализация ``is_virtual_environment`` выше, а также логика загрузки файла " +"``EXTERNALLY-MANAGED`` и поиска сообщения об ошибке из него, могут быть " +"добавлены в стандартную библиотеку (``sys`` и ``sysconfig``, " +"соответственно), чтобы централизовать их реализацию, но пока в этом нет " +"необходимости." + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "Авторские права" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" +"Этот документ размещен в общественном достоянии или под лицензией CC0-1.0-" +"Universal, в зависимости от того, что является более разрешительным." + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "Июнь 2022: Эта спецификация была одобрена через :pep:`668`." + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +#, fuzzy +#| msgid "This specification was originally defined in :pep:`753`." +msgid "This specification was originally defined in :pep:`592`." +msgstr "Эта спецификация была первоначально определена в :pep:`753`." + +#: ../source/specifications/file-yanking.rst:14 +#, fuzzy +#| msgid "" +#| ":pep:`740` includes changes to the HTML and JSON index APIs. These " +#| "changes are documented in the :ref:`simple-repository-api` " +#| "under :ref:`simple-repository-api-base` and :ref:`json-serialization`." +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" +":pep:`740` включает изменения в HTML и JSON API индексов. Эти изменения " +"документированы в разделах :ref:`Simple-repository-api` под :ref:`Simple-" +"repository-api-base` и :ref:`json-serialization`." + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" +"Ссылки в простом репозитории **МОГУТ** иметь атрибут ``данные-янки'', " +"который может не иметь значения, или иметь произвольную строку в качестве " +"значения. Наличие атрибута ``данные-янки'' **ДОЛЖНО** интерпретироваться как " +"указание на то, что файл, на который указывает данная конкретная ссылка, был " +"\"выдернут\", и не должен выбираться программой установки, за исключением " +"особых случаев." + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" +"Значение атрибута ``данные выдернуты``, если он присутствует, представляет " +"собой произвольную строку, которая отражает причину, по которой файл был " +"выдернут. Инструменты, обрабатывающие простой API репозитория, **МОГУТ** " +"отображать эту строку для конечных пользователей." + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" +"Атрибут yanked не является неизменяемым после установки и может быть отменен " +"в будущем (а после отмены может быть также сброшен). Таким образом, " +"пользователи API **МОГУТ** быть в состоянии справиться с тем, что файл с " +"атрибутом yanked может быть \"отменен\" (и даже снова отменен)." + +#: ../source/specifications/file-yanking.rst:40 +msgid "Installers" +msgstr "Установщики" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" +"Для пользователей желательно, чтобы после удаления файла, когда человек в " +"данный момент пытается напрямую установить удаленный файл, это происходило " +"так, как будто файл был удален. Однако если человек сделал это некоторое " +"время назад, а теперь компьютер просто продолжает механически следовать " +"первоначальному приказу установить удаленный файл, то он ведет себя так, как " +"будто он не был удален." + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" +"Программа установки **ДОЛЖНА** игнорировать выдернутые релизы, если " +"ограничения выбора могут быть удовлетворены с помощью не выдернутой версии, " +"и **МОЖЕТ** отказаться от использования выдернутого релиза, даже если это " +"означает, что запрос вообще не может быть удовлетворен. Реализация " +"**ДОЛЖНА** выбрать политику, которая следует духу вышеуказанного намерения и " +"предотвращает \"новые\" зависимости от выдернутых релизов/файлов." + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" +"Что это значит, решает конкретный инсталлятор, чтобы решить, как лучше всего " +"вписать это в общее использование своего инсталлятора. Однако можно " +"предложить два подхода:" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" +"Выдернутые файлы всегда игнорируются, если только они не являются " +"единственным файлом, соответствующим спецификатору версии, который " +"\"привязывает\" к точной версии с помощью ``==`` (без каких-либо " +"модификаторов, которые делают его диапазоном, таких как ``.*``) или ``===``. " +"В остальном соответствие этому спецификатору версии должно выполняться " +"согласно : ссылка:`спецификации спецификаторов версии <версия-" +"спецификаторы>` для таких вещей, как локальные версии, нулевые подстановки и " +"т.д." + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" +"Выдернутые файлы всегда игнорируются, если только они не являются " +"единственным файлом, который соответствует тому, что указано в файле " +"блокировки (например, ``Pipfile.lock`` или ``poetry.lock``) для установки. В " +"этом случае выдернутый файл **ДОЛЖЕН** не использоваться при создании или " +"обновлении файла блокировки из какого-либо входного файла или команды." + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "Зеркала" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "Как правило, зеркала можно обрабатывать одним из двух способов:" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" +"Они могут полностью исключить их из своего простого API репозитория, " +"предоставляя представление репозитория, в котором отображаются только " +"\"активные\", незаанкетированные файлы." + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" +"Они могут выбрать включение выдернутых файлов и дополнительно отразить " +"атрибут ``данные выдернуты``." + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" +"Зеркала **МОГУТ НЕ** зеркалировать выдернутый файл, не зеркалируя также " +"атрибут ``данные выдернуты`` для него." + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" +"Буквенно-цифровые символы, подчеркивания (``_``), дефисы (``-``) и точки " +"(``.``) ДОЛЖНЫ совпадать дословно." + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" +"Специальные символы глобуса: ``*``, ``?``, ``**`` и диапазоны символов: " +"``[...]``, содержащие только дословные совпадающие символы, ДОЛЖНЫ " +"поддерживаться. Внутри ``[...]`` дефис указывает на диапазон, не зависящий " +"от локали (например, ``a-z``, порядок основан на кодовых точках Unicode). " +"Дефисы в начале или в конце совпадают буквально." + +#: ../source/specifications/glob-patterns.rst:27 +#, fuzzy +#| msgid "Path delimiters must be the forward slash character (``/``)." +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "Разделителями путей должны быть символы прямой косой черты (``/``)." + +#: ../source/specifications/glob-patterns.rst:29 +#, fuzzy +#| msgid "" +#| "Path delimiters MUST be the forward slash character (``/``). Patterns are " +#| "relative to the directory containing :file:`pyproject.toml`, therefore " +#| "the leading slash character MUST NOT be used." +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" +"Разделителями путей ДОЛЖЕН быть символ прямой косой черты (``/``). Образцы " +"являются относительными к директории, содержащей :file:`pyproject.toml`, " +"поэтому символ прямой косой черты НЕ ДОЛЖЕН использоваться." + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "Индикаторы родительского каталога (``..``) НЕ ДОЛЖНЫ использоваться." + +#: ../source/specifications/glob-patterns.rst:36 +#, fuzzy +#| msgid "" +#| "Any characters or character sequences not covered by this specification " +#| "are invalid. Projects MUST NOT use such values. Tools consuming this " +#| "field SHOULD reject invalid values with an error." +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" +"Любые символы или последовательности символов, не предусмотренные данной " +"спецификацией, являются недействительными. Проекты НЕ ДОЛЖНЫ использовать " +"такие значения. Средства, использующие это поле, ДОЛЖНЫ отклонять " +"недопустимые значения с ошибкой." + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" +"Буквальные пути (например, :file:`LICENSE`) являются допустимыми глобусами, " +"что означает, что они также могут быть определены." + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" +"ДОЛЖНО рассматривать каждое значение как шаблон glob, и ДОЛЖНО выдать " +"ошибку, если шаблон содержит неверный синтаксис glob." + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" +"ДОЛЖНА вызывать ошибку, если любой отдельный шаблон, указанный " +"пользователем, не соответствует хотя бы одному файлу." + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +#, fuzzy +#| msgid "Reference Implementation" +msgid "Reference implementation in Python" +msgstr "Справочное осуществление" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "Спецификации PyPA" + +#: ../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 Packaging Authority. Процесс обновления этих " +"стандартов и предложения новых задокументирован на сайте `pypa.io `__." + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "Аттестаты, размещенные в индексе" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "Эта спецификация была первоначально определена в :pep:`740`." + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" +":pep:`740` включает изменения в HTML и JSON API индексов. Эти изменения " +"документированы в разделах :ref:`Simple-repository-api` под :ref:`Simple-" +"repository-api-base` и :ref:`json-serialization`." + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "Загрузка изменений конечной точки" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" +"«Устаревший» API выгрузки не стандартизирован. О том, как загружаются " +"аттестаты, см. документацию по API выгрузки `PyPI `_." + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "Объекты аттестации" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" +"Объект аттестации - это объект JSON с несколькими обязательными ключами; " +"приложения или подписывающие лица могут включать дополнительные ключи при " +"условии, что все явно перечисленные ключи будут предоставлены. Требуемый " +"макет объекта аттестации представлен в виде псевдокода ниже." + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" +"Полная модель данных для каждого объекта в ``transparency_entries`` " +"приведена в :ref:``appendix``. Объекты аттестации **ДОЛЖНЫ** включать одну " +"или несколько записей журнала прозрачности, и **МОГУТ** включать " +"дополнительные ключи для других источников подписанного времени (таких " +"как :rfc:`3161` Time Stamping Authority или `Roughtime `__ сервер)." + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" +"Объекты аттестации имеют версии; данный PEP определяет версию 1. Каждая " +"версия привязана к одному криптографическому набору, чтобы минимизировать " +"ненужную криптографическую маневренность. В версии 1 этот набор выглядит " +"следующим образом:" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" +"Сертификаты указываются как сертификаты X.509 и соответствуют профилю " +"в :rfc:`5280`." + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" +"Алгоритм подписи сообщений - ECDSA, с кривой P-256 для открытых ключей и " +"SHA-256 в качестве функции криптографического дайджеста." + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" +"Будущие PEP могут изменить этот набор (и общую форму объекта аттестации), " +"выбрав новый номер версии." + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "Создание аттестационного листа и подписи" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" +"Заявление об аттестации* - это фактическое утверждение, которое " +"криптографически подписывается внутри объекта аттестации (т.е. " +"``конверт.заявление``)." + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" +"Заявление об аттестации кодируется как объект `v1 in-toto Statement `__, в форме " +"JSON. При сериализации заявление рассматривается как непрозрачный двоичный " +"блок, что позволяет избежать необходимости канонизации." + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" +"Помимо того, что аттестационное заявление является v1 in-toto Statement, оно " +"ограничено следующим образом:" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "In-toto ``субъект`` **ДОЛЖЕН** содержать только один субъект." + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" +"``subject[0].name`` - это имя файла дистрибутива, которое **МОЖЕТ** быть " +"действительным именем файла :ref:`source distribution ` или :ref:`wheel distribution `." + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" +"``subject[0].digest`` **МОЖНО** содержать дайджест SHA-256. Другие дайджесты " +"**МОГУТ** присутствовать. Дайджесты **МОГУТ** быть представлены в виде " +"шестнадцатеричных строк." + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "Поддерживаются следующие значения ``predicateType``:" + +#: ../source/specifications/index-hosted-attestations.rst:130 +#, fuzzy +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" +"`PyPI Публикация аттестации `__: `https://docs.pypi.org/attestations/publish/v1``" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" +"Подпись под этим утверждением построена с использованием протокола подписи " +"DSSE `__, с ``PAYLOAD_TYPE`` из ``application/vnd.in-toto+json`` и " +"``PAYLOAD_BODY`` из JSON-кодированного утверждения выше. Никакой другой " +"``PAYLOAD_TYPE`` не допускается." + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "Объекты, имеющие происхождение" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" +"Индекс будет обслуживать загруженные аттестации вместе с метаданными, " +"которые могут помочь в их проверке, в виде сериализованных объектов JSON." + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" +"Эти объекты *provenance* будут доступны как через Simple Index, так и через " +"JSON-based Simple API, как описано выше, и будут иметь следующий вид:" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "или, как псевдокод:" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" +"``версия`` - ``1``. Как и объекты аттестации, объекты подтверждения имеют " +"версии, и в этом PEP определена только версия ``1``." + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" +"``attestation_bundles`` - это **обязательный** массив JSON, содержащий один " +"или несколько \"пучков\" аттестаций. Каждый пакет соответствует " +"идентификатору подписи (например, идентификатору доверенной публикации) и " +"содержит один или несколько объектов аттестации." + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" +"Как отмечается в модели ``Издатель``, каждый объект " +"``AttestationBundle.publisher`` специфичен для своего Доверенного Издателя, " +"но должен включать в себя как минимум:" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" +"Ключ ``kind``, который **МОЖЕТ** быть строкой JSON, уникально " +"идентифицирующей тип доверенного издателя." + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" +"Ключ ``claims``, который **МОЖЕТ** быть JSON-объектом, содержащим любые " +"контекстно-специфические требования, сохраненные индексом во время " +"аутентификации Trusted Publisher." + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" +"Все остальные ключи в объекте publisher являются специфическими для издателя." + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" +"Каждый массив объектов аттестации является надмножеством массива " +"``аттестаций``, предоставленного загружаемым через поле ``аттестации`` во " +"время загрузки, как описано в :ref:`upload-endpoint` и :ref:`changes-to-" +"provenance-objects`." + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "Изменить объекты подтверждения" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" +"Объекты провенанса *не* неизменяемы и могут изменяться с течением времени. " +"Причины изменения объекта провенанса включают, но не ограничиваются ими:" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" +"Добавление новых аттестаций для уже существующего идентификатора подписи: " +"индекс **МОЖЕТ** разрешить дополнительные аттестации для уже существующих " +"идентификаторов подписи, например, новые версии аттестаций для уже " +"загруженных файлов." + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" +"Добавление новых идентификаторов подписи и связанных с ними аттестаций: " +"индекс **МОЖЕТ** поддерживать аттестации из источников, отличных от " +"загрузчика файла, таких как сторонние аудиторы или сам индекс. Эти " +"аттестации могут выполняться асинхронно, требуя от индекса вставлять их в " +"объект провенанса *постфактум*." + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "Проверка аттестации" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" +"Проверка объекта аттестации по файлу распространения требует проверки " +"каждого из следующих параметров:" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" +"``версия`` - ``1``. Верификатор **МОЖЕТ** отклонить любую другую версию." + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" +"``verification_material.certificate`` - это действительный сертификат " +"подписи, выданный *априори* доверенным органом (например, корнем доверия, " +"который уже присутствует в проверяющем клиенте)." + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" +"``verification_material.certificate`` идентифицирует соответствующий субъект " +"подписи, например, идентификатор машины доверенного издателя, " +"опубликовавшего пакет." + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" +"``envelope.statement`` - это корректный in-toto v1 Statement, с темой и " +"дайджестом, которые **ДОЛЖНЫ** совпадать с именем и содержимым дистрибутива. " +"Для имени дистрибутива соответствие **ДОЛЖНО** быть выполнено путем разбора " +"с использованием соответствующего формата имени исходного дистрибутива или " +"колеса, так как тема заявления может быть эквивалентной, но нормализованной." + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" +"``envelope.signature`` является действительной подписью для " +"``envelope.statement``, соответствующей " +"``verification_material.certificate``, как восстановлено по протоколу " +"подписи `v1 DSSE `__." + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" +"В дополнение к вышеперечисленным действиям верификатор **МОЖЕТ** " +"дополнительно проверять ``материал_верификации.записи_прозрачности`` на " +"основе политики, например, требуя по крайней мере одну запись журнала " +"прозрачности или пороговое количество записей. При проверке записей о " +"прозрачности верификатор **ДОЛЖЕН** подтвердить, что время включения каждой " +"записи находится в пределах срока действия сертификата подписи." + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "Приложение: Модели данных для записей журнала прозрачности" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" +"Это приложение содержит псевдокодированные модели данных для записей журнала " +"прозрачности в объектах аттестации. Каждая запись журнала прозрачности " +"служит источником подписанного времени включения и может быть проверена как " +"онлайн, так и офлайн." + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "Встроенные метаданные сценария" + +#: ../source/specifications/inline-script-metadata.rst:7 +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 "" +"Эта спецификация определяет формат метаданных, которые могут быть встроены в " +"однофайловые скрипты Python, чтобы помочь программам запуска, IDE и другим " +"внешним инструментам, которым может понадобиться взаимодействовать с такими " +"скриптами." + +#: ../source/specifications/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" +"Эта спецификация определяет формат блока комментариев метаданных (в " +"значительной степени вдохновленный `reStructuredText Directives`__)." + +#: ../source/specifications/inline-script-metadata.rst:20 +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 "" +"Любой скрипт Python может иметь блоки комментариев верхнего уровня, которые " +"ДОЛЖНЫ начинаться со строки ``# /// TYPE``, где ``TYPE`` определяет, как " +"обрабатывать содержимое. То есть: один ``#``, затем один пробел, затем три " +"прямые косые черты, затем один пробел, затем тип метаданных. Блок ДОЛЖЕН " +"заканчиваться строкой ``# ///``. То есть: один ``#``, за которым следует " +"один пробел, а затем три прямые косые черты. ``TYPE`` ДОЛЖЕН состоять только " +"из букв ASCII, цифр и дефисов." + +#: ../source/specifications/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" +"Каждая строка между этими двумя строками (``# /// TYPE`` и ``# ///``) ДОЛЖНА " +"быть комментарием, начинающимся с ``#``. Если после ``#`` идут символы, то " +"первым символом должен быть пробел. Встроенное содержимое формируется путем " +"удаления первых двух символов каждой строки, если второй символ - пробел, в " +"противном случае - только первого символа (что означает, что строка состоит " +"только из одного ``#``)." + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" +"Приоритет для завершающей строки ``# ///`` отдается в том случае, если " +"следующая строка не является допустимой строкой встроенного содержимого, как " +"описано выше. Например, ниже приведен один полностью допустимый блок:" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" +"Начальная линия НЕ ДОЛЖНА располагаться между другой начальной и конечной " +"линиями. В таких случаях инструменты МОГУТ выдать ошибку. Незакрытые блоки " +"ДОЛЖНЫ игнорироваться." + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" +"Если определено несколько блоков комментариев одного и того же ``типа``, " +"инструменты ДОЛЖНЫ выдать ошибку." + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" +"Средства чтения встроенных метаданных МОГУТ соблюдать стандартное объявление " +"кодировки Python. Если они этого не делают, они ДОЛЖНЫ обрабатывать файл в " +"кодировке UTF-8." + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" +"Это каноническое регулярное выражение, которое МОЖЕТ быть использовано для " +"разбора метаданных:" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" +"В случае расхождения между текстовой спецификацией и регулярным выражением " +"приоритет отдается текстовой спецификации." + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" +"Инструменты НЕ ДОЛЖНЫ читать из блоков метаданных с типами, которые не были " +"стандартизированы данной спецификацией." + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "тип скрипта" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" +"Первый тип блока метаданных называется ``script`, он содержит метаданные " +"сценария (данные о зависимостях и конфигурации инструментов)." + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" +"Этот документ МОЖЕТ включать поля верхнего уровня ``зависимости`` и " +"``требования-python``, и МОЖЕТ опционально включать таблицу ``[инструмент]``." + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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 "" +"Таблица ``[tool]`` МОЖЕТ использоваться любым инструментом, исполнителем " +"скриптов или другим, для настройки поведения. Она имеет ту же семантику, что " +"и таблица :ref:`[tool] в pyproject.toml `." + +#: ../source/specifications/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "К полям верхнего уровня относятся:" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" +"``зависимости``: Список строк, определяющих зависимости скрипта от времени " +"выполнения. Каждая запись ДОЛЖНА быть действительным :ref:`спецификатором " +"зависимости `." + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" +"``requires-python``: Строка, указывающая версию(и) Python, с которой(ыми) " +"совместим(ы) скрипт. Значение этого поля ДОЛЖНО быть " +"действительным :ref:`спецификатором версии `." + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" +"Программы запуска сценариев ДОЛЖНЫ ошибаться, если указанные ``зависимости`` " +"не могут быть предоставлены. Программы запуска сценариев ДОЛЖНЫ ошибаться, " +"если не может быть предоставлена версия Python, удовлетворяющая указанному " +"``требованию-python``." + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "Ниже приведен пример сценария со встроенными метаданными:" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" +"Ниже приведен пример того, как читать метаданные на Python 3.11 и выше." + +#: ../source/specifications/inline-script-metadata.rst:151 +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 "" +"Часто для редактирования зависимостей используются такие инструменты, как " +"менеджеры пакетов или автоматизация обновления зависимостей в CI. Ниже " +"приведен пример изменения содержимого с помощью библиотеки ``tomlkit``." + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" +"Обратите внимание, что в этом примере использовалась библиотека, сохраняющая " +"форматирование TOML. Это ни в коем случае не является обязательным условием " +"редактирования, а скорее \"приятная возможность\"." + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "Ниже приведен пример чтения потока произвольных блоков метаданных." + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "Рекомендации" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" +"Инструменты, поддерживающие управление различными версиями Python, должны " +"пытаться использовать самую высокую доступную версию Python, совместимую с " +"метаданными скрипта ``requires-python``, если они определены." + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" +"Октябрь 2023 года: Эта спецификация была условно утверждена через :pep:`723`." + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" +"Январь 2024 года: Благодаря поправкам к :pep:`723`, тип блока метаданных " +"``pyproject`` был переименован в ``скрипт``, а таблица ``[ запускать]`` была " +"удалена, сделав ключи ``зависимости`` и ``запросы-python`` ключами верхнего " +"уровня. Кроме того, спецификация больше не является предварительной." + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +#, fuzzy +#| msgid "Some additional examples of valid ``License-Expression`` values:" +msgid "Examples of valid license expressions:" +msgstr "" +"Некоторые дополнительные примеры допустимых значений ``License-Expression``:" + +#: ../source/specifications/license-expression.rst:45 +#, fuzzy +#| msgid "Some additional examples of valid ``License-Expression`` values:" +msgid "Examples of invalid license expressions:" +msgstr "" +"Некоторые дополнительные примеры допустимых значений ``License-Expression``:" + +#: ../source/specifications/name-normalization.rst:3 +msgid "Names and normalization" +msgstr "Имена и нормализация" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" +"Эта спецификация определяет формат, которому должны соответствовать имена " +"пакетов и дополнений. Она также описывает, как их нормализовать, что следует " +"делать перед поиском и сравнением." + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "Формат имени" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" +"Правильное имя состоит только из букв и цифр ASCII, точки, подчеркивания и " +"дефиса. Оно должно начинаться и заканчиваться буквой или цифрой. Это " +"означает, что допустимые имена проектов ограничены теми, которые " +"соответствуют следующему regex (выполняется с :py:data:`re.IGNORECASE`)::" + +#: ../source/specifications/name-normalization.rst:26 +msgid "Name normalization" +msgstr "Нормализация имен" + +#: ../source/specifications/name-normalization.rst:28 +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:" +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 +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 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" +"``FrIeNdLy-._.-bArD`` (это *ужасный* способ написания имени, но он " +"действителен)" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" +"Сентябрь 2015 г: Спецификация имени нормализованные была одобрена " +"через :pep:`503 <503#нормализованные названия>`." + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" +"Ноябрь 2015 г: Спецификация допустимых имен была одобрена через :pep:`508 " +"<508#names>`." + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "Теги совместимости платформ" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" +"Метки совместимости с платформами позволяют инструментам сборки помечать " +"дистрибутивы как совместимые с определенными платформами, а установщикам - " +"понимать, какие дистрибутивы совместимы с системой, на которой они работают." + +#: ../source/specifications/platform-compatibility-tags.rst: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 "'cp32dmu', '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`` указывает на совместимость с Python 2.7 " +"(любой реализацией Python 2.7) без требования abi, на любой платформе." + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" +"Формат собранных пакетов ``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 ``_``." +msgstr "" +"Любые потенциальные пробелы в любом теге должны быть заменены на ``_``." + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "Метка Python" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" +"Метка Python указывает на реализацию и версию, требуемую дистрибутивом. " +"Основные реализации изначально имеют сокращенные коды:" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "py: Generic 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/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "jy: Jython" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" +"Другие реализации Python должны использовать :py: " +"данные:`sys.implementation. название `." + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" +"Версия - это ``py_version_nodot``. CPython обходится без точки, но если она " +"необходима, то вместо нее используется знак подчеркивания ``_``. PyPy, " +"вероятно, должен использовать здесь свои собственные версии ``pp18``, " +"``pp19``." + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" +"Версия может быть просто основной версией ``2`` или ``3`` ``py2``, ``py3`` " +"для многих дистрибутивов pure-Python." + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" +"Важно отметить, что такие теги, как ``py2`` и ``py3``, относящиеся только к " +"мажорным версиям, не являются сокращением для ``py20`` и ``py30``. " +"Напротив, эти метки означают, что упаковщик намеренно выпустил кросс-" +"версионный совместимый дистрибутив." + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" +"Дистрибутив с одним источником, совместимый с Python 2/3, может использовать " +"составной тег ``py2.py3``. См. раздел ``Сжатые наборы тегов``, ниже." + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "Тег ABI" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" +"Метка ABI указывает, какой ABI Python требуется для всех включенных модулей " +"расширения. Для ABI, специфичных для конкретной реализации, реализация " +"сокращается так же, как и тег Python, например, ``cp33d`` будет означать " +"CPython 3.3 ABI с отладкой." + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" +"Стабильный ABI CPython - ``abi3``, как и суффикс разделяемой библиотеки." + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" +"Реализации с очень нестабильным ABI могут использовать первые 6 байт (как 8 " +"символов в base64-кодировке) SHA-256 хэша ревизии исходного кода, флаги " +"компилятора и т. д., но, вероятно, не будут испытывать большой потребности в " +"распространении бинарных дистрибутивов. Сообщество каждой реализации может " +"решать, как лучше использовать метку ABI." + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "Метка платформы" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "Базовые теги платформы" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" +"В своей простейшей форме тег платформы - " +"это :py:func:`sysconfig.get_platform()`` со всеми дефисами ``-`` и периодами " +"``.``, замененными на подчеркивание ``_``. До удаления :ref:`distutils` в " +"Python 3.12, это было ``distutils.util.get_platform()``. Например:" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "win32" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "linux_i386" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "linux_x86_64" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "``manylinux``" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" +"Простая схема, описанная выше, недостаточна для публичного распространения " +"файлов wheel на платформах Linux из-за большой экосистемы платформ Linux и " +"тонких различий между ними." + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" +"Вместо этого, для этих платформ стандарт ``manylinux`` представляет общее " +"подмножество платформ Linux и позволяет создавать колеса, помеченные тегом " +"платформы ``manylinux``, которые могут быть использованы в большинстве " +"распространенных дистрибутивов Linux." + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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 "" +"Текущий стандарт - это защищенный от будущего стандарт :file:`manylinux_{x}" +"_{y}`. Он определяет теги вида :file:`manylinux_{x}_{y}_{arch}`, где ``x`` и " +"``y`` - поддерживаемые версии glibc major и minor (например, " +"``manylinux_2_24_xxx`` должен работать на любом дистрибутиве, использующем " +"glibc 2.24+), а ``arch`` - архитектура, соответствующая " +"значению :py:func:`sysconfig.get_platform()` на системе, как в \"простой\" " +"форме выше." + +#: ../source/specifications/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" +"Следующие старые теги по-прежнему поддерживаются для обратной совместимости:" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" +"``manylinux1`` поддерживает glibc 2.5 на архитектурах ``x86_64`` и ``i686``." + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "``manylinux2010`` поддерживает glibc 2.12 на ``x86_64`` и ``i686``." + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" +"``manylinux2014`` поддерживает glibc 2.17 на ``x86_64``, ``i686``, " +"``aarch64``, ``armv7l``, ``ppc64``, ``ppc64le``, и ``390x``." + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" +"В целом, дистрибутивы, созданные для старых версий спецификации, являются " +"совместимыми вперед (то есть дистрибутивы ``manylinux1`` должны продолжать " +"работать на современных системах), но не совместимыми назад (то есть " +"дистрибутивы ``manylinux2010`` не должны работать на платформах, " +"существовавших до 2010 года)." + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" +"Сопровождающие пакеты должны стараться использовать максимально совместимую " +"спецификацию, с оговоркой, что предоставленная среда сборки для " +"``manylinux1`` и ``manylinux2010`` уже отжила свой век, а значит, эти образы " +"больше не будут получать обновления безопасности." + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" +"В следующей таблице приведены минимальные версии соответствующих проектов " +"для поддержки различных стандартов ``manylinux``:" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "Инструмент" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "``manylinux1``" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "``manylinux2010``" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "``manylinux2014``" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "``manylinux_x_y``" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "``>=8.1.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "``>=19.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "``>=19.3``" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "``>=20.3``" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "auditwheel" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "``>=1.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "``>=2.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "``>=3.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "``>=3.3.0`` [#]_" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "В auditwheel 3.3.0 добавлена только поддержка ``manylinux_2_24``" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "``musllinux``" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +#, fuzzy +#| 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 :file:`musllinux_{x}_{y}_{arch}" +#| "``, supporting musl ``x.y`` and higher on the architecture ``arch``." +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" +"Семейство тегов ``musllinux`` аналогично ``manylinux``, но для Linux-" +"платформ, использующих не glibc, а musl_ libc (яркий пример - Alpine Linux). " +"Схема :file:`musllinux_{x}_{y}_{arch}``, поддерживающая musl ``x.y`` и выше " +"на архитектуре ``arch``." + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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 "" +"Значения версий musl можно получить, выполнив команду musl libc shared " +"library, на которой в данный момент работает интерпретатор Python, и " +"разобрав полученный результат:" + +#: ../source/specifications/platform-compatibility-tags.rst:193 +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 "" +"В настоящее время существует два способа найти местоположение библиотеки " +"musl, на котором запущен интерпретатор Python: либо с помощью системной " +"команды ldd_, либо путем разбора значения секции ``PT_INTERP`` из заголовка " +"ELF_ исполняемого файла." + +#: ../source/specifications/platform-compatibility-tags.rst:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" +"В macOS используется семейство тегов ``macosx`` (суффикс ``x`` является " +"историческим артефактом официальной схемы именования macOS от Apple). Схема " +"тегов совместимости - :file:`macosx_{x}_{y}_{arch}`, указывающая на то, что " +"колесо совместимо с macOS ``x.y`` или более поздними версиями на архитектуре " +"``arch``." + +#: ../source/specifications/platform-compatibility-tags.rst:207 +#, fuzzy +#| msgid "" +#| "The values of ``x`` and ``y`` correspond to the major and minor version " +#| "number of the macOS release, respectively. They must both be positive " +#| "integers, with the ``x`` value being ``>= 10``. The version number always " +#| "includes a major *and* minor version, even if Apple's official version " +#| "numbering only refers to the major value. For example, " +#| "``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" +"Значения ``x`` и ``y`` соответствуют мажорному и минорному номеру версии " +"выпуска macOS, соответственно. Оба они должны быть положительными целыми " +"числами, причем значение ``x`` должно быть ``>= 10``. Номер версии всегда " +"включает в себя мажорную *и* минорную версии, даже если официальная " +"нумерация версий Apple ссылается только на мажорное значение. Например, " +"``macosx_11_0_arm64`` указывает на совместимость с macOS 11 или более " +"поздней версией." + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" +"Двоичные файлы macOS могут быть скомпилированы для одной архитектуры, а " +"могут включать поддержку нескольких архитектур в одном двоичном файле " +"(иногда их называют \"толстыми\" двоичными файлами). Чтобы указать на " +"поддержку одной архитектуры, значение ``arch`` должно совпадать со " +"значением :py:func:`platform.machine()` в системе. Чтобы указать на " +"поддержку нескольких архитектур, тег ``arch`` должен быть идентификатором из " +"следующего списка, описывающего набор поддерживаемых архитектур:" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +#, fuzzy +msgid "``arch``" +msgstr "``arch``" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "Поддержка архитектуры" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "``универсальный2``" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +#, fuzzy +#| msgid "``x86_64``" +msgid "``arm64``, ``x86_64``" +msgstr "``arm64``, ``x86_64``" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "``универсальный``" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +#, fuzzy +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "``i386``, ``ppc``, ``ppc64``, ``x86_64``" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +#, fuzzy +#| msgid "``install``" +msgid "``intel``" +msgstr "``intel``" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +#, fuzzy +#| msgid "``x86_64``" +msgid "``i386``, ``x86_64``" +msgstr "``i386``, ``x86_64``" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +#, fuzzy +msgid "``fat``" +msgstr "``fat``" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +#, fuzzy +#| msgid "``3.4``, ``2.7``" +msgid "``i386``, ``ppc``" +msgstr "``i386``, ``ppc``" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +#, fuzzy +msgid "``fat3``" +msgstr "``fat3``" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +#, fuzzy +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "``i386``, ``ppc``, ``x86_64``" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +#, fuzzy +#| msgid "``x86_64``" +msgid "``fat64``" +msgstr "``fat64``" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +#, fuzzy +#| msgid "``x86_64``" +msgid "``ppc64``, ``x86_64``" +msgstr "``ppc64``, ``x86_64``" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" +"Минимальная поддерживаемая версия macOS также может быть ограничена " +"архитектурой. Например, macOS 11 (Big Sur) была первой версией, " +"поддерживающей arm64. Эти дополнительные ограничения прозрачно применяются " +"инструментальной цепочкой компиляции macOS при сборке двоичных файлов, " +"поддерживающих несколько архитектур." + +#: ../source/specifications/platform-compatibility-tags.rst:241 +#, fuzzy +msgid "Android" +msgstr "Android" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" +"Android использует схему :file:`android_{apilevel}_{abi}`, указывающую на " +"совместимость с данным уровнем API Android или более поздним, на данном ABI. " +"Например, ``android_27_arm64_v8a`` указывает на поддержку уровня API 27 или " +"более позднего, на устройствах ``arm64_v8a``. Android не делает различий " +"между физическими и эмулируемыми устройствами." + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" +"Уровень API должен быть целым положительным числом. Это *не* то же самое, " +"что версия Android для пользователя. Например, релиз, известный как Android " +"12 (кодовое название \"Snow Cone\"), использует уровень API 31 или 32, в " +"зависимости от конкретной используемой версии Android. Полный список версий " +"Android и соответствующих им уровней API содержится в документации по " +"релизам Android `__." + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" +"Существует 4 поддерживаемых ABI `__. Нормализованные в соответствии с правилами выше, они таковы:" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +#, fuzzy +msgid "``armeabi_v7a``" +msgstr "``armeabi_v7a``" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +#, fuzzy +msgid "``arm64_v8a``" +msgstr "``arm64_v8a``" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +#, fuzzy +#| msgid "``x86_64``" +msgid "``x86``" +msgstr "``x86``" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" +"Практически все современные физические устройства используют одну из " +"архитектур ARM. Для использования в эмуляторе поддерживаются ``x86`` и " +"``x86_64``. ``x86`` не поддерживается в качестве платформы разработки с 2020 " +"года, и с тех пор не было выпущено ни одного нового образа эмулятора." + +#: ../source/specifications/platform-compatibility-tags.rst:272 +#, fuzzy +msgid "iOS" +msgstr "iOS" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" +"iOS использует схему :file:`ios_{x}_{y}_{arch}_{sdk}`, указывающую на " +"совместимость с iOS ``x.y`` или более поздней версии, на архитектуре " +"``arch``, с использованием ``sdk`` SDK." + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" +"Значения ``x`` и ``y`` соответствуют номеру мажорной и минорной версии " +"релиза iOS, соответственно. Оба они должны быть положительными целыми " +"числами. Номер версии всегда включает в себя мажорную *и* минорную версии, " +"даже если официальная нумерация версий Apple ссылается только на мажорное " +"значение. Например, ``ios_13_0_arm64_iphonesimulator`` указывает на " +"совместимость с iOS 13 или более поздней версией." + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" +"Значение ``arch`` должно совпадать со " +"значением :py:func:`platform.machine()` в системе." + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" +"Значение ``sdk` должно быть либо ``iphoneos`` (для физических устройств), " +"либо ``iphonesimulator`` (для симуляторов устройств). Эти SDK имеют " +"одинаковую поверхность API, но несовместимы на бинарном уровне, даже если " +"они работают на одной архитектуре процессора. Код, скомпилированный для " +"симулятора arm64, не будет работать на устройстве arm64." + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" +"Комбинация :file:`{arch}_{sdk}` называется \"multiarch\". Существует три " +"возможных значения для multiarch:" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" +"``arm64_iphoneos``, для физических устройств iPhone/iPad. Сюда входят все " +"iOS-устройства, выпущенные с ~2015 года;" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" +"``arm64_iphonesimulator``, для симуляторов, работающих на оборудовании Apple " +"Silicon macOS; и" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" +"``x86_64_iphonesimulator``, для симуляторов, работающих на оборудовании " +"x86_64." + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "Используйте" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" +"Теги используются программами установки, чтобы решить, какой собранный " +"дистрибутив (если таковой имеется) загрузить из списка потенциальных " +"собранных дистрибутивов. Программа установки ведет список кортежей (pyver, " +"abi, arch), которые она будет поддерживать. Если тег собранного " +"дистрибутива находится ``в`` этом списке, то он может быть установлен." + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" +"Рекомендуется, чтобы программы установки старались выбирать наиболее " +"функционально полный собранный дистрибутив (наиболее подходящий для среды " +"установки) по умолчанию, прежде чем возвращаться к версиям чистого Python, " +"опубликованным для старых версий Python. Инсталляторам также рекомендуется " +"предоставлять возможность настраивать и изменять список разрешенных тегов " +"совместимости; например, пользователь может принимать только теги ``*-none-" +"any``, чтобы загружать только те собранные пакеты, которые рекламируют себя " +"как чистый Python." + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" +"Еще одной желательной функцией программы установки может быть включение " +"опции \"перекомпилировать из исходного кода, если это возможно\" как более " +"предпочтительной, чем некоторые совместимые, но устаревшие опции " +"предварительной сборки." + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" +"Этот пример списка предназначен для программы установки, работающей под " +"управлением CPython 3.3 на системе linux_x86_64. Он расположен в порядке от " +"наиболее предпочтительного (дистрибутив с скомпилированным модулем " +"расширения, собранный для текущей версии Python) до наименее " +"предпочтительного (дистрибутив чистого Python, собранный для более старой " +"версии Python):" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "cp33-cp33m-linux_x86_64" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "cp33-abi3-linux_x86_64" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "cp3-abi3-linux_x86_64" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "cp33-none-linux_x86_64*" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "cp3-none-linux_x86_64*" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "py33-none-linux_x86_64*" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "py3-none-linux_x86_64*" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "cp33-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "cp3-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "py33-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "py3-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "py32-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "py31-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "py30-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" +"Собранные дистрибутивы могут быть специфичными для конкретной платформы по " +"причинам, не связанным с расширениями C, например, путем включения " +"собственного исполняемого файла, вызываемого в качестве подпроцесса." + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" +"Иногда для определенной версии пакета существует более одного " +"поддерживаемого собранного дистрибутива. Например, упаковщик может " +"выпустить пакет с тегом ``cp33-abi3-linux_x86_64``, содержащий " +"необязательное расширение C, и такой же дистрибутив с тегом ``py3-none-" +"any``, не содержащий его. Индекс тега в списке поддерживаемых тегов " +"разрушает равенство, и пакет с расширением C устанавливается " +"предпочтительнее, чем пакет без него, поскольку этот тег появляется первым в " +"списке." + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "Сжатые наборы тегов" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +#, fuzzy +#| 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::" +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, collection 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 "" +"Чтобы обеспечить компактные имена файлов bdist, которые работают с более чем " +"одной тройкой тегов совместимости, каждый тег в имени файла может быть '.'-" +"разделенным, отсортированным набором тегов. Например, pip, чисто " +"питоновский пакет, написанный для работы под Python 2 и 3 с одинаковым " +"исходным кодом, может распространять bdist с тегом ``py2.py3-none-any``. " +"Полный список простых тегов выглядит так::" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" +"Формат bdist, реализующий эту схему, должен включать расширенные теги в " +"метаданные, специфичные для bdist. Эта схема сжатия может генерировать " +"большое количество неподдерживаемых тегов и \"невозможных\" тегов, которые " +"не поддерживаются ни одной реализацией Python, например, \"cp33-cp31u-" +"win64\", поэтому используйте ее осторожно." + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "Какие теги используются по умолчанию?" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +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`` или наиболее " +"предпочтительный тег чистого python, например, ``py33-none-any``. Если " +"упаковщик переопределяет значение по умолчанию, это указывает на то, что он " +"намерен обеспечить кросс-Python совместимость." + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" +"Какой тег мне использовать, если в моем дистрибутиве используется функция, " +"эксклюзивная для новейшей версии Python?" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" +"Теги совместимости помогают установщикам выбрать *наиболее совместимую* " +"сборку *одной версии* дистрибутива. Например, когда не существует сборки " +"``beaglevote-1.2.0``, совместимой с Python 3.3 (она использует эксклюзивную " +"возможность Python 3.4), можно использовать тег ``py3-none-any`` вместо тега " +"``py34-none-any``. Пользователь Python 3.3 должен комбинировать другие " +"квалификаторы, например, требовать более старый выпуск ``beaglevote-1.1.0``, " +"который не использует новую возможность, чтобы получить совместимую сборку." + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "Почему в номере версии Python нет ``.``?" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" +"CPython продержался 20 с лишним лет без трехзначного мажорного релиза. Это " +"должно продолжаться еще некоторое время. Другие реализации могут " +"использовать _ в качестве разделителя, поскольку и -, и . разграничивают " +"окружающее имя файла." + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" +"Зачем приводить дефисы и другие неалфавитные символы в соответствие с " +"символами подчеркивания?" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" +"Чтобы избежать конфликта с символами ``.`` и ``-``, разделяющими компоненты " +"имени файла, а также для лучшей совместимости с широким спектром ограничений " +"файловой системы для имен файлов (включая возможность использования в URL-" +"путях без кавычек)." + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" +"Почему бы не использовать специальный символ , а не ``.`` или ``-``?" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" +"Либо потому, что этот символ неудобен или потенциально запутан в некоторых " +"контекстах (например, ``+`` должен быть заключен в кавычки в URL, ``~`` " +"используется для обозначения домашнего каталога пользователя в POSIX), либо " +"потому, что преимущества не были достаточно убедительными, чтобы оправдать " +"изменение существующей реализации ссылки на формат колеса, определенный " +"в :pep:`427` (например, использование ``,`` вместо ``.`` для разделения " +"компонентов в сжатом теге)." + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "Кто будет вести реестр сокращенных реализаций?" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" +"Новые двухбуквенные аббревиатуры можно запросить в списке рассылки python-" +"dev. Как правило, аббревиатуры сохраняются для 4 наиболее известных " +"реализаций." + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "Тег совместимости помещается в METADATA или PKG-INFO?" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" +"Нет. Метка совместимости является частью метаданных собранного " +"дистрибутива. METADATA / PKG-INFO должны быть действительны для всего " +"дистрибутива, а не для одной его сборки." + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "Почему вы не упомянули мою любимую реализацию Python?" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +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``." + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" +"Почему в эталонной реализации тег ABI (второй тег) иногда имеет значение " +"\"none\"?" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" +"Поскольку в Python 2 нет простого способа добраться до SOABI (эта концепция " +"пришла из более новых версий Python 3), эталонная реализация на момент " +"написания статьи выдает \"none\". В идеале она должна определять \"py27(d|m|" +"u)\" по аналогии с новыми версиями Python, но пока что \"none\" - достаточно " +"хороший способ сказать \"не знаю\"." + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" +"Февраль 2013 г: Первоначальная версия этой спецификации была одобрена " +"через :pep:`425`." + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "Январь 2016 г: Метка ``manylinux1`` была одобрена через :pep:`513``." + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" +"Апрель 2018 г: Метка ``manylinux2010`` была одобрена через :pep:`571``." + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "Июль 2019: Метка ``manylinux2014`` была одобрена через :pep:`599``." + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" +"Ноябрь 2019: Многолетний тег ``manylinux_x_y`` был одобрен через :pep:`600`." + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" +"Апрель 2021 года: Метка ``musllinux_x_y`` была одобрена через :pep:`656``." + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "Декабрь 2023 года: Теги для iOS были одобрены через :pep:`730`." + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "Март 2024 года: Теги для Android были одобрены через :pep:`738`." + +#: ../source/specifications/project-status-markers.rst:5 +#, fuzzy +#| msgid "Project Summaries" +msgid "Project Status Markers" +msgstr "Обзор проектов" + +#: ../source/specifications/project-status-markers.rst:9 +#, fuzzy +#| msgid "This specification was originally defined in :pep:`740`." +msgid "This specification was originally defined in :pep:`792`." +msgstr "Эта спецификация была первоначально определена в :pep:`740`." + +#: ../source/specifications/project-status-markers.rst:14 +#, fuzzy +#| msgid "" +#| ":pep:`740` includes changes to the HTML and JSON index APIs. These " +#| "changes are documented in the :ref:`simple-repository-api` " +#| "under :ref:`simple-repository-api-base` and :ref:`json-serialization`." +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" +":pep:`740` включает изменения в HTML и JSON API индексов. Эти изменения " +"документированы в разделах :ref:`Simple-repository-api` под :ref:`Simple-" +"repository-api-base` и :ref:`json-serialization`." + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +#, fuzzy +#| msgid "Installation" +msgid "Installer semantics: none." +msgstr "Установка" + +#: ../source/specifications/project-status-markers.rst:45 +#, fuzzy +msgid "``archived``" +msgstr "``arch``" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +#, fuzzy +#| msgid "Installers" +msgid "Installer semantics:" +msgstr "Установщики" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +#, fuzzy +#| msgid "Deprecated" +msgid "``deprecated``" +msgstr "Устаревшее" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +#, fuzzy +#| msgid "``pyproject.toml`` specification" +msgid "``pylock.toml`` Specification" +msgstr "Спецификация ``pyproject.toml``" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +#, fuzzy +#| msgid "This specification was originally defined in :pep:`753`." +msgid "This specification was originally defined in :pep:`751`." +msgstr "Эта спецификация была первоначально определена в :pep:`753`." + +#: ../source/specifications/pylock-toml.rst:16 +#, fuzzy +#| msgid "Name" +msgid "File Name" +msgstr "Имя" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +#, fuzzy +#| msgid "``platform_version``" +msgid "``lock-version``" +msgstr "``платформа_версия``" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +#, fuzzy +#| msgid "Requires" +msgid "**Required?**: yes" +msgstr "Требуется" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +#, fuzzy +#| msgid "``entry-points``" +msgid "``environments``" +msgstr "``точки входа``" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +#, fuzzy +#| msgid "TOML_ type: array of strings" +msgid "**Type**: Array of strings" +msgstr "Тип TOML_: массив строк" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +#, fuzzy +#| msgid "TOML_ type: string" +msgid "**Type**: string" +msgstr "Тип TOML_: строка" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +#, fuzzy +#| msgid "The ``[dependency-groups]`` Table" +msgid "``dependency-groups``" +msgstr "Таблица ``[dependency-groups]``" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +#, fuzzy +#| msgid ":ref:`pyproject-toml-spec`" +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr ":ref:`pyproject-toml-spec`" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +#, fuzzy +#| msgid "" +#| "``INSTALLER``: records the name of the tool used to install the project." +msgid "Records the name of the tool used to create the lock file." +msgstr "" +"``INSTALLER``: записывает имя инструмента, используемого для установки " +"проекта." + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +#, fuzzy +#| msgid "``packages``" +msgid "``[[packages]]``" +msgstr "``пакеты``" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +#, fuzzy +#| msgid "TOML_ type: array of strings" +msgid "**Type**: array of tables" +msgstr "Тип TOML_: массив строк" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.name``" +msgstr "``пакеты``" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +#, fuzzy +#| msgid "" +#| "For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgid "The name of the package :ref:`normalized `." +msgstr "" +"Для сравнения имена должны быть :ref:`нормализованы <имя-нормализация>` " +"перед сравнением." + +#: ../source/specifications/pylock-toml.rst:210 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.version``" +msgstr "``пакеты``" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +#, fuzzy +#| msgid "Creating the package" +msgid "The version of the package." +msgstr "Создание пакета" + +#: ../source/specifications/pylock-toml.rst:216 +#, fuzzy +#| msgid "" +#| "``subject[0].name`` is the distribution's filename, which **MUST** be a " +#| "valid :ref:`source distribution ` " +#| "or :ref:`wheel distribution ` filename." +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" +"``subject[0].name`` - это имя файла дистрибутива, которое **МОЖЕТ** быть " +"действительным именем файла :ref:`source distribution ` или :ref:`wheel distribution `." + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.marker``" +msgstr "``пакеты``" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +#, fuzzy +#| msgid "``requires-python``" +msgid "``packages.requires-python``" +msgstr "``требуется-python``" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +#, fuzzy +#| msgid "``dependencies``" +msgid "``[[packages.dependencies]]``" +msgstr "``зависимости``" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +#, fuzzy +#| msgid "``packages``" +msgid "``[packages.vcs]``" +msgstr "``пакеты``" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +#, fuzzy +#| msgid "TOML_ type: table" +msgid "**Type**: table" +msgstr "TOML_ тип: таблица" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.vcs.type``" +msgstr "``пакеты``" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +#, fuzzy +#| msgid "Install from version control systems" +msgid "The type of version control system used." +msgstr "Установка из систем контроля версий" + +#: ../source/specifications/pylock-toml.rst:306 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.vcs.url``" +msgstr "``пакеты``" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +#, fuzzy +#| msgid "The source tree" +msgid "The URL_ to the source tree." +msgstr "Дерево исходного кода" + +#: ../source/specifications/pylock-toml.rst:317 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.vcs.path``" +msgstr "``пакеты``" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +#, fuzzy +#| msgid "``requested_revision`` field" +msgid "``packages.vcs.requested-revision``" +msgstr "поле ``запрошенный_пересмотр``" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.vcs.commit-id``" +msgstr "``пакеты``" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +#, fuzzy +#| 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." +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" +"Ключ ``commit_id`` (тип ``string``) ДОЛЖЕН присутствовать, содержащий точный " +"номер коммита/ревизии, которая была/есть установлена. Если VCS поддерживает " +"идентификаторы ревизий на основе commit-hash, то такой commit-hash ДОЛЖЕН " +"использоваться в качестве ``commit_id``, чтобы ссылаться на неизменяемую " +"версию исходного кода." + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +#, fuzzy +#| msgid "``packages``" +msgid "``[packages.directory]``" +msgstr "``пакеты``" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +#, fuzzy +#| msgid "``package_data``" +msgid "``packages.directory.path``" +msgstr "``package_data``" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +#, fuzzy +#| msgid "``packages``" +msgid "``[packages.archive]``" +msgstr "``пакеты``" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.archive.url``" +msgstr "``пакеты``" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.archive.path``" +msgstr "``пакеты``" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.archive.size``" +msgstr "``пакеты``" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +#, fuzzy +#| msgid "The name of the project." +msgid "The size of the archive file." +msgstr "Название проекта." + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +#, fuzzy +#| msgid "Where the guide is deployed" +msgid "The time the file was uploaded." +msgstr "Где развёрнуто руководство" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +#, fuzzy +#| msgid "TOML_ type: array of strings" +msgid "**Type**: Table of strings" +msgstr "Тип TOML_: массив строк" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +#, fuzzy +#| msgid "" +#| "A table of URLs where the key is the URL label and the value is the URL " +#| "itself." +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" +"Таблица URL-адресов, где ключом является метка URL, а значением - сам URL." + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.index``" +msgstr "``пакеты``" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +#, fuzzy +#| msgid "``packages``" +msgid "``[packages.sdist]``" +msgstr "``пакеты``" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +#, fuzzy +#| msgid "``package_data``" +msgid "``packages.sdist.name``" +msgstr "``package_data``" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +#, fuzzy +#| msgid "``package_data``" +msgid "``packages.sdist.upload-time``" +msgstr "``package_data``" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.sdist.url``" +msgstr "``пакеты``" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +#, fuzzy +#| msgid "``package_data``" +msgid "``packages.sdist.path``" +msgstr "``package_data``" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.sdist.size``" +msgstr "``пакеты``" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +#, fuzzy +#| msgid "``package_data``" +msgid "``packages.sdist.hashes``" +msgstr "``package_data``" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +#, fuzzy +#| msgid "``packages``" +msgid "``[[packages.wheels]]``" +msgstr "``пакеты``" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.wheels.name``" +msgstr "``пакеты``" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.wheels.url``" +msgstr "``пакеты``" + +#: ../source/specifications/pylock-toml.rst:647 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.wheels.path``" +msgstr "``пакеты``" + +#: ../source/specifications/pylock-toml.rst:655 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.wheels.size``" +msgstr "``пакеты``" + +#: ../source/specifications/pylock-toml.rst:663 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.wheels.hashes``" +msgstr "``пакеты``" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +#, fuzzy +#| msgid ":ref:`pyproject-toml-spec`" +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr ":ref:`pyproject-toml-spec`" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +#, fuzzy +#| msgid "``packages``" +msgid "``[packages.tool]``" +msgstr "``пакеты``" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +#, fuzzy +#| msgid "Binary distribution format" +msgid ":ref:`Install `." +msgstr "Формат распространения двоичных пакетов" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +#, fuzzy +#| msgid "" +#| "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" +"Версия API 1.0: Начальная версия API, объявленная с помощью :pep:`629`." + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "Файл :file:`.pypirc`" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" +"Файл :file:`.pypirc` позволяет определить конфигурацию для :term:`индексов " +"пакетов ` (называемых здесь \"репозиториями\"), так что вам " +"не придется вводить URL, имя пользователя или пароль всякий раз, когда вы " +"загружаете пакет с помощью :ref:`twine` или :ref:`flit`." + +#: ../source/specifications/pypirc.rst:13 +#, fuzzy +#| msgid "The :file:`.pypirc` file" +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "Файл :file:`.pypirc`" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "Формат (первоначально определенный пакетом :ref:`distutils`) таков:" + +#: ../source/specifications/pypirc.rst:37 +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/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "В каждом разделе, описывающем хранилище, определены три поля:" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "``репозиторий``: URL-адрес репозитория." + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" +"``имя пользователя``: Зарегистрированное имя пользователя в репозитории." + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" +"``пароль``: Пароль, который будет использоваться для аутентификации имени " +"пользователя." + +#: ../source/specifications/pypirc.rst:48 +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 "" +"Имейте в виду, что при этом ваш пароль сохраняется в виде обычного текста. " +"Для большей безопасности воспользуйтесь альтернативой вроде `keyring`_, " +"установите переменные окружения или введите пароль в командной строке." + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" +"В противном случае установите права на :file:`.pypirc`, чтобы только вы " +"могли просматривать или изменять его. Например, в Linux или macOS выполните " +"команду:" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "Общие конфигурации" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" +"Эти примеры относятся к :ref:`twine`. Другие проекты (например, :ref:`flit`) " +"также используют :file:`.pypirc`, но с другими значениями по умолчанию. За " +"более подробной информацией и инструкциями по использованию обращайтесь к " +"документации каждого проекта." + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" +"Конфигурация Twine по умолчанию имитирует файл :file:`.pypirc` с разделами " +"репозитория для PyPI и TestPyPI:" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" +"Twine добавит к этой конфигурации по умолчанию дополнительные настройки " +"из :file:`$HOME/.pypirc`, командной строки и переменных окружения." + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "Использование токена PyPI" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" +"Чтобы установить свой `API-токен`_ для PyPI, вы можете " +"создать :file:`$HOME/.pypirc`, подобный этому:" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" +"Для :ref:`TestPyPI `, добавьте секцию ``[testpypi]``, " +"используя API-токен от вашего аккаунта TestPyPI." + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "Использование индекса другого пакета" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" +"Чтобы настроить дополнительный репозиторий, вам нужно переопределить поле " +"``index-servers``, включив в него имя репозитория. Вот полный " +"пример :file:`$HOME/.pypirc` для PyPI, TestPyPI и частного репозитория:" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" +"Вместо того чтобы использовать поле ``пароль``, подумайте о безопасном " +"сохранении API-токенов и паролей с помощью `keyring`_ (которое " +"устанавливается в Twine):" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "Спецификация ``pyproject.toml``" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" +"Это **техническая, формальная спецификация**. Мягкое, удобное руководство по " +"``pyproject.toml`` см. в :ref:``writing-pyproject-toml``." + +#: ../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 "" +"Файл ``pyproject.toml`` выступает в качестве файла конфигурации для " +"инструментов, связанных с упаковкой (а также других инструментов)." + +#: ../source/specifications/pyproject-toml.rst:17 +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 "" +"Файл ``pyproject.toml`` написан на языке ``TOML `_. В " +"настоящее время заданы три таблицы, а именно :ref:`[build-system] `, :ref:`[project] ` " +"и :ref:`[tool] `. Остальные таблицы зарезервированы " +"для будущего использования (для конфигурации конкретных инструментов следует " +"использовать таблицу ``[tool]``)." + +#: ../source/specifications/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "Объявление зависимостей от системы сборки: таблица ``[build-system]``" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" +"В таблице ``[build-system]`` объявляются все зависимости уровня Python, " +"которые должны быть установлены для успешного запуска системы сборки проекта." + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" +"Таблица ``[build-system]`` используется для хранения данных, связанных со " +"сборкой. Изначально в таблице действует только один ключ, который является " +"обязательным для таблицы: ``requires``. Этот ключ должен иметь значение, " +"состоящее из списка строк, представляющих зависимости, необходимые для " +"выполнения системы сборки. Строки в этом списке " +"соответствуют :ref:`спецификации спецификатора версии `." + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" +"Пример таблицы ``[build-system]`` для проекта, собранного с помощью " +"``setuptools``:" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" +"Предполагается, что инструменты сборки будут использовать приведенный выше " +"пример конфигурационного файла в качестве семантики по умолчанию, если файл " +"``pyproject.toml`` отсутствует." + +#: ../source/specifications/pyproject-toml.rst:54 +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 "" +"Инструменты не должны требовать наличия таблицы ``[build-system]``. Файл " +"``pyproject.toml`` может использоваться для хранения конфигурационных " +"данных, отличных от данных, связанных со сборкой, и поэтому в нем может " +"отсутствовать таблица ``[build-system]``, что вполне законно. Если файл " +"существует, но в нем отсутствует таблица ``[build-system]``, то следует " +"использовать значения по умолчанию, как указано выше. Если таблица указана, " +"но в ней отсутствуют необходимые поля, то инструмент должен считать это " +"ошибкой." + +#: ../source/specifications/pyproject-toml.rst:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" +"Чтобы обеспечить специфическое представление результирующих данных из файла " +"TOML только для иллюстрации, следующая `JSON Schema `_ будет соответствовать формату данных:" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "Объявление метаданных проекта: таблица ``[project]``" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" +"Таблица ``[project]`` определяет метаданные ядра проекта `." + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" +"Существует два вида метаданных: *статические* и *динамические*. Статические " +"метаданные указываются непосредственно в файле ``pyproject.toml`` и не могут " +"быть указаны или изменены инструментом (сюда входят данные, на которые " +"ссылаются метаданные, например, содержимое файлов, на которые ссылаются " +"метаданные). Динамические метаданные перечисляются с помощью ключа " +"``dynamic`` (определяется позже в этой спецификации) и представляют собой " +"метаданные, которые инструмент предоставит позже." + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" +"Отсутствие таблицы ``[project]`` неявно означает, что :term:`build backend " +"` будет динамически предоставлять все ключи." + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" +"Единственными ключами, которые должны быть определены статически, являются:" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" +"Ключи, которые являются обязательными, но могут быть указаны либо " +"статически, либо как динамические, следующие:" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" +"Все остальные ключи считаются необязательными и могут быть указаны " +"статически, перечислены как динамические или не указаны." + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "Полный список ключей, допустимых в таблице ``[project]``, таков:" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "``авторы``" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "``зависимости``" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "``динамический``" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "``точки входа``" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "``gui-скрипт``" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +#, fuzzy +#| msgid "``name``" +msgid "``import-names``" +msgstr "``name``" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "``мастера``" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "``опциональные зависимости``" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "Тип TOML_: строка" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" +"Соответствующее поле :ref:`core metadata `: :ref:`Name `" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "Название проекта." + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" +"Инструменты ДОЛЖНЫ :ref:`нормализовать <имя-нормализация>` это имя, как " +"только оно будет прочитано для внутренней согласованности." + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" +"Соответствующее поле :ref:`core metadata `: :ref:`Version " +"`" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" +"Версия проекта, как определено в спецификации спецификатора версии `." + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "Пользователи ДОЛЖНЫ предпочитать указывать уже нормализованные версии." + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" +"Соответствующее поле :ref:`core metadata `: :ref:`Summary " +"`" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" +"Краткое описание проекта в одной строке. Инструменты MAY ошибаются, если оно " +"включает несколько строк." + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "Тип TOML_: строка или таблица" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" +"Соответствующее поле :ref:`core metadata `: :ref:`Description " +"` и :ref:`Description-Content-Type `" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "Полное описание проекта (то есть README)." + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" +"Ключ принимает значение либо строки, либо таблицы. Если это строка, то это " +"путь относительно ``pyproject.toml`` к текстовому файлу, содержащему полное " +"описание. Инструменты ДОЛЖНЫ считать, что кодировка файла - UTF-8. Если путь " +"к файлу заканчивается суффиксом ``.md`` без учета регистра, то инструменты " +"ДОЛЖНЫ считать, что тип содержимого - ``text/markdown``. Если путь к файлу " +"заканчивается суффиксом ``.rst``, то инструменты ДОЛЖНЫ считать, что тип " +"содержимого - ``text/x-rst``. Если инструмент распознает больше расширений, " +"чем этот PEP, он МОЖЕТ определить тип содержимого для пользователя, не " +"указывая этот ключ как ``динамический``. Для всех нераспознанных суффиксов, " +"когда тип содержимого не указан, инструменты ДОЛЖНЫ выдавать ошибку." + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" +"Ключ ``readme`` также может принимать вид таблицы. Ключ ``file`` имеет " +"строковое значение, представляющее собой путь относительно " +"``pyproject.toml`` к файлу, содержащему полное описание. Ключ ``text`` имеет " +"строковое значение, которое является полным описанием. Эти ключи являются " +"взаимоисключающими, поэтому инструменты ДОЛЖНЫ выдавать ошибку, если в " +"метаданных указаны оба ключа." + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" +"Таблица, указанная в ключе ``readme'', также имеет ключ ``content-type'', " +"который принимает строку, определяющую тип содержимого полного описания. " +"Инструмент ДОЛЖЕН выдать ошибку, если метаданные не указывают этот ключ в " +"таблице. Если в метаданных не указан параметр ``charset'', то " +"предполагается, что это UTF-8. Инструменты МОГУТ поддерживать другие " +"кодировки по своему усмотрению. Инструменты МОГУТ поддерживать " +"альтернативные типы содержимого, которые они могут преобразовать в тип " +"содержимого, поддерживаемый :ref:`core metadata `. В " +"противном случае инструменты ДОЛЖНЫ выдавать ошибку о неподдерживаемых типах " +"содержимого." + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" +"Соответствующее поле :ref:`core metadata `: :ref:`Requires-" +"Python `" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "Требования к версии Python для проекта." + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" +"Соответствующее поле :ref:`core metadata `: :ref:`License-" +"Expression `." + +#: ../source/specifications/pyproject-toml.rst:261 +#, fuzzy +#| msgid "" +#| "Text string that is a valid SPDX license expression as defined " +#| "in :pep:`639`. Tools SHOULD validate and perform case normalization of " +#| "the expression." +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" +"Текстовая строка, которая является действительным выражением лицензии SPDX, " +"как определено в :pep:`639`. Инструменты ДОЛЖНЫ проверять и выполнять " +"нормализацию регистра выражения." + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +#, fuzzy +#| msgid "PyPA specifications" +msgid "Legacy specification" +msgstr "Спецификации PyPA" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "TOML_ тип: таблица" + +#: ../source/specifications/pyproject-toml.rst:276 +#, fuzzy +#| msgid "" +#| "Corresponding :ref:`core metadata ` field: :ref:`License-" +#| "File `" +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" +"Соответствующее поле :ref:`core metadata `: :ref:`License-" +"File `" + +#: ../source/specifications/pyproject-toml.rst:279 +#, fuzzy +#| 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." +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" +"Таблица может иметь один из двух ключей. Ключ ``file`` имеет строковое " +"значение, которое представляет собой путь к файлу относительно " +"``pyproject.toml`` к файлу, содержащему лицензию на проект. Инструменты " +"ДОЛЖНЫ считать, что кодировка файла - UTF-8. Ключ ``text`` имеет строковое " +"значение, которое является лицензией проекта. Эти ключи являются " +"взаимоисключающими, поэтому инструмент ДОЛЖЕН выдать ошибку, если в " +"метаданных указаны оба ключа." + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "Тип TOML_: массив строк" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" +"Соответствующее поле :ref:`core metadata `: :ref:`License-" +"File `" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" +"Массив, указывающий пути в дереве исходных текстов проекта относительно " +"корневого каталога проекта (т.е. каталога, " +"содержащего :file:`pyproject.toml` или унаследованные файлы конфигурации " +"проекта, например :file:`setup.py`, :file:`setup.cfg` и т.д.) к файлу(ам) с " +"лицензиями и другими юридическими уведомлениями, которые будут " +"распространяться вместе с пакетом." + +#: ../source/specifications/pyproject-toml.rst:303 +#, fuzzy +#| msgid "The strings MUST contain valid glob patterns, as specified below:" +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "Строки ДОЛЖНЫ содержать правильные шаблоны glob, как указано ниже:" + +#: ../source/specifications/pyproject-toml.rst:306 +#, fuzzy +#| msgid "" +#| "Patterns are relative to the directory containing :file:`pyproject.toml`, " +#| "and thus may not start with a slash character." +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" +"Шаблоны являются относительными к директории, " +"содержащей :file:`pyproject.toml`, и поэтому не могут начинаться с символа " +"слэша." + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" +"Инструменты ДОЛЖНЫ предполагать, что содержимое файла лицензии является " +"правильным текстом в кодировке UTF-8, и ДОЛЖНЫ проверять его и выдавать " +"ошибку, если это не так." + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "Сборка инструментов:" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" +"ОБЯЗАТЕЛЬНО включите все файлы, соответствующие перечисленному шаблону, во " +"все архивы дистрибутива." + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" +"ДОЛЖЕН перечислить каждый совпадающий путь к файлу в поле License-File в " +"основных метаданных." + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" +"Если ключ ``license-files`` присутствует и имеет значение пустого массива, " +"то инструменты НЕ ДОЛЖНЫ включать никакие файлы лицензий и НЕ ДОЛЖНЫ " +"выдавать ошибку. Если ключ ``license-files`` не определен, инструменты могут " +"сами решать, как обращаться с файлами лицензий. Например, они могут не " +"включать никаких файлов или использовать собственную логику для обнаружения " +"соответствующих файлов в дистрибутиве." + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "TOML_ type: Массив строчных таблиц со строковыми ключами и значениями" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" +"Соответствующее поле :ref:`core metadata `: :ref:`Author " +"`, :ref:`Author-email `, :ref:`Maintainer `, и :ref:`Maintainer-" +"email `" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" +"Люди или организации, считающиеся \"авторами\" проекта. Точное значение " +"открыто для интерпретации - это может быть список оригинальных или основных " +"авторов, текущих сопровождающих или владельцев пакета." + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" +"Ключ \"maintainers\" похож на \"authors\" тем, что его точное значение можно " +"интерпретировать." + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" +"Эти ключи принимают массив таблиц с 2 ключами: ``имя`` и ``email``. Оба " +"значения должны быть строками. Значение ``name`` ДОЛЖНО быть действительным " +"именем электронной почты (т.е. тем, что может быть указано в качестве имени " +"перед электронной почтой в :rfc:`822`) и не содержать запятых. Значение " +"``email`` ДОЛЖНО быть действительным адресом электронной почты. Оба ключа " +"необязательны, но хотя бы один из них должен быть указан в таблице." + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" +"Использование данных для заполнения :ref:`core metadata ` " +"осуществляется следующим образом:" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" +"Если указано только ``имя``, значение помещается в :ref:`Author ` или :ref:`Maintainer ` в " +"зависимости от ситуации." + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" +"Если указан только ``email``, значение помещается в :ref:`Author-email ` или :ref:`Maintainer-email ` в зависимости от ситуации." + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" +"Если указаны и ``email``, и ``name``, значение помещается в :ref:`Author-" +"email ` или :ref:`Maintainer-email ` в зависимости от ситуации, с форматом ``{name} " +"<{email}>```." + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "Несколько значений должны быть разделены запятыми." + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" +"Соответствующее поле :ref:`core metadata `: :ref:`Keywords " +"`" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "Ключевые слова для проекта." + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" +"Соответствующее поле :ref:`core metadata `: :ref:`Classifier " +"`" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "Классификаторы Trove, применимые к проекту." + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" +"Использование классификаторов ``License ::`` устарело, и инструменты МОГУТ " +"выдавать предупреждение, информирующее об этом пользователей. Инструменты " +"сборки МОГУТ выдать ошибку, если используется как строковое значение " +"``license`` (перевод в поле метаданных ``License-Expression``), так и " +"классификаторы ``License ::``." + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "Тип TOML_: таблица с ключами и значениями строк" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" +"Соответствующее поле :ref:`core metadata `: :ref:`Project-URL " +"`" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" +"Таблица URL-адресов, где ключом является метка URL, а значением - сам URL. " +"См. :ref:`well-known-project-urls` для правил нормализации и общеизвестных " +"правил при обработке метаданных для представления." + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "Точки входа" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" +"Тип TOML_: таблица (``[project.scripts]``, ``[project.gui-scripts]``, и " +"``[project.entry-points]``)" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr ":ref:`Спецификация точек входа `" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" +"Существует три таблицы, связанные с точками входа. Таблица " +"``[project.scripts]`` соответствует группе ``console_scripts`` " +"в :ref:`спецификации точек входа `. Ключом таблицы является " +"имя точки входа, а значением - ссылка на объект." + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" +"Таблица ``[project.gui-scripts]`` соответствует группе ``gui_scripts`` в " +"спецификации точек входа `. Ее формат такой же, как и у " +"``[project.scripts]``." + +#: ../source/specifications/pyproject-toml.rst:436 +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/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" +"Внутренние компоненты сборки ДОЛЖНЫ выдавать ошибку, если метаданные " +"определяют таблицу ``[project.entry-points.console_scripts]`` или " +"``[project.entry-points.gui_scripts]``, поскольку они будут неоднозначными " +"перед лицом ``[project.scripts]`` и ``[project.gui-scripts]``, " +"соответственно." + +#: ../source/specifications/pyproject-toml.rst:455 +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` (``зависимости``), и таблица со " +"значениями массивов строк :pep:`508` (``опциональные-зависимости``)" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" +"Соответствующее поле :ref:`core metadata `: :ref:`Requires-" +"Dist ` и :ref:`Provides-Extra `" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "Зависимости проекта (необязательно)." + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" +"Для ``зависимостей`` это ключ, значением которого является массив строк. " +"Каждая строка представляет зависимость проекта и ДОЛЖНА быть отформатирована " +"как корректная строка :pep:`508`. Каждая строка сопоставляется " +"непосредственно с записью :ref:`Requires-Dist `." + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" +"Для ``optional-dependencies`` это таблица, в которой каждый ключ указывает " +"на дополнительное значение, а значение представляет собой массив строк. " +"Строки массивов должны быть действительными строками :pep:`508`. Ключи " +"ДОЛЖНЫ быть допустимыми значениями для :ref:`Provides-Extra `. Таким образом, каждое значение в массиве становится " +"соответствующей записью :ref:`Requires-Dist ` " +"для соответствующего метаданного :ref:`Provides-Extra `." + +#: ../source/specifications/pyproject-toml.rst:485 +#, fuzzy +#| msgid "" +#| "Corresponding :ref:`core metadata ` field: :ref:`Name " +#| "`" +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" +"Соответствующее поле :ref:`core metadata `: :ref:`Name `" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +msgid "Examples:" +msgstr "Примеры:" + +#: ../source/specifications/pyproject-toml.rst:536 +#, fuzzy +#| msgid "" +#| "Corresponding :ref:`core metadata ` field: :ref:`Name " +#| "`" +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" +"Соответствующее поле :ref:`core metadata `: :ref:`Name `" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +#, fuzzy +#| msgid "Example::" +msgid "Example:" +msgstr "Пример::" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "Тип TOML_: массив строк" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" +"Соответствующее поле :ref:`core metadata `: :ref:`Dynamic " +"`" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" +"Указывает, какие ключи, перечисленные в этом PEP, были намеренно не " +"определены, чтобы другой инструмент может/должен предоставить такие " +"метаданные динамически. Это четко определяет, какие метаданные намеренно не " +"определены и, как ожидается, останутся неопределенными по сравнению с тем, " +"что будет предоставлено с помощью инструментов позже." + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" +"Бэкэнд сборки ДОЛЖЕН почитать статически заданные метаданные (это означает, " +"что в метаданных не указан ключ в ``динамическом``)." + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" +"Внутренний модуль сборки ДОЛЖЕН выдать ошибку, если в метаданных указано " +"``имя`` в ``dynamic``." + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" +"Если в спецификации :ref:`core metadata ` указано поле как " +"\"Required\", то метаданные ДОЛЖНЫ указывать ключ статически или перечислять " +"его в ``dynamic`` (сборка бэкендов ДОЛЖНА выдавать ошибку в противном " +"случае, т.е. не должно быть возможности, чтобы требуемый ключ не был как-то " +"указан в таблице ``[project]``)." + +#: ../source/specifications/pyproject-toml.rst:595 +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:`core metadata ` поле указано как " +"\"Optional\", метаданные МОГУТ указывать его в ``dynamic``, если " +"предполагается, что сборка бэкенда предоставит данные для ключа позже." + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" +"Внутренние компоненты сборки ДОЛЖНЫ выдать ошибку, если метаданные указывают " +"ключ статически, а также перечислены в ``динамических``." + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" +"Если в метаданных не указан ключ в ``dynamic``, то бэкэнд сборки не сможет " +"заполнить необходимые метаданные от имени пользователя (т.е. ``dynamic`` - " +"это единственный способ позволить инструменту заполнить метаданные, и " +"пользователь должен согласиться на заполнение)." + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" +"Бэкэнд сборки ДОЛЖЕН выдать ошибку, если в метаданных указан ключ в " +"``dynamic``, но бэкэнд сборки не смог определить данные для него (опускание " +"данных, если определено, что это точное значение, допустимо)." + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "Произвольная конфигурация инструментов: таблица ``[tool]``" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" +"Таблица ``[tool]`` - это место, где любой инструмент, связанный с вашим " +"Python-проектом, не только инструменты сборки, может иметь пользователей, " +"указывающих конфигурационные данные, если они используют подтаблицу в " +"``[tool]``, например, инструмент `flit `_ " +"будет хранить свою конфигурацию в ``[tool.flit]``." + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" +"Необходим механизм для распределения имен в пространстве имен ``tool.*``, " +"чтобы убедиться, что разные проекты не пытаются использовать одну и ту же " +"подтаблицу и не сталкиваются. Наше правило заключается в том, что проект " +"может использовать подтаблицу ``tool.$NAME`` тогда и только тогда, когда он " +"владеет записью для ``$NAME`` в Cheeseshop/PyPI." + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" +"Май 2016 г: Первоначальная спецификация файла ``pyproject.toml``, содержащая " +"только ``[build-system]``, содержащую ключ ``requires`` и таблицу " +"``[tool]``, была одобрена через :pep:`518``." + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" +"Ноябрь 2020 года: Спецификация таблицы ``[проект]`` была утверждена " +"через :pep:`621``." + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" +"Декабрь 2024 года: Ключ ``license`` был переопределен, ключ ``license-" +"files`` был добавлен, а классификаторы ``License::`` были устаревшими " +"через :pep:`639`." + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "Запись установленных проектов" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" +"Этот документ определяет общий формат записи информации о " +"Python :term:`проектах `, установленных в среде. Общий формат " +"метаданных позволяет инструментам запрашивать, управлять или удалять " +"проекты, независимо от того, как они были установлены." + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" +"Почти вся информация является необязательной. Это позволяет инструментам вне " +"экосистемы Python, таким как менеджеры пакетов Linux, интегрироваться с " +"инструментарием 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``\", расположенный рядом с " +"импортируемыми модулями и пакетами (обычно это каталог ``ite-packages``)." + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" +"Этот каталог называется ``{имя}-{версия}.dist-info``, а поля ``имя`` и " +"``версия`` соответствуют :ref:`core-metadata``. Оба поля должны быть " +"нормализованы (см. спецификации :ref:`name normalization specification ` и :ref:`version normalization specification `) и заменять символы тире (``-``) на символы " +"подчеркивания (``_``), поэтому каталог ``.dist-info`` всегда имеет ровно " +"один символ тире (``-``) в своей строке, разделяющий поля ``name`` и " +"``version``." + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" +"Исторически сложилось так, что инструменты не заменяют символы точки или не " +"нормализуют регистр в поле ``имя``, или не выполняют нормализацию в поле " +"``версия``. Утилиты, использующие каталоги ``.dist-info``, должны ожидать, " +"что эти поля будут ненормализованными, и рассматривать их как эквивалентные " +"нормализованным аналогам. Новые инструменты, записывающие каталоги ``.dist-" +"info``, ДОЛЖНЫ нормализовать поля ``name`` и ``version``, используя правила, " +"описанные выше, а существующим инструментам рекомендуется начать " +"нормализацию этих полей." + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" +"Имя каталога ``.dist-info`` форматируется для однозначного представления " +"дистрибутива в виде пути к файловой системе. Утилиты, представляющие " +"пользователю имя дистрибутива, должны избегать использования " +"нормализованного имени, а вместо этого представлять указанное имя (если это " +"необходимо до разрешения установленного пакета) или читать соответствующие " +"поля в Core Metadata, поскольку значения, перечисленные там, не имеют " +"кодировки и точно отражают дистрибутив. Библиотеки должны предоставлять API " +"для таких инструментов, чтобы инструменты могли иметь доступ к " +"ненормализованному имени при отображении информации о дистрибутиве." + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" +"Этот каталог ``.dist-info`` может содержать следующие файлы, подробно " +"описанные ниже:" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "``METADATA``: содержит метаданные проекта" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "``RECORD``: записывает список установленных файлов." + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" +"``INSTALLER``: записывает имя инструмента, используемого для установки " +"проекта." + +#: ../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/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 "" +"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/recording-installed-packages.rst:69 +#, fuzzy +#| msgid "" +#| "This :file:`.dist-info/` directory may contain the following directory, " +#| "described in detail below:" +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" +"Этот каталог :file:`.dist-info/` может содержать следующие каталоги, " +"подробно описанные ниже:" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr ":file:`licenses/`: содержит файлы лицензий." + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" +"Спецификация :ref:`binary-distribution-format` описывает дополнительные " +"файлы, которые могут появиться в директории ``.dist-info`` " +"для :term:`Wheel`. Такие файлы могут быть скопированы в каталог ``.dist-" +"info`` установленного проекта." + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" +"В предыдущих версиях этой спецификации также указывался файл ``REQUESTED`` " +"Сейчас этот файл считается расширением, специфичным для конкретного " +"инструмента, но в будущем он может быть стандартизирован. Его первоначальное " +"значение см. в `PEP 376 `_." + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "Файл METADATA" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" +"Файл ``METADATA`` содержит метаданные, описанные в спецификации :ref:`core-" +"metadata``, версии 1.1 или выше." + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" +"Файл ``METADATA`` является обязательным. Если он не может быть создан или " +"если необходимые метаданные ядра отсутствуют, программа установки должна " +"сообщить об ошибке и не установить проект." + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "Файл RECORD" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"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/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" +"Диалект CSV должен быть доступен для чтения с помощью стандартного " +"``reader`` модуля Python ``csv``:" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "разделитель полей: ``,`` (запятая)," + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "Кавычки: ``''`` (прямая двойная кавычка)," + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "терминатор строки: либо ``\\r\\n``, либо ``\\n``." + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" +"Каждая запись состоит из трех элементов: **путь** файла, **хэш** его " +"содержимого и **размер**." + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" +"Путь *path* может быть как абсолютным, так и относительным к каталогу, " +"содержащему каталог ``.dist-info`` (обычно это каталог ``ite-packages``). В " +"Windows каталоги могут быть разделены прямыми или обратными слешами (``/`` " +"или ``\\``)." + +#: ../source/specifications/recording-installed-packages.rst:120 +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* используется либо пустая строка, либо имя хэш-алгоритма " +"из :py:data:`hashlib. алгоритмы_гарантированы`, за которым следует символ " +"равенства ``=`` и дайджест содержимого файла, закодированный с помощью " +"кодировки urlsafe-base64-nopad (:py:func:`base64.urlsafe_b64encode(digest) " +"` с удаленным ``=`` в конце)." + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" +"Параметр *size* - это либо пустая строка, либо размер файла в байтах, как " +"целое число по основанию 10." + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" +"Для любого файла любое из полей *hash* и *size* или оба могут быть пустыми. " +"Обычно записи для файлов ``.pyc`` и самого файла ``RECORD`` имеют пустые " +"*hash* и *size*. Для других файлов оставлять эту информацию не " +"рекомендуется, так как это мешает проверке целостности установленного " +"проекта." + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" +"Если файл ``RECORD`` присутствует, в нем должны быть перечислены все " +"установленные файлы проекта, за исключением файлов ``.pyc``, соответствующих " +"файлам ``.py``, перечисленным в ``RECORD``, которые являются " +"необязательными. В частности, должно быть перечислено содержимое каталога " +"``.dist-info`` (включая сам файл ``RECORD``). Каталоги перечислять не " +"следует." + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" +"Чтобы полностью удалить пакет, инструмент должен удалить все файлы, " +"перечисленные в ``RECORD``, все файлы ``.pyc`` (всех уровней оптимизации), " +"соответствующие удаленным файлам ``.py``, и все каталоги, опустошенные в " +"результате деинсталляции." + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "Вот пример фрагмента возможного файла ``RECORD``::" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" +"Если файл ``RECORD`` отсутствует, инструменты, полагающиеся на ``.dist-" +"info``, не должны пытаться удалить или обновить пакет. (Это ограничение не " +"распространяется на инструменты, которые полагаются на другие источники " +"информации, такие как системные менеджеры пакетов в дистрибутивах Linux.)" + +#: ../source/specifications/recording-installed-packages.rst:172 +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 "" +"Устанавливаемому пакету *сильно не рекомендуется* изменять себя (например, " +"хранить файлы кэша в своем пространстве имен в ``ite-packages``). Изменения " +"внутри ``site-packages` следует оставить специализированным инструментам " +"установки, таким как pip. Если пакет все же был изменен таким образом, то " +"необходимо обновить ``RECORD``, иначе при деинсталляции пакета на месте " +"останутся незарегистрированные файлы (возможно, это приведет к появлению " +"пакета-зомби в пространстве имен)." + +#: ../source/specifications/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "Файл INSTALLER" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" +"Если присутствует, ``INSTALLER`` - это однострочный текстовый файл с " +"названием инструмента, используемого для установки проекта. Если программа " +"установки исполняется из командной строки, ``INSTALLER`` должен содержать " +"имя команды. В противном случае в нем должна содержаться печатаемая ASCII-" +"строка." + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" +"Файл может быть завершен нулем или несколькими пробельными символами ASCII." + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "Вот примеры двух возможных файлов ``INSTALLER``::" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" +"Это значение следует использовать только в информационных целях. Например, " +"если инструменту предлагается удалить проект, но он не находит файла " +"``RECORD``, он может предположить, что инструмент, названный в " +"``INSTALLER``, может выполнить удаление." + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "Файл entry_points.txt" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" +"Этот файл МОЖЕТ быть создан программой установки, чтобы указать, когда " +"пакеты содержат компоненты, предназначенные для обнаружения и использования " +"другим кодом, включая консольные сценарии и другие приложения, которые " +"программа установки сделала доступными для выполнения." + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "Его подробная спецификация находится по адресу :ref:`entry-points`." + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "Файл direct_url.json" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" +"Этот файл ДОЛЖЕН создаваться программой установки при установке дистрибутива " +"из требования, указывающего прямую URL-ссылку (включая VCS URL)." + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "Его подробная спецификация находится по адресу :ref:`direct-url`." + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "Подкаталог :file:`licenses/`" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" +"Если версия метаданных 2.4 или выше и указано одно или несколько полей " +"``License-File``, каталог :file:`.dist-info/` ДОЛЖЕН содержать " +"подкаталог :file:`licenses/`, который ДОЛЖЕН содержать файлы, перечисленные " +"в полях ``License-File`` в файле :file:`METADATA`` по их соответствующим " +"путям относительно каталога :file:`licenses/`. Любые файлы в этом каталоге " +"ДОЛЖНЫ быть скопированы с колеса средствами установки." + +#: ../source/specifications/recording-installed-packages.rst:240 +#, fuzzy +#| msgid "The :file:`licenses/` subdirectory" +msgid "The :file:`sboms/` subdirectory" +msgstr "Подкаталог :file:`licenses/`" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "Намеренное предотвращение изменений в установленных пакетах" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" +"В некоторых случаях (например, при необходимости управлять внешними " +"зависимостями в дополнение к зависимостям экосистемы Python) желательно, " +"чтобы инструмент, устанавливающий пакеты в среду Python, не использовал " +"другие инструменты для удаления или иного изменения установленного пакета, " +"поскольку это может привести к проблемам совместимости с более широкой " +"средой." + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" +"Чтобы добиться этого, пострадавшие инструменты должны предпринять следующие " +"шаги:" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" +"Переименуйте или удалите файл ``RECORD``, чтобы предотвратить изменения с " +"помощью других инструментов (например, добавьте суффикс для создания " +"нестандартного файла ``RECORD.tool``, если информация нужна самому " +"инструменту, или полностью удалите файл, если содержимое пакета " +"отслеживается и управляется другими средствами)" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" +"Запишите файл ``INSTALLER``, указывающий имя инструмента, который должен " +"использоваться для управления пакетом (это позволяет инструментам, знающим " +"``RECORD``, выдавать более точные уведомления об ошибках при запросе на " +"модификацию затронутых пакетов)" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" +"Провайдеры среды выполнения Python также могут предотвратить " +"непреднамеренную модификацию пакетов, предоставляемых платформой, изменив " +"схему установки пакетов Python по умолчанию, чтобы использовать " +"местоположение, отличное от того, которое используется пакетами, " +"предоставляемыми платформой (при этом оба места должны быть указаны в пути " +"импорта Python по умолчанию)." + +#: ../source/specifications/recording-installed-packages.rst:272 +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:`externally-managed-environments`" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" +"Июнь 2009 г: Первоначальная версия этой спецификации была одобрена " +"через :pep:`376`. В то время она была известна как *База данных " +"установленных дистрибутивов Python*." + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" +"Март 2020 г: Спецификация файла ``direct_url.json`` была одобрена " +"через :pep:`610``. Он только упоминается на этой странице; полное " +"определение см. в :ref:`direct-url`." + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" +"Сентябрь 2020 года: Различные поправки и уточнения были одобрены " +"через :pep:`627`." + +#: ../source/specifications/schemas/index.rst:4 +#, fuzzy +#| msgid "Data schema" +msgid "PyPA schemas" +msgstr "Схема данных" + +#: ../source/specifications/schemas/index.rst:6 +#, fuzzy +#| msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgid "`direct_url.json `_" +msgstr "``direct_url.json``: подробности см. в :ref:`direct-url``" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "Метаданные установки пакета" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "Индекс пакета Интерфейсы" + +#: ../source/specifications/section-python-description-formats.rst:3 +#, fuzzy +#| msgid "Python versions over time" +msgid "Python Description Formats" +msgstr "Python версии с течением времени" + +#: ../source/specifications/section-reproducible-environments.rst:3 +#, fuzzy +#| msgid "Virtual Environment" +msgid "Reproducible Environments" +msgstr "Виртуальная среда" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "Простой API репозитория" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" +"Ключевые слова \"**MUST**\", \"**MUST NOT**\", \"**REQUIRED**\", " +"\"**SHALL**\", \"**SHALL NOT**\", \"**SHOULD**\", \"**SHOULD NOT**\", " +"\"**RECOMMENDED**\", \"**MAY**\" и \"**OPTIONAL**\" в этом документе должны " +"интерпретироваться, как описано в :rfc:`2119`." + +#: ../source/specifications/simple-repository-api.rst:13 +#, fuzzy +#| msgid "" +#| "The interface for querying available package versions and retrieving " +#| "packages from an index server comes in two forms: HTML and JSON." +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" +"Интерфейс для запроса доступных версий пакетов и получения пакетов с " +"индексного сервера представлен в двух формах: HTML и JSON." + +#: ../source/specifications/simple-repository-api.rst:21 +#, fuzzy +#| msgid "Base HTML API" +msgid "Base API" +msgstr "Базовый HTML API" + +#: ../source/specifications/simple-repository-api.rst:23 +#, fuzzy +#| 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/``." +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/``." +msgstr "" +"Репозиторий, реализующий простой API, определяется его базовым URL, это URL " +"верхнего уровня, под которым располагаются все дополнительные URL. API " +"назван \"простым\" репозиторием из-за того, что базовый URL PyPI - ``https://" +"pypi.org/simple/``." + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" +"Все последующие URL в этом документе будут относительными к этому базовому " +"URL (поэтому, учитывая URL PyPI, URL ``/foo/`` будет ``https://pypi.org/" +"simple/foo/``." + +#: ../source/specifications/simple-repository-api.rst:33 +msgid "Normalized Names" +msgstr "Нормализованные названия" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" +"Эта спецификация ссылается на концепцию \"нормализованного\" имени проекта. " +"Согласно : ссылка:спецификации нормализации имен <название - нормализация>` " +"единственными допустимыми символами в имени являются алфавит ASCII, числа " +"ASCII, ``.``, ``-`` и ``_``. Имя должно быть строчным, при этом все пробелы " +"символов ``.``, ``-`` или ``_`` должны быть заменены одним символом ``-``. " +"Это можно реализовать на языке Python с помощью модуля ``re``::" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "Версионирование простого API PyPI" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" +"Эта спецификация предлагает включение мета-тега в ответы на каждый успешный " +"запрос к простой странице API, который содержит атрибут имени " +"``pypi:repository-version`` и содержимое, которое является совместимым " +"с :ref:``спецификацией версий ` номером версии, который " +"далее ограничивается тем, что он может быть только Major.Minor, и ни одной " +"из дополнительных возможностей, поддерживаемых :ref:``спецификацией версий " +"`." + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "В итоге это будет выглядеть так:" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "При интерпретации версии репозитория:" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" +"Увеличение основной версии используется для сигнализации об изменении, " +"несовместимом с обратной стороной, когда существующие клиенты уже не смогут " +"полноценно использовать API." + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" +"Увеличение минорной версии используется для того, чтобы сигнализировать об " +"изменении обратной совместимости, так что ожидается, что существующие " +"клиенты все еще смогут полноценно использовать API." + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" +"На усмотрение любых будущих спецификаций остается вопрос о том, что именно " +"считать обратно несовместимым и совместимым изменением, помимо широкого " +"предложения о том, что существующие клиенты смогут \"осмысленно\" продолжать " +"использовать API, и это может включать добавление, модификацию или удаление " +"существующих функций." + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" +"Предполагается, что основная версия никогда не будет увеличиваться, и любые " +"будущие основные эволюции API будут использовать другой механизм для " +"эволюции API. Тем не менее, основная версия включена для того, чтобы не было " +"разночтений с будущими версиями (например, гипотетический простой api v2, " +"который жил по адресу /v2/, но который был бы запутан, если бы в репозитории-" +"версия была установлена версия >= 2)." + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "История версий API" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" +"Этот раздел содержит только сокращенную историю изменений, отмеченную " +"номером версии API. Полную историю изменений, включая изменения, сделанные " +"до появления версий API, смотрите в :ref:`History `." + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" +"Версия API 1.0: Начальная версия API, объявленная с помощью :pep:`629`." + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" +"API версии 1.1: Добавлены метаданные ``версии``, ``файлы[].размер`` и " +"``файлы[].время загрузки`` в сериализацию JSON, объявленную с " +"помощью :pep:`700``." + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" +"API версии 1.2: Добавлены метаданные репозитория \"треки\", объявленные с " +"помощью :pep:`708`." + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" +"API версии 1.3: Добавлены метаданные о происхождении, объявленные с " +"помощью :pep:`740`." + +#: ../source/specifications/simple-repository-api.rst:100 +#, fuzzy +#| msgid "" +#| "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" +"API версии 1.3: Добавлены метаданные о происхождении, объявленные с " +"помощью :pep:`740`." + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "Клиенты" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" +"Клиенты, взаимодействующие с простым API, **ОБЯЗАНЫ** проверять каждый ответ " +"на версию хранилища, и если эти данные отсутствуют, **ОБЯЗАНЫ** считать, что " +"это версия 1.0." + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" +"При столкновении с минорной версией, превышающей ожидаемую, клиенты " +"**ДОЛЖНЫ** предупреждать пользователей соответствующим сообщением." + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +#, fuzzy +#| msgid "JSON Serialization" +msgid "HTML Serialization" +msgstr "Сериализация JSON" + +#: ../source/specifications/simple-repository-api.rst:125 +#, fuzzy +#| msgid "" +#| "The following constraints apply to all JSON serialized responses " +#| "described in this spec:" +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" +"Следующие ограничения применяются ко всем сериализованным ответам JSON, " +"описанным в данной спецификации:" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +msgid "Project List" +msgstr "Список проектов" + +#: ../source/specifications/simple-repository-api.rst:135 +#, fuzzy +#| 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:" +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." +msgstr "" +"Внутри репозитория корневой URL (``/`` в данной спецификации представляет " +"собой базовый URL) **ДОЛЖЕН** быть корректной HTML5-страницей с одним " +"якорным элементом для каждого проекта в репозитории. Текст тега якоря " +"**ДОЛЖЕН** быть названием проекта, а атрибут href ** ДОЛЖЕН** ссылаться на " +"URL для этого конкретного проекта. В качестве примера:" + +#: ../source/specifications/simple-repository-api.rst:139 +#, fuzzy +#| 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:" +msgid "" +"The text of each 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 "" +"Внутри репозитория корневой URL (``/`` в данной спецификации представляет " +"собой базовый URL) **ДОЛЖЕН** быть корректной HTML5-страницей с одним " +"якорным элементом для каждого проекта в репозитории. Текст тега якоря " +"**ДОЛЖЕН** быть названием проекта, а атрибут href ** ДОЛЖЕН** ссылаться на " +"URL для этого конкретного проекта. В качестве примера:" + +#: ../source/specifications/simple-repository-api.rst:156 +#: ../source/specifications/simple-repository-api.rst:473 +msgid "Project Detail" +msgstr "Деталь проекта" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +#, fuzzy +#| msgid "" +#| "The repository **SHOULD** provide the hash of the Core Metadata file as " +#| "the ``data-core-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." +msgid "" +"Each file 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 "" +"Хранилище **ДОЛЖНО** предоставить хэш файла основных метаданных в качестве " +"значения атрибута ``data-core-metadata``, используя синтаксис " +"``=``, где ```` - это имя используемой хэш-" +"функции, а ```` - шестнадцатеричный дайджест. Хранилище **МОЖЕТ** " +"использовать ``true`` в качестве значения атрибута, если хэш недоступен." + +#: ../source/specifications/simple-repository-api.rst:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" +"В дополнение к вышесказанному, на API накладываются следующие ограничения:" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" +"Все URL-адреса, которые отвечают HTML5-страницей, **ДОЛЖНЫ** заканчиваться " +"``/``, а хранилище **ДОЛЖНО** перенаправлять URL-адреса без ``/``, чтобы " +"добавить ``/`` в конец." + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" +"URL-адреса могут быть как абсолютными, так и относительными, если они " +"указывают на правильное местоположение." + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" +"Нет никаких ограничений на то, где должны быть размещены файлы относительно " +"хранилища." + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"There may be any other HTML elements on the API pages as long as the " +"required anchor elements exist." +msgstr "" +"На страницах API могут быть любые другие HTML-элементы при условии наличия " +"необходимых элементов якоря." + +#: ../source/specifications/simple-repository-api.rst:192 +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." +msgstr "" +"Репозитории **МОГУТ** перенаправлять ненормализованные URL на канонический " +"нормализованный URL (например, ``/Foobar/`` может перенаправлять на ``/" +"foobar/``), однако клиенты **НЕ ДОЛЖНЫ** полагаться на это перенаправление и " +"**МОГУТ** запрашивать нормализованный URL." + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" +"Репозитории **ДОЛЖНЫ** выбирать хэш-функцию из числа тех, которые " +"гарантированно доступны через модуль :py:mod:`hashlib` в стандартной " +"библиотеке Python (в настоящее время это ``md5``, ```sha1``, ```sha224``, " +"```sha256``, ```sha384``, ```sha512``). В настоящее время рекомендуется " +"использовать ``sha256``." + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" +"Если существует GPG-подпись для определенного файла дистрибутива, она " +"**МОЖЕТ** находиться рядом с одноименным файлом с приставкой ``.asc``. Таким " +"образом, если файл ``/пакеты/HolyGrail-1.0.tar.gz`` существует и имеет " +"соответствующую подпись, подпись будет находиться по адресу ``/пакеты/" +"HolyGrail-1.0.tar.gz.asc``." + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" +"Хранилище **МОЖЕТ** включать атрибут ``data-core-metadata`` в ссылку на файл." + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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 "" +"Хранилище **ДОЛЖНО** предоставить хэш файла основных метаданных в качестве " +"значения атрибута ``data-core-metadata``, используя синтаксис " +"``=``, где ```` - это имя используемой хэш-" +"функции, а ```` - шестнадцатеричный дайджест. Хранилище **МОЖЕТ** " +"использовать ``true`` в качестве значения атрибута, если хэш недоступен." + +#: ../source/specifications/simple-repository-api.rst:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" +"Хранилище **МОЖЕТ** включать атрибут ``data-dist-info-metadata`` в ссылку на " +"файл." + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" +"Индексные клиенты **МОГУТ** использовать этот ключ, если он присутствует, в " +"качестве традиционного запасного варианта для ``data-core-metadata``." + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" +"``data-dist-info-metadata`` была стандартизирована в :pep:`658` и " +"переименована в ``data-core-metadata`` в :pep:`714`." + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" +"Хранилище **МОЖЕТ** включать атрибут ``data-gpg-sig`` в ссылку на файл со " +"значением ``true`` или ``false`` для указания наличия или отсутствия GPG-" +"подписи. Репозитории, которые делают это, **ДОЛЖНЫ** включать его в каждую " +"ссылку." + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" +"Репозиторий **МОЖЕТ** включать атрибут ``data-requires-python`` в ссылку на " +"файл. Он раскрывает поле метаданных :ref:`core-metadata-requires-python` для " +"соответствующего релиза. При наличии этого атрибута инструменты установки " +"**ДОЛЖНЫ** игнорировать загрузку при установке на версию Python, которая не " +"удовлетворяет этому требованию. Например:" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" +"В значении атрибута < и > должны быть закодированы в HTML как ``<`` и " +"``>``, соответственно." + +#: ../source/specifications/simple-repository-api.rst:245 +#, fuzzy +#| msgid "" +#| "A repository **MAY** include a ``data-core-metadata`` attribute on a file " +#| "link." +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" +"Хранилище **МОЖЕТ** включать атрибут ``data-core-metadata`` в ссылку на файл." + +#: ../source/specifications/simple-repository-api.rst:247 +#, fuzzy +#| 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." +msgid "" +"The ``data-yanked`` attribute 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:253 +#, fuzzy +#| 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." +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." +msgstr "" +"Значение атрибута ``данные выдернуты``, если он присутствует, представляет " +"собой произвольную строку, которая отражает причину, по которой файл был " +"выдернут. Инструменты, обрабатывающие простой API репозитория, **МОГУТ** " +"отображать эту строку для конечных пользователей." + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" +"Хранилище **МОЖЕТ** включать атрибут ``data-provenance`` в ссылку на файл. " +"Значение этого атрибута **ДОЛЖНО** представлять собой полностью определенный " +"URL, сигнализирующий о том, что информацию о происхождении файла можно найти " +"по этому URL. Этот URL **ДОЛЖЕН** представлять собой `secure origin `_." + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "Атрибут ``data-provenance`` был добавлен в API версии 1.3." + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" +"Формат связанного провенанса определен в :ref:`index-hosted-attestations`." + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "Предоставление метаданных распространения в API простого репозитория" + +#: ../source/specifications/simple-repository-api.rst:296 +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 "" +"На странице проекта простого хранилища каждый якорный тег, указывающий на " +"дистрибутив, **МОЖЕТ** содержать атрибут ``данные-дистрибутива-инфо-" +"метаданные``. Наличие этого атрибута указывает на то, что дистрибутив, " +"представленный тегом якоря, **МОЖЕТ** содержать файл метаданных Core, " +"который не будет изменен при обработке и/или установке дистрибутива." + +#: ../source/specifications/simple-repository-api.rst:302 +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." +msgstr "" +"Если атрибут ``данные-дистрибутива-инфо-метаданные`` присутствует, " +"репозиторий **ДОЛЖЕН** предоставлять файл основных метаданных дистрибутива " +"вместе с дистрибутивом с добавлением ``. метаданные`` к имени файла " +"дистрибутива. Например, Core Metadata дистрибутива, обслуживаемого по адресу " +"``/файлы/дистрибутив-1.0-py3.none.any.whl``, будет находиться по адресу ``/" +"файлы/дистрибутив-1.0-py3.none.any.whl. метаданные``. Это похоже на то, " +"как :ref:`в базовой спецификации HTML API <простой репозиторий-апи-база>` " +"указывается местоположение файла подписи GPG." + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" +"Хранилище **ДОЛЖНО** предоставить хэш файла основных метаданных в качестве " +"значения атрибута ``данные-дист-инфо-метаданные``, используя синтаксис " +"``=``, где ```` - это имя используемой хэш-" +"функции, а ```` - дайджест в шестнадцатеричном коде. Хранилище " +"**МОЖЕТ** использовать ``true`` в качестве значения атрибута, если хэш " +"недоступен." + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "Обратная совместимость" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "Простой API на основе JSON для индексов пакетов Python" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" +"Чтобы обеспечить возможность разбора ответов с помощью только стандартной " +"библиотеки, в этом документе указано, что все ответы (кроме самих файлов и " +"HTML-ответов из : ссылка:`базовой спецификации HTML API <простая репозитория-" +"api-базовая>`) должны быть сериализованы с помощью `JSON `_." + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" +"Чтобы обеспечить нулевое обнаружение конфигурации и минимизировать " +"количество дополнительных HTTP-запросов, эта спецификация расширяет : " +"ссылка:`базовую спецификацию HTML API <симпл-репозиторий-апи-база>` таким " +"образом, что все конечные точки API (кроме самих файлов) будут использовать " +"HTTP согласование содержимого, чтобы позволить клиенту и серверу выбрать " +"правильный формат сериализации для обслуживания, т.е. либо HTML, либо JSON." + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" +"Версионирование будет соответствовать : ссылка:`спецификации версий API " +"<симпл-репозиторий-апи-версионирование>` формата (``Major.Minor``), которая " +"определила существующие HTML-ответы как ``1.0``. Поскольку эта спецификация " +"не вводит новых возможностей в API, а описывает другой формат сериализации " +"для существующих возможностей, эта спецификация не изменяет существующую " +"версию ``1.0``, а вместо этого просто описывает, как сериализовать ее в JSON." + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" +"Подобно : ссылка:спецификация версионности API <симпл-репозиторий-апи-" +"версионность>`, номер основной версии **МОЖНО** увеличивать, если любые " +"изменения в новом формате приведут к тому, что существующие клиенты больше " +"не смогут понять этот формат." + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" +"Аналогично, минорная версия **МОЖЕТ** быть увеличена, если в формат " +"добавляются или удаляются функции, но ожидается, что существующие клиенты " +"будут продолжать понимать формат." + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" +"Изменения, которые не приведут к тому, что существующие клиенты не смогут " +"понять формат, и которые не представляют собой добавления или удаления " +"функций, могут происходить без изменения номера версии." + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" +"Это намеренно расплывчатая формулировка, так как в данной спецификации " +"считается, что лучше оставить это на усмотрение будущих спецификаций, " +"вносящих какие-либо изменения в API, чтобы исследовать и решить, должно ли " +"это изменение увеличивать мажорную или минорную версию." + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" +"В будущих версиях API могут быть добавлены функции, которые могут быть " +"представлены только в подмножестве доступных сериализаций данной версии. " +"Номера версий всех сериализаций в рамках одной основной версии **ДОЛЖНЫ** " +"быть синхронизированы, но специфика того, как функция сериализуется в каждом " +"формате, может отличаться, включая то, присутствует ли эта функция вообще." + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" +"Согласно этой спецификации, API следует рассматривать как конечные точки " +"URL, которые возвращают данные, интерпретация которых определяется версией " +"этих данных, а затем сериализуются в целевой формат сериализации." + +#: ../source/specifications/simple-repository-api.rst:390 +msgid "JSON Serialization" +msgstr "Сериализация JSON" + +#: ../source/specifications/simple-repository-api.rst:392 +#, fuzzy +#| 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." +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 "" +"Структура URL из : ссылка:`базовой спецификации HTML API <симпл-репозиторий-" +"апи-база>` по-прежнему применима, так как эта спецификация лишь добавляет " +"дополнительный формат сериализации для уже существующего API." + +#: ../source/specifications/simple-repository-api.rst:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" +"Следующие ограничения применяются ко всем сериализованным ответам JSON, " +"описанным в данной спецификации:" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" +"Все ответы JSON *всегда* будут представлять собой объект JSON, а не массив " +"или другой тип." + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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 "" +"Хотя JSON не поддерживает тип URL, любое значение, представляющее URL в этом " +"API, может быть как абсолютным, так и относительным, если оно указывает на " +"правильное местоположение. Если они относительные, то они относятся к " +"текущему URL, как если бы это был HTML." + +#: ../source/specifications/simple-repository-api.rst:407 +msgid "" +"Additional keys may be added to any dictionary objects in the API responses " +"and clients **MUST** ignore keys that they don't understand." +msgstr "" +"Дополнительные ключи могут быть добавлены к любым объектам словаря в ответах " +"API, и клиенты **МОГУТ** игнорировать ключи, которые они не понимают." + +#: ../source/specifications/simple-repository-api.rst:410 +msgid "" +"All JSON responses will have a ``meta`` key, which contains information " +"related to the response itself, rather than the content of the response." +msgstr "" +"Все JSON-ответы имеют ключ ``meta``, который содержит информацию, " +"относящуюся к самому ответу, а не к его содержимому." + +#: ../source/specifications/simple-repository-api.rst:413 +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 "" +"Все JSON-ответы будут содержать ключ ``meta.api-версия``, который будет " +"представлять собой строку, содержащую номер версии : ссылка:спецификация " +"версионности API <простой репозиторий-апи-версия>` ``Major.Minor``, с той же " +"семантикой fail/warn, которая определена в :ссылка:спецификация версионности " +"API <простой репозиторий-апи-версия>`." + +#: ../source/specifications/simple-repository-api.rst:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" +"Все требования : ссылка:`базовой спецификации HTML API <простой репозиторий-" +"апи-база>`, не относящиеся к HTML, остаются в силе." + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" +"Ключи (любого уровня) с ведущим символом подчеркивания зарезервированы как " +"частные для использования индексным сервером. Ни один будущий стандарт не " +"будет присваивать значение такому ключу." + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"The root URL ``/`` for this spec (which represents the base URL) will be a " +"JSON encoded dictionary which has a two keys:" +msgstr "" +"Корневой URL ``/`` для этой спецификации (который представляет собой базовый " +"URL) будет представлять собой словарь в кодировке JSON, имеющий два ключа:" + +#: ../source/specifications/simple-repository-api.rst:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" +"``meta``: Общие метаданные ответа, как `описано ранее `__." + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "В качестве примера:" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" +"Поле ``имя`` совпадает с полем из : ссылка:``базовая спецификация HTML API " +"<простой репозиторий-апи-база>``, в которой не указано, является ли оно " +"ненормализованным отображаемым именем или нормализованным. На практике " +"разные реализации этих спецификаций выбирают по-разному, так что полагаться " +"на то, что это ненормализованное или нормализованное имя, - это полагаться " +"на детали реализации данного репозитория." + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" +"Хотя ключ ``проекты`` является массивом и, следовательно, должен быть " +"расположен в определенном порядке, ни : ссылка:``базовая спецификация HTML " +"API <простой репозиторий-апи-база>``, ни эта спецификация не требуют какого-" +"либо определенного порядка, ни того, чтобы порядок был последовательным от " +"одного запроса к другому. Мысленно это лучше всего воспринимать как набор, " +"но и JSON, и HTML не имеют функциональности для создания наборов." + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" +"Формат этого URL - ``/<проект>/``, где ``<проект>`` заменяется на : " +"ссылка:``базовая спецификация HTML API <простой-репозиторий-апи-база>`` " +"нормализованное имя этого проекта, так что проект с именем \" Глупый_ход\" " +"будет иметь URL типа ``/глупый_ход/``." + +#: ../source/specifications/simple-repository-api.rst:480 +#, fuzzy +#| msgid "" +#| "This URL must respond with a JSON encoded dictionary that has four keys:" +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" +"В ответ на этот URL должен прийти словарь в кодировке JSON, состоящий из " +"четырех ключей:" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "``название``: Нормализованное имя проекта." + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +#, fuzzy +#| msgid "The ``versions`` key was added with API version 1.1." +msgid "The ``status`` key was added with API version 1.4." +msgstr "Ключ ``версии`` был добавлен в API версии 1.1." + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +#, fuzzy +#| msgid "The ``versions`` key was added with API version 1.1." +msgid "The ``reason`` key was added with API version 1.4." +msgstr "Ключ ``версии`` был добавлен в API версии 1.1." + +#: ../source/specifications/simple-repository-api.rst:505 +#, fuzzy +#| msgid "The ``versions`` key was added with API version 1.1." +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "Ключ ``версии`` был добавлен в API версии 1.1." + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" +"``файлы``: Список словарей, каждый из которых представляет отдельный файл." + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" +"``версии``: Список строк версий, определяющих все версии проекта, " +"загруженные для этого проекта. Значение ``версий`` логически является " +"множеством, и поэтому не может содержать дубликатов, а порядок версий не " +"имеет значения." + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" +"Все файлы, перечисленные в ключе ``файлы``, ДОЛЖНЫ быть связаны с одной из " +"версий в ключе ``версии``. Ключ ``версии`` МОЖЕТ содержать версии без " +"ассоциированных файлов (для представления версий без загруженных файлов, " +"если сервер имеет такую концепцию)." + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" +"Поскольку серверы могут содержать \"устаревшие\" данные, полученные до " +"принятия :ref:`the version specifiers specification (VSS) `, в настоящее время нельзя требовать, чтобы строки версий были " +"действительными версиями VSS, и поэтому нельзя считать, что они могут быть " +"упорядочены с использованием правил VSS. Тем не менее, серверы **ДОЛЖНЫ** " +"использовать нормализованные версии VSS, где это возможно." + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "Ключ ``версии`` был добавлен в API версии 1.1." + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "Каждый отдельный словарь файлов имеет следующие ключи:" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "``имя файла``: Имя представляемого файла." + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "``url``: URL, с которого может быть получен файл." + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" +"``хэши``: Словарь, отображающий имя хэша на шестнадцатеричный дайджест " +"файла. Можно включить несколько хэшей, и клиент сам решает, что делать с " +"несколькими хэшами (он может подтвердить все из них или их подмножество, или " +"вообще ничего). Имена хэшей **ОБЯЗАТЕЛЬНО** всегда должны быть приведены к " +"нижнему регистру." + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" +"По умолчанию в качестве ключа для словаря хэшей может использоваться любой " +"алгоритм, доступный через :py:mod:`hashlib` (в частности, все, которые могут " +"быть переданы в :py:func:`hashlib.new()` и не требуют дополнительных " +"параметров). По крайней мере один безопасный алгоритм из :py: " +"данные:`hashlib. алгоритмы_гарантированные` **ОБЯЗАТЕЛЬНО** всегда должен " +"быть включен. На момент создания данной спецификации рекомендуется " +"использовать ``sha256``." + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" +"``requires-python``: **опциональный** ключ, который раскрывает поле " +"метаданных : ссылка:`core-metadata-requires-python`. При наличии этого поля " +"инструменты установки **ДОЛЖНЫ** игнорировать загрузку при установке на " +"версию Python, которая не удовлетворяет этому требованию." + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" +"В отличие от ``данные-запросы-python`` в : ссылка:``базовая спецификация " +"HTML API ``, ключ ``запросы-python`` не требует " +"никакого специального экранирования, кроме того, что JSON делает естественно." + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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 "" +"``core-metadata``: **опциональный** ключ, указывающий, что метаданные для " +"этого файла доступны в том же месте, которое указано в :ref:спецификации " +"файла метаданных API ` " +"(``{file_url}.metadata``). Там, где он присутствует, он **МОЖЕТ** быть либо " +"булевым значением, указывающим, есть ли у файла связанный файл метаданных, " +"либо словарем, отображающим имена хэшей на шестнадцатеричный дайджест хэша " +"метаданных." + +#: ../source/specifications/simple-repository-api.rst:568 +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." +msgstr "" +"Если это словарь хэшей, а не булевых значений, то все те же требования и " +"рекомендации, что и для ключа ``хэши``, справедливы и для этого ключа." + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" +"Если этот ключ отсутствует, то файл метаданных может существовать, а может и " +"не существовать. Если значение ключа истинно, то файл метаданных " +"присутствует, а если ложно, то нет." + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" +"Рекомендуется, чтобы серверы по возможности предоставляли хэши файлов " +"метаданных." + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" +"``dist-info-metadata``: **опциональный**, устаревший псевдоним для ``core-" +"metadata``." + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" +"Индексные клиенты **МОГУТ** использовать этот ключ, если он присутствует, в " +"качестве традиционного запасного варианта для ``ядра-метаданных``." + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" +"``dist-info-metadata`` был стандартизирован в :pep:`658` и переименован в " +"``core-metadata`` в :pep:`714`." + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" +"``gpg-sig``: **опциональный** ключ, который представляет собой булево " +"значение, указывающее, есть ли у файла связанная с ним подпись GPG или нет. " +"URL для файла подписи соответствует тому, что указано в : ссылка:``базовой " +"спецификации HTML API <простой репозиторий-апи-база>`` (``{файл_url}.asc``). " +"Если этот ключ не существует, то подпись может существовать, а может и не " +"существовать." + +#: ../source/specifications/simple-repository-api.rst:595 +#, fuzzy +#| 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 `." +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\"." +msgstr "" +"``yanked``: **опциональный** ключ, который может быть либо булевым " +"значением, указывающим, был ли файл выдернут, либо непустой, но произвольной " +"строкой, указывающей, что файл был выдернут по определенной причине. Если " +"ключ ``yanked`` присутствует и является истинным значением, то он **ДОЛЖЕН** " +"интерпретироваться как указание на то, что файл, на который указывает поле " +"``url``, был \"Yanked\" согласно : ссылка:спецификации API yank <простой " +"репозиторий-апи-yank>`." + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" +"``размер``: **обязательный** ключ. Он **ДОЛЖЕН** содержать целое число, " +"которое представляет собой размер файла в байтах." + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "Ключ ``размер`` был добавлен в API версии 1.1." + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" +"``время загрузки``: **опциональный** ключ, который, если присутствует, " +"**ДОЛЖЕН** содержать действительную строку даты/времени ISO 8601 в формате " +"``yyyy-mm-ddThh:mm:ss.ffffffZ``, которая представляет время, когда файл был " +"загружен в индекс." + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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 "" +"Как указывает суффикс ``Z'', время загрузки **МОЖНО** использовать часовой " +"пояс UTC. Дробная секундная часть временной метки (часть ``.ffffff``) " +"необязательна, и если она присутствует, то может содержать до 6 цифр " +"точности. Если сервер не записывает информацию о времени загрузки файла, он " +"**МОЖЕТ** опустить ключ ``upload-time``." + +#: ../source/specifications/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "Ключ ``время загрузки`` был добавлен в API версии 1.1." + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" +"``provenance``: **опциональный** ключ, который, если присутствует, " +"**ДОЛЖЕН** быть либо строкой JSON, либо ``null``. Если не ``null``, то " +"**ДОЛЖЕН** быть URL-адресом связанного с файлом провенанса, по тем же " +"правилам, что и ``data-provenance`` в спецификации HTML API ` в :ref:`base HTML API`." + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "Поле ``provenance`` было добавлено в API версии 1.3." + +#: ../source/specifications/simple-repository-api.rst:670 +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 "" +"Хотя ключ ``файлы`` является массивом и, следовательно, должен быть " +"расположен в определенном порядке, ни : ссылка:``базовая спецификация HTML " +"API <простой репозиторий-апи-база>``, ни эта спецификация не требуют какого-" +"либо определенного порядка, а также того, чтобы порядок был последовательным " +"от одного запроса к другому. Мысленно это лучше всего воспринимать как " +"набор, но и JSON, и HTML не имеют функциональности для создания наборов." + +#: ../source/specifications/simple-repository-api.rst:679 +msgid "Content-Types" +msgstr "Контент-Типы" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" +"В этой спецификации предлагается, чтобы все ответы от простого API имели " +"стандартный тип содержимого, который описывает, что представляет собой ответ " +"(ответ простого API), какую версию API он представляет и какой формат " +"сериализации был использован." + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "Структура этого типа содержимого будет следующей:" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" +"Поскольку только основные версии должны быть опасны для клиентов, пытающихся " +"понять один из этих ответов API, только основная версия будет включена в тип " +"содержимого и будет снабжена префиксом ``v``, чтобы пояснить, что это номер " +"версии." + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" +"Это означает, что для существующего API 1.0 типы содержимого будут такими:" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "**JSON:** ``приложение/vnd.pypi. простой.v1+json``" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "**HTML:** ``приложение/vnd.pypi. простой.v1+html``" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" +"В дополнение к вышесказанному поддерживается специальная \"мета\" версия под " +"названием ``последний``, цель которой - позволить клиентам запрашивать " +"абсолютно последнюю версию, без необходимости заранее знать, что это за " +"версия. Рекомендуется, однако, чтобы клиенты четко указывали, какие версии " +"они поддерживают." + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" +"Для поддержки существующих клиентов, которые ожидают, что существующие : " +"ссылка:`базовая спецификация HTML API <простой репозиторий-апи-база>` ответы " +"API будут использовать тип содержимого ``текст/html``, эта спецификация " +"далее определяет ``текст/html`` как псевдоним для типа содержимого " +"``приложение/vnd.pypi. простой.v1+html``." + +#: ../source/specifications/simple-repository-api.rst:713 +msgid "Version + Format Selection" +msgstr "Выбор версии + формата" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" +"Теперь, когда существует множество возможных сериализаций, нам нужен " +"механизм, позволяющий клиентам указывать, какие форматы сериализации они " +"способны понимать. Кроме того, было бы полезно, если бы любая возможная " +"новая основная версия API могла быть добавлена без нарушения работы " +"существующих клиентов, ожидающих предыдущую версию API." + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" +"Чтобы сделать это, данная спецификация стандартизирует использование HTTP " +"`Серверного согласования содержимого` (Server-Driven Content Negotiation) " +"`_." + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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 "" +"Клиент отправляет HTTP-запрос, содержащий заголовок ``Принять``, в котором " +"перечислены все типы содержимого версии+формата, которые он способен понять." + +#: ../source/specifications/simple-repository-api.rst:728 +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: */*``)." +msgstr "" +"Сервер проверяет этот заголовок, выбирает один из перечисленных типов " +"содержимого, затем возвращает ответ, используя этот тип содержимого " +"(рассматривая отсутствие заголовка ``принять`` как ``принять: */*``)." + +#: ../source/specifications/simple-repository-api.rst:731 +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 "" +"Если сервер не поддерживает ни один из типов содержимого в заголовке " +"``принять``, он может выбрать один из 3 вариантов ответа:" + +#: ../source/specifications/simple-repository-api.rst:735 +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:737 +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." +msgstr "" +"Возвращает ответ HTTP ``406 Неприемлемо``, указывающий на то, что ни один из " +"запрошенных типов содержимого не был доступен, и сервер не смог или не " +"захотел выбрать тип содержимого по умолчанию для ответа." + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"Return a HTTP ``300 Multiple Choices`` response that contains a list of all " +"of the possible responses that could have been chosen." +msgstr "" +"Возвращает ответ HTTP ``300 Множество вариантов``, содержащий список всех " +"возможных ответов, которые могли быть выбраны." + +#: ../source/specifications/simple-repository-api.rst:742 +msgid "" +"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:745 +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." +msgstr "" +"В данной спецификации не указывается, какой выбор делает сервер в отношении " +"обработки типа содержимого, который он не может вернуть, и клиенты " +"**ДОЛЖНЫ** быть готовы обрабатывать все возможные ответы тем способом, " +"который наиболее удобен для них." + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" +"Однако, поскольку не существует стандартного формата для интерпретации " +"ответа ``300 Много вариантов``, данная спецификация настоятельно не " +"рекомендует серверам использовать эту опцию, поскольку у клиентов не будет " +"возможности понять и выбрать другой тип содержимого для запроса. Кроме того, " +"маловероятно, что клиент *может* понять другой тип содержимого в любом " +"случае, так что в лучшем случае этот ответ будет рассматриваться так же, как " +"и ошибка ``406 не принято``." + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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 "" +"Эта спецификация **дополняет** требование, что если используется мета-версия " +"``latest``, сервер **ДОЛЖЕН** отвечать типом содержимого для фактической " +"версии, которая содержится в ответе (т.е. запрос ``Accept: application/" +"vnd.pypi.simple.latest+json``, который возвращает ответ ``v1.x'', должен " +"иметь ``Content-Type`` из ``application/vnd.pypi.simple.v1+json``)." + +#: ../source/specifications/simple-repository-api.rst:764 +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:768 +msgid "``$type/$subtype``" +msgstr "``$тип/$подтип``" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "``$тип/*``" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "``*/*``" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" +"Для выбора версии+формата наиболее полезным из них является ``$тип/" +"$подтип``, поскольку это единственный способ действительно указать нужную " +"версию и формат." + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" +"Это позволяет клиенту указать приоритет для конкретной записи в заголовке " +"``Принять``, добавив ``;q=``, за которым следует значение от ``0`` до ``1`` " +"включительно, содержащее до 3 десятичных цифр. При интерпретации этого " +"значения запись с более высоким качеством имеет приоритет перед записью с " +"более низким качеством, и любая запись без присутствующего качества будет по " +"умолчанию иметь качество ``1``." + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" +"Однако клиентам следует помнить, что сервер может выбрать **любой** из " +"запрошенных ими типов содержимого, независимо от их приоритета, и даже может " +"вернуть тип содержимого, который они **не* запрашивали." + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" +"Чтобы помочь клиентам определить тип содержимого ответа, который они " +"получили в результате запроса API, данная спецификация требует, чтобы " +"серверы всегда включали заголовок ``Содержание-Тип``, указывающий на тип " +"содержимого ответа. Технически это изменение несовместимо с обратными " +"требованиями, однако на практике `pip соблюдает это требование `_, так что риск реальных поломок " +"невелик." + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "Пример работы клиента может выглядеть следующим образом:" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" +"Если клиент хочет поддерживать только HTML или только JSON, то он просто " +"удалит типы контента, которые ему не нужны, из заголовка ``принять``, и " +"превратит их получение в ошибку." + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "Альтернативные механизмы переговоров" + +#: ../source/specifications/simple-repository-api.rst:859 +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 "" +"Хотя использование согласования содержимого HTTP считается стандартным " +"способом координации действий клиента и сервера для обеспечения того, чтобы " +"клиент получал понятный ему HTTP-ответ, бывают ситуации, когда этого " +"механизма может быть недостаточно. Для таких случаев в данной спецификации " +"предусмотрены альтернативные механизмы согласования, которые могут " +"*факультативно* использоваться вместо него." + +#: ../source/specifications/simple-repository-api.rst:867 +msgid "URL Parameter" +msgstr "Параметр URL" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" +"Серверы, реализующие Simple API, могут поддерживать параметр URL с именем " +"``формат``, чтобы позволить клиентам запрашивать определенную версию URL." + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" +"Значение параметра ``формат'' должно быть **одним** из допустимых типов " +"содержимого. Передача нескольких типов содержимого, подстановочных карт, " +"качественных значений и т. д. **не поддерживается." + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" +"Поддержка этого параметра необязательна, и клиенты **НЕ ДОЛЖНЫ** полагаться " +"на него при взаимодействии с API. Этот механизм согласования предназначен " +"для того, чтобы облегчить изучение API в браузере, а также для того, чтобы в " +"документации или примечаниях можно было ссылаться на конкретную " +"версию+формат." + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" +"Серверы, не поддерживающие этот параметр, могут возвращать ошибку при его " +"наличии или просто игнорировать его присутствие." + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" +"Когда сервер реализует этот параметр, он **ДОЛЖЕН** иметь приоритет над " +"любыми значениями в заголовке ``Принять`` клиента, и если сервер не " +"поддерживает запрашиваемый формат, он может вернуться к заголовку " +"``Принять`` или выбрать любое из условий ошибки, которые обычно имеет " +"стандартное согласование содержимого, управляемое сервером (например, ``406 " +"Недоступен``, ``303 Несколько вариантов`` или выбор типа по умолчанию для " +"возврата)." + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "Конфигурация конечной точки" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" +"Эта опция технически не является специальной опцией вообще, это просто " +"естественное следствие использования согласования содержимого и разрешения " +"серверам выбирать, какой из доступных типов содержимого является их типом по " +"умолчанию." + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" +"Если сервер не хочет или не может реализовать согласование содержимого, " +"управляемое сервером, и предпочитает, чтобы пользователи явно настраивали " +"свой клиент для выбора нужной им версии, то такая конфигурация " +"поддерживается." + +#: ../source/specifications/simple-repository-api.rst:903 +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 "" +"Для этого сервер должен создать несколько конечных точек (например, ``/" +"простой/v1+html/`` и/или ``/простой/v1+json/``) для каждой версии+формата, " +"которые он хочет поддерживать. Под этой конечной точкой они могут разместить " +"копию своего хранилища, которая поддерживает только один (или подмножество) " +"из типов содержимого. Когда клиент делает запрос с использованием заголовка " +"``Принять``, сервер может проигнорировать его и вернуть тип содержимого, " +"соответствующий данной конечной точке." + +#: ../source/specifications/simple-repository-api.rst:910 +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 "" +"Для клиентов, которые хотят требовать определенной конфигурации, они могут " +"отслеживать, для какой версии+формата был сконфигурирован конкретный URL " +"репозитория, и при запросе к этому серверу выдавать заголовок ``Принять``, " +"который *только* включает правильный тип содержимого." + +#: ../source/specifications/simple-repository-api.rst:918 +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." +msgstr "" +"Этот раздел не является нормативным и представляет собой то, что, по мнению " +"авторов спецификации, является наилучшими решениями по умолчанию для " +"реализации этой спецификации, но он **не** представляет собой никаких " +"требований по соответствию этим решениям." + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" +"Эти решения были выбраны для того, чтобы максимизировать количество " +"запросов, которые можно перенести на новейшую версию API, сохранив при этом " +"максимальную совместимость. Кроме того, они постарались сделать так, чтобы " +"использование API обеспечивало защитные ограждения, которые пытаются " +"подтолкнуть клиента к наилучшему выбору." + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "Рекомендуется использовать серверы:" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" +"Поддерживать все 3 типа контента, описанные в данной спецификации, используя " +"согласование контента с сервером, до тех пор, пока это возможно, или, по " +"крайней мере, пока они получают нетривиальный трафик, использующий ответы " +"HTML." + +#: ../source/specifications/simple-repository-api.rst:933 +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 "" +"При встрече с заголовком ``Принять``, который не содержит типов содержимого, " +"с которыми сервер умеет работать, сервер не должен возвращать ответ ``300 " +"Множественный выбор``, а вместо этого возвращает ответ ``406 Неприемлемо``." + +#: ../source/specifications/simple-repository-api.rst:938 +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." +msgstr "" +"Однако, если вы решили использовать конфигурацию конечной точки, вы должны " +"предпочесть возвращать ответ ``200 OK`` в ожидаемом типе содержимого для " +"данной конечной точки." + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" +"При выборе приемлемой версии сервер должен выбрать самую высокую версию, " +"которую поддерживает клиент, с наиболее выразительным/функциональным " +"форматом сериализации, принимая во внимание специфику запросов клиента, а " +"также любые значения приоритета качества, которые он выразил, и должен " +"использовать тип содержимого ``текст/html`` только в качестве последнего " +"средства." + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "Рекомендуется, чтобы клиенты:" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" +"Поддерживать все 3 типа контента, описанные в данной спецификации, используя " +"согласование контента с сервером, до тех пор, пока это возможно." + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" +"При составлении заголовка ``Принять`` включите в него все типы содержимого, " +"которые вы поддерживаете." + +#: ../source/specifications/simple-repository-api.rst:955 +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 "" +"Обычно не следует *не* включать значение приоритета качества для типов " +"содержимого, если только у вас нет конкретных причин, которые вы хотите, " +"чтобы сервер принял во внимание (например, если вы используете HTML-парсер " +"стандартной библиотеки и беспокоитесь о том, что некоторые типы HTML-ответов " +"могут быть не в состоянии разобрать в некоторых крайних случаях)." + +#: ../source/specifications/simple-repository-api.rst:961 +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." +msgstr "" +"Единственным исключением из этой рекомендации является то, что рекомендуется " +"*включать значение ``;q=0.01`` для унаследованного типа содержимого ``текст/" +"html``, если только это не единственный тип содержимого, который вы " +"запрашиваете." + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" +"Явно выбирайте версии, которые они ищут, вместо того чтобы использовать " +"``последнюю`` мета-версию во время обычной работы." + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" +"Проверьте ``Контент-Тип`` в ответе и убедитесь, что он соответствует тому, " +"что вы ожидали." + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "Сентябрь 2015 года: начальная форма формата HTML, в :pep:`503`" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "Июль 2016 г: Метаданные Требуется-Python, в обновлении :pep:`503`" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "Май 2019: поддержка \"янки\", в :pep:`592`" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" +"Июль 2020 года: Соглашение о версиях API и метаданные, а также объявление " +"формата HTML как API v1, в :pep:`629`" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" +"Май 2021: предоставление метаданных пакета независимо от пакета, в :pep:`658`" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" +"Май 2022: начальная форма формата JSON, с механизмом выбора между ними для " +"клиентов, и объявление обоих форматов как API v1, в :pep:`691`" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" +"Октябрь 2022: версии проектов, размер файлов и время загрузки в формате " +"JSON, в :pep:`700`" + +#: ../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 "" +"Июнь 2023: переименование поля, предоставляющего метаданные пакета " +"независимо от пакета, в :pep:`714`" + +#: ../source/specifications/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" +"Ноябрь 2024: метаданные о проверке в форматах HTML и JSON, в :pep:`740`" + +#: ../source/specifications/simple-repository-api.rst:990 +#, fuzzy +#| msgid "" +#| "November 2024: provenance metadata in the HTML and JSON formats, " +#| "in :pep:`740`" +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" +"Ноябрь 2024: метаданные о проверке в форматах HTML и JSON, в :pep:`740`" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "Формат распространения в исходных кодах" + +#: ../source/specifications/source-distribution-format.rst:8 +#, fuzzy +#| 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." +msgid "" +"The current standard 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/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``. Этот документ не пытается " +"стандартизировать этот формат, за исключением того, что если дистрибутив " +"унаследованного исходного кода содержит файл ``PKG-INFO``, использующий " +"метаданные версии 2.2 или более поздней, то он ДОЛЖЕН следовать правилам, " +"применимым к дистрибутивам исходного кода, определенным в спецификации " +"метаданных." + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "Дистрибутивы с исходными текстами также известны как *sdists*." + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "Деревья источников" + +#: ../source/specifications/source-distribution-format.rst:28 +#, fuzzy +#| 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." +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 used 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`, который " +"может быть использован для сборки дистрибутива исходных текстов из " +"содержащихся файлов и каталогов. :pep:`517` и :pep:`518` определяют, что " +"должно соответствовать определению того, что должен " +"содержать :file:`pyproject.toml`, чтобы что-то считалось деревом исходных " +"текстов." + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "Имя файла исходного дистрибутива" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" +"Имя файла sdist было стандартизировано в :pep:`625`. Имя файла должно иметь " +"вид ``{имя}-{версия}.tar.gz``, где ``{имя}`` нормализовано по тем же " +"правилам, что и для бинарных дистрибутивов (см. :ref:`binary-distribution-" +"format`), а ``{версия}`` - это канонизированная форма версии проекта " +"(см. :ref:`version-specifiers`)." + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" +"Компоненты имени и версии в имени файла ДОЛЖНЫ соответствовать значениям, " +"хранящимся в метаданных, содержащихся в файле." + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" +"Код, создающий дистрибутивный файл с исходным кодом, ДОЛЖЕН дать файлу имя, " +"соответствующее этой спецификации. Это включает в себя крючок " +"``build_sdist`` в :term:`build backend `." + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" +"Код, обрабатывающий файлы исходных дистрибутивов, МОЖЕТ распознать файлы " +"исходных дистрибутивов по суффиксу ``.tar.gz`` и наличию *одного* дефиса в " +"имени файла. Код, который это делает, может использовать имя дистрибутива и " +"версию из имени файла без дополнительной проверки." + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "Формат файла исходного дистрибутива" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`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) содержит один каталог " +"верхнего уровня с именем ``{имя}-{версия}`` (например, ``foo-1.0``), " +"содержащий исходные файлы пакета. Имя и версия ДОЛЖНЫ совпадать с " +"метаданными, хранящимися в файле. Этот каталог также должен " +"содержать :file:`pyproject.toml` в формате, определенном в :ref:`pyproject-" +"toml-spec`, и :file:`PKG-INFO` файл, содержащий метаданные в формате, " +"описанном в спецификации :ref:`core-metadata`. Метаданные ДОЛЖНЫ " +"соответствовать, по крайней мере, версии 2.2 спецификации метаданных." + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" +"Если версия метаданных 2.4 или выше, исходный дистрибутив ДОЛЖЕН содержать " +"все файлы лицензий, указанные в поле ``License-File`` в :file:`PKG-INFO`` по " +"соответствующим путям относительно корневого каталога sdist " +"(содержащего :file:`pyproject.toml`` и метаданные :file:`PKG-INFO``)." + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" +"Никакое другое содержимое sdist не требуется и не определено. Системы сборки " +"могут хранить в sdist любую информацию, необходимую им для сборки проекта." + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" +"В Таровом шарике должен использоваться современный формат POSIX.1-2001 pax " +"tar, который определяет имена файлов в формате UTF-8. В частности, файлы " +"исходных дистрибутивов должны быть читаемы с помощью модуля tarfile " +"стандартной библиотеки с флагом open 'r:gz'." + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "Возможности архива распространения исходных текстов" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"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/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "Распаковка с помощью фильтра данных" + +#: ../source/specifications/source-distribution-format.rst:93 +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/source-distribution-format.rst:97 +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 "" +"В качестве исключения, в интерпретаторах Python " +"без :py:func:`hasattr(tarfile, 'data_filter') ` " +"(:pep:`706`), инструменты, которые обычно используют этот фильтр (прямо или " +"косвенно), МОГУТ предупредить пользователя и проигнорировать эту " +"спецификацию. Компромисс между удобством использования (например, полное " +"доверие к архиву) и безопасностью (например, отказ от распаковки) в этом " +"случае остается на усмотрение инструмента." + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "Распаковка без фильтра данных" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" +"Инструменты, которые не используют фильтр ``data`` напрямую (например, для " +"обратной совместимости, предоставления дополнительных возможностей или не " +"использующие Python), ДОЛЖНЫ следовать этому разделу. (На момент написания " +"этой статьи фильтр ``data`` также следует этому разделу, но в будущем они " +"могут рассинхронизироваться)" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" +"Следующие файлы недействительны в архиве *sdist*. При обнаружении такой " +"записи инструменты ДОЛЖНЫ уведомить пользователя, НЕ ДОЛЖНЫ распаковывать " +"запись и МОГУТ прервать работу с ошибкой:" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "Файлы, которые будут размещены за пределами каталога назначения." + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" +"Ссылки (символические или жесткие), указывающие за пределы целевого каталога." + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "Файлы устройств (включая pipes)." + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" +"Следующие также недействительны. Инструменты МОГУТ обрабатывать их, как " +"указано выше, но НЕ ОБЯЗАНЫ это делать:" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "Файлы с компонентом ``...`` в имени файла или цели ссылки." + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "Ссылки, указывающие на файл, который не является частью архива." + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" +"Инструменты MAY распаковывают ссылки (символические или жесткие) как обычные " +"файлы, используя содержимое архива." + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "При извлечении архивов *sdist*:" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" +"Ведущие косые черты в именах файлов ДОЛЖНЫ быть опущены. (В настоящее время " +"это стандартное поведение для распаковки ``tar``)" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "Для каждого бита ``мода`` (разрешения Unix) инструменты ДОЛЖНЫ либо:" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" +"использовать значение платформы по умолчанию для нового файла/каталога " +"(соответственно)," + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "установить бит в соответствии с архивом, или" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"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/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "Старшие биты ``режима'' (setuid, setgid, sticky) ДОЛЖНЫ быть очищены." + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "РЕКОМЕНДУЕТСЯ сохранять пользовательский *исполняемый* бит." + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "Дополнительные подсказки" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" +"Авторам инструментов рекомендуется рассмотреть, насколько *подсказки для " +"дальнейшей проверки* в документации к ``tarfile`` применимы к их инструменту." + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" +"Ноябрь 2020 года: Первоначальная версия этой спецификации была одобрена " +"через :pep:`643`." + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "Июль 2021 года: Определено, что такое дерево источников." + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" +"Сентябрь 2022: Имя файла исходного дистрибутива было стандартизировано " +"через :pep:`625`." + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" +"Август 2023 года: Функции архива дистрибутива исходных текстов были " +"стандартизированы с помощью :pep:`721`." + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" +"Декабрь 2024 года: Включение файлов лицензий в дистрибутив исходных текстов " +"было стандартизировано с помощью :pep:`639`." + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "Спецификаторы версии" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" +"Эта спецификация описывает схему идентификации версий программных " +"дистрибутивов Python и объявления зависимостей от конкретных версий." + +#: ../source/specifications/version-specifiers.rst:15 +msgid "Definitions" +msgstr "Определение" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +msgstr "" +"Ключевые слова \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL " +"NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\" и \"OPTIONAL\" в " +"этом документе должны интерпретироваться так, как описано в :rfc:`2119`." + +#: ../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." +msgstr "" +"\"Инструменты сборки\" - это автоматизированные инструменты, предназначенные " +"для работы в системах разработки и создающие архивы исходных текстов и " +"бинарных дистрибутивов. Инструменты сборки также могут вызываться средствами " +"интеграции для сборки программного обеспечения, распространяемого в виде " +"sdists, а не предварительно собранных бинарных архивов." + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" +"\"Индексные серверы\" - это активные реестры распространения, которые " +"публикуют метаданные о версиях и зависимостях и накладывают ограничения на " +"разрешенные метаданные." + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" +"\"Инструменты публикации\" - это автоматизированные инструменты, " +"предназначенные для запуска на системах разработки и загрузки архивов " +"исходных и бинарных дистрибутивов на индексные серверы." + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" +"\"Инструменты установки\" - это инструменты интеграции, специально " +"предназначенные для запуска на объектах развертывания, потребляющие исходные " +"и двоичные архивы дистрибутивов с индексного сервера или другого указанного " +"места и развертывающие их на целевой системе." + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" +"\"Автоматизированные инструменты\" - это собирательный термин, охватывающий " +"инструменты сборки, индексные серверы, инструменты публикации, инструменты " +"интеграции и любое другое программное обеспечение, которое производит или " +"потребляет метаданные о версиях и зависимостях дистрибутива." + +#: ../source/specifications/version-specifiers.rst:43 +msgid "Version scheme" +msgstr "Схема версии" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" +"Дистрибутивы идентифицируются общедоступным идентификатором версии, который " +"поддерживает все определенные операции сравнения версий" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" +"Схема версий используется как для описания версии дистрибутива, " +"предоставляемого конкретным архивом дистрибутива, так и для наложения " +"ограничений на версии зависимостей, необходимых для сборки или запуска " +"программного обеспечения." + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "Идентификаторы общедоступных версий" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" +"Канонические идентификаторы публичных версий ДОЛЖНЫ соответствовать " +"следующей схеме::" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" +"Идентификаторы общедоступных версий НЕ ДОЛЖНЫ содержать ведущие или " +"завершающие пробельные символы." + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" +"Идентификаторы публичных версий ДОЛЖНЫ быть уникальными в пределах одного " +"дистрибутива." + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" +"Средства установки ДОЛЖНЫ игнорировать любые публичные версии, которые не " +"соответствуют этой схеме, но также ДОЛЖНЫ включать нормализации, указанные " +"ниже. Средства установки МОГУТ предупреждать пользователя при обнаружении " +"несоответствующих или неоднозначных версий." + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" +"См. также :ref:`version-specifiers-regex`, который предоставляет регулярное " +"выражение для проверки строгого соответствия каноническому формату, а также " +"более свободное регулярное выражение, принимающее входные данные, которые " +"могут потребовать последующей нормализации." + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "Идентификаторы публичных версий разделяются на пять сегментов:" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "Эпохальный сегмент: ``N!``" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "Сегмент выпуска: ``N(.N)*``" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "Предрелизный сегмент: ``{a|b|rc}N``" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "Пост-релизный сегмент: ``.postN``" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "Сегмент релиза разработки: ``.devN``" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" +"Любой конкретный релиз может быть \"финальным релизом\", \"предварительным " +"релизом\", \"пост-релизом\" или \"девелоперским релизом\", как определено в " +"следующих разделах." + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" +"Все числовые компоненты ДОЛЖНЫ быть неотрицательными целыми числами, " +"представленными в виде последовательностей цифр ASCII." + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" +"Все числовые компоненты ДОЛЖНЫ интерпретироваться и упорядочиваться в " +"соответствии с их числовым значением, а не как текстовые строки." + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" +"Все числовые компоненты МОГУТ быть нулевыми. За исключением случаев, " +"описанных ниже для сегмента выпуска, числовой компонент, равный нулю, не " +"имеет особого значения, кроме того, что всегда является наименьшим возможным " +"значением при упорядочивании версий." + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" +"Эта схема допускает использование некоторых трудночитаемых идентификаторов " +"версий, чтобы лучше приспособиться к широкому спектру практик " +"версионирования в существующих общественных и частных проектах Python." + +#: ../source/specifications/version-specifiers.rst:105 +msgid "" +"Accordingly, some of the versioning practices which are technically " +"permitted by the specification are strongly discouraged for new projects. " +"Where this is the case, the relevant details are noted in the following " +"sections." +msgstr "" +"Соответственно, некоторые методы версионирования, которые технически " +"разрешены спецификацией, настоятельно не рекомендуются для новых проектов. " +"Если это так, то соответствующие детали указаны в следующих разделах." + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" +"Локальные идентификаторы версий ДОЛЖНЫ соответствовать следующей схеме::" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" +"Они состоят из обычного идентификатора публичной версии (как определено в " +"предыдущем разделе), а также произвольной \"метки локальной версии\", " +"отделенной от идентификатора публичной версии плюсом. Локальные метки версий " +"не имеют специфической семантики, но на них накладываются некоторые " +"синтаксические ограничения." + +#: ../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 "" +"Идентификаторы локальных версий используются для обозначения полностью " +"совместимых с API (и, если применимо, ABI) исправленных версий проектов " +"upstream. Например, они могут быть созданы разработчиками приложений и " +"системными интеграторами путем применения специфических исправлений, когда " +"обновление до нового релиза upstream будет слишком разрушительным для " +"приложения или другой интегрированной системы (например, дистрибутива Linux)." + +#: ../source/specifications/version-specifiers.rst:132 +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." +msgstr "" +"Включение метки локальной версии позволяет отличить релизы восходящего " +"потока от потенциально измененных перестроек, сделанных интеграторами " +"нисходящего потока. Использование идентификатора локальной версии не влияет " +"на вид релиза, но при применении к дистрибутиву исходного кода указывает на " +"то, что он может содержать не совсем тот же код, что и соответствующий релиз " +"восходящего потока." + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" +"Чтобы идентификаторы локальных версий могли быть легко включены в имена " +"файлов и URL-адреса, а также чтобы избежать несоответствий в форматировании " +"шестнадцатеричных хэш-представлений, метки локальных версий ДОЛЖНЫ быть " +"ограничены следующим набором разрешенных символов:" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "Буквы ASCII (``[a-zA-Z]``)" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "Цифры ASCII (``[0-9]``)" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "периоды (``.``)" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" +"Метки локальных версий ДОЛЖНЫ начинаться и заканчиваться буквой или цифрой " +"ASCII." + +#: ../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 "" +"При сравнении и упорядочивании локальных версий каждый сегмент локальной " +"версии (разделенный символом ``.``) рассматривается отдельно. Если сегмент " +"полностью состоит из ASCII-цифр, то для целей сравнения этот сегмент следует " +"считать целым числом, а если сегмент содержит какие-либо ASCII-буквы, то " +"этот сегмент сравнивается лексикографически с нечувствительностью к " +"регистру. При сравнении числового и лексикографического сегментов числовой " +"сегмент всегда сравнивается как больший, чем лексикографический. Кроме того, " +"локальная версия с большим количеством сегментов всегда будет сравниваться " +"как большая, чем локальная версия с меньшим количеством сегментов, при " +"условии, что более короткие сегменты локальной версии точно совпадают с " +"началом более длинных сегментов локальной версии." + +#: ../source/specifications/version-specifiers.rst:160 +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." +msgstr "" +"Восходящий проект\" - это проект, который определяет свои собственные " +"публичные версии. Проект \"downstream\" - это проект, который отслеживает и " +"распространяет проект \"upstream\", потенциально перенося исправления " +"безопасности и ошибок из более поздних версий проекта \"upstream\"." + +#: ../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 "" +"Локальные идентификаторы версий НЕ ДОЛЖНЫ использоваться при публикации " +"восходящих проектов на публичном индексном сервере, но МОГУТ использоваться " +"для идентификации частных сборок, созданных непосредственно из источника " +"проекта. Идентификаторы локальных версий ДОЛЖНЫ использоваться нижестоящими " +"проектами при выпуске версии, которая совместима по API с версией " +"вышестоящего проекта, идентифицируемой идентификатором публичной версии, но " +"содержит дополнительные изменения (например, исправления ошибок). Поскольку " +"Python Package Index предназначен исключительно для индексирования и " +"размещения upstream-проектов, он НЕ ДОЛЖЕН разрешать использование локальных " +"идентификаторов версий." + +#: ../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`)." +msgstr "" +"Исходные дистрибутивы, использующие локальный идентификатор версии, ДОЛЖНЫ " +"предоставлять метаданные расширения ``python.integrator`` (как определено " +"в :pep:`459`)." + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "Финальные релизы" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" +"Идентификатор версии, состоящий только из сегмента выпуска и, опционально, " +"идентификатора эпохи, называется \"финальным выпуском\"." + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" +"Сегмент освобождения состоит из одного или нескольких неотрицательных целых " +"значений, разделенных точками::" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" +"Финальные релизы в рамках проекта ДОЛЖНЫ иметь последовательно возрастающую " +"нумерацию, иначе автоматизированные инструменты не смогут правильно их " +"обновить." + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" +"Хотя по этой схеме допускается любое количество дополнительных компонентов " +"после первого, наиболее распространенными вариантами являются использование " +"двух компонентов (\"major.minor\") или трех компонентов " +"(\"major.minor.micro\")." + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "Например::" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" +"Серия релизов - это любой набор номеров финальных релизов, которые " +"начинаются с общего префикса. Например, ``3.3.1``, ``3.3.5`` и ``3.3.9.45`` " +"являются частью серии релизов ``3.3``." + +#: ../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." +msgstr "" +"``X.Y`` и ``X.Y.0`` не считаются отдельными номерами релизов, поскольку " +"правила сравнения сегментов релизов неявно расширяют двухкомпонентную форму " +"до ``X.Y.0``, когда сравнивают ее с любым сегментом релиза, включающим три " +"компонента." + +#: ../source/specifications/version-specifiers.rst:229 +#, fuzzy +#| msgid "" +#| "Date based release segments are also permitted. An example of a date " +#| "based release scheme using the year and month of the release::" +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:243 +msgid "Pre-releases" +msgstr "Предварительные выпуски" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" +"Если эти предварительные версии используются как часть цикла разработки " +"проекта, они обозначаются включением сегмента pre-release в идентификатор " +"версии::" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" +"Идентификатор версии, состоящий только из сегмента релиза и сегмента " +"предрелиза, называется \"предрелизом\"." + +#: ../source/specifications/version-specifiers.rst:259 +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 "" +"Сегмент предрелиза состоит из алфавитного идентификатора фазы предрелиза и " +"неотрицательного целочисленного значения. Предварительные выпуски для " +"данного выпуска упорядочиваются сначала по фазе (альфа, бета, кандидат на " +"выпуск), а затем по числовому компоненту в рамках этой фазы." + +#: ../source/specifications/version-specifiers.rst:264 +msgid "" +"Installation tools MAY accept both ``c`` and ``rc`` releases for a common " +"release segment in order to handle some existing legacy distributions." +msgstr "" +"Утилиты установки МОГУТ принимать выпуски ``c`` и ``rc`` для общего сегмента " +"выпуска, чтобы работать с некоторыми существующими устаревшими " +"дистрибутивами." + +#: ../source/specifications/version-specifiers.rst:267 +msgid "" +"Installation tools SHOULD interpret ``c`` versions as being equivalent to " +"``rc`` versions (that is, ``c1`` indicates the same version as ``rc1``)." +msgstr "" +"Утилиты установки ДОЛЖНЫ интерпретировать версии ``c`` как эквивалентные " +"версиям ``rc`` (то есть, ``c1`` означает ту же версию, что и ``rc1``)." + +#: ../source/specifications/version-specifiers.rst:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" +"Средства сборки, средства публикации и индексные серверы ДОЛЖНЫ запрещать " +"создание релизов ``rc`` и ``c`` для общего сегмента релиза." + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "Пост-релизы" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" +"Некоторые проекты используют пост-релизы для устранения мелких ошибок в " +"финальном релизе, которые не влияют на распространяемое ПО (например, " +"исправление ошибки в примечаниях к релизу)." + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" +"Если эти пост-релизы используются в рамках цикла разработки проекта, они " +"обозначаются включением сегмента post-release в идентификатор версии::" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" +"Идентификатор версии, включающий сегмент пост-релиза без сегмента релиза " +"разработки, называется \"пост-релизом\"." + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" +"Сегмент пост-релиза состоит из строки ``.post``, за которой следует целое " +"неотрицательное значение. Пост-релизы упорядочиваются по их числовой " +"составляющей, сразу после соответствующего релиза и перед любым последующим " +"релизом." + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "Пост-релизы также разрешены для пре-релизов::" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" +"Настоятельно не рекомендуется создавать пост-релизы из пре-релизов, так как " +"это затрудняет разбор идентификатора версии для человека. В целом, гораздо " +"понятнее просто создать новый пререлиз, увеличив числовой компонент." + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "Развивающие релизы" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" +"Некоторые проекты регулярно выпускают новые релизы, и разработчики системных " +"пакетов (особенно для дистрибутивов Linux) могут захотеть создавать ранние " +"релизы непосредственно из системы контроля исходных кодов, которые не будут " +"конфликтовать с более поздними релизами проекта." + +#: ../source/specifications/version-specifiers.rst:323 +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 "" +"Если они используются как часть цикла разработки проекта, то эти релизы " +"указываются путем включения сегмента developmental release в идентификатор " +"версии::" + +#: ../source/specifications/version-specifiers.rst:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" +"Идентификатор версии, включающий сегмент выпуска разработки, называется " +"\"выпуском разработки\"." + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" +"Сегмент релиза разработки состоит из строки ``.dev``, за которой следует " +"целое неотрицательное значение. Релизы разработки упорядочиваются по их " +"числовой составляющей, непосредственно перед соответствующим релизом (и " +"перед любыми предшествующими релизами с тем же сегментом релиза) и после " +"любого предыдущего релиза (включая любые пост-релизы)." + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" +"Релизы разработки также разрешены для предварительных и последующих релизов::" + +#: ../source/specifications/version-specifiers.rst:346 +#, fuzzy +#| msgid "" +#| "Developmental releases are also permitted for pre-releases and post-" +#| "releases::" +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" +"Релизы разработки также разрешены для предварительных и последующих релизов::" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" +"Хотя они могут быть полезны для целей непрерывной интеграции, публикация " +"предварительных релизов разработки на общедоступных индексных серверах " +"крайне не рекомендуется, так как это затрудняет разбор идентификатора версии " +"для человека. Если такой релиз необходимо опубликовать, гораздо понятнее " +"вместо этого создать новый предварительный релиз, увеличив числовой " +"компонент." + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" +"Также настоятельно не рекомендуется использовать пост-релизы для разработки, " +"но они могут быть уместны в проектах, которые используют нотацию post-" +"release для полных релизов сопровождения, которые могут включать изменения " +"кода." + +#: ../source/specifications/version-specifiers.rst:364 +msgid "Version epochs" +msgstr "Эпохи версий" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" +"Если он включен в идентификатор версии, то эпоха появляется перед всеми " +"остальными компонентами и отделяется от сегмента релиза восклицательным " +"знаком::" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "Если явная эпоха не указана, то неявной эпохой будет ``0``." + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" +"Большинство идентификаторов версий не будут включать эпоху, поскольку явная " +"эпоха нужна только в том случае, если проект *изменяет* способ обработки " +"нумерации версий таким образом, что обычные правила упорядочивания версий " +"дают неверный ответ. Например, если проект использует версии, основанные на " +"дате, такие как ``2014.04``, и хочет перейти на семантические версии, такие " +"как ``1.0``, то новые релизы будут идентифицироваться как *более старые*, " +"чем версии, основанные на дате, при использовании обычной схемы сортировки::" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" +"Однако, указав явную эпоху, можно соответствующим образом изменить порядок " +"сортировки: все версии, относящиеся к более поздней эпохе, будут " +"отсортированы после версий, относящихся к более ранней эпохе::" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +msgid "Normalization" +msgstr "Нормализация" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" +"Для обеспечения лучшей совместимости с существующими версиями существует ряд " +"\"альтернативных\" синтаксисов, которые ДОЛЖНЫ быть учтены при разборе " +"версий. Эти синтаксисы ДОЛЖНЫ учитываться при разборе версии, однако они " +"должны быть \"нормализованы\" к стандартному синтаксису, определенному выше." + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "Чувствительность случая" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" +"Все буквы ascii должны интерпретироваться без учета регистра в пределах " +"версии, и нормальной формой является строчный регистр. Это позволяет " +"использовать такие версии, как ``1.1RC1``, которые будут нормализованы до " +"``1.1rc1``." + +#: ../source/specifications/version-specifiers.rst:433 +msgid "Integer Normalization" +msgstr "Нормализация целого числа" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" +"Все целые числа интерпретируются с помощью встроенной функции ``int()`` и " +"нормализуются к строковой форме вывода. Это означает, что целочисленная " +"версия ``00`` будет нормализована до ``0``, а ``09000`` - до ``9000``. Это " +"не относится к целым числам внутри буквенно-цифрового сегмента локальной " +"версии, например ``1.0+foo0100``, которая уже находится в нормализованной " +"форме." + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "Сепараторы перед выпуском" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" +"Предварительные выпуски должны допускать разделитель ``.``, ``-`` или ``_`` " +"между сегментом выпуска и сегментом предварительных выпусков. Нормальная " +"форма для этого - без разделителя. Это позволяет использовать такие версии, " +"как ``1.1.a1`` или ``1.1-a1``, которые будут нормализованы до ``1.1a1``. " +"Также следует разрешить использовать разделитель между обозначением pre-" +"release и цифрой. Это позволяет использовать такие версии, как ``1.0a.1``, " +"которые будут нормализованы до ``1.0a1``." + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "Предварительное написание" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" +"В предварительных версиях допускаются дополнительные написания ``alpha``, " +"``beta``, ``c``, ``pre`` и ``preview`` для ``a``, ``b``, ``rc``, ``rc`` и " +"``rc`` соответственно. Это позволяет использовать такие версии, как " +"``1.1alpha1``, ``1.1beta2`` или ``1.1c3``, которые нормализуются до " +"``1.1a1``, ``1.1b2`` и ``1.1rc3``. В каждом случае дополнительные написания " +"следует считать эквивалентными их нормальным формам." + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "Неявный номер предварительного выпуска" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" +"В предыдущих версиях допускается опускать цифру, в этом случае она неявно " +"принимается за ``0``. Нормальной формой для этого является явное указание " +"``0``. Это позволяет использовать такие версии, как ``1.2a``, которые " +"нормализуются до ``1.2a0``." + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "Сепараторы после выпуска" + +#: ../source/specifications/version-specifiers.rst:475 +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 "" +"В релизах Post допускается использование разделителя ``.``, ``-`` или ``_``, " +"а также полное отсутствие разделителя. Обычная форма - с разделителем ``.``. " +"Это позволяет использовать такие версии, как ``1.2-post2`` или ``1.2post2``, " +"которые нормализуются до ``1.2.post2``. Как и в случае с предрелизным " +"разделителем, здесь также допускается необязательный разделитель между " +"обозначением пострелиза и цифрой. Это позволяет использовать версии типа " +"``1.2.post-2``, которые нормализуются до ``1.2.post2``." + +#: ../source/specifications/version-specifiers.rst:484 +msgid "Post release spelling" +msgstr "Написание после выпуска" + +#: ../source/specifications/version-specifiers.rst:486 +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 "" +"Пост-релизы допускают дополнительные написания ``rev`` и ``r``. Это " +"позволяет использовать такие версии, как ``1.0-r4``, которые нормализуются " +"до ``1.0.post4``. Как и в предыдущих версиях, дополнительные написания " +"следует считать эквивалентными их нормальным формам." + +#: ../source/specifications/version-specifiers.rst:493 +msgid "Implicit post release number" +msgstr "Неявный номер после выпуска" + +#: ../source/specifications/version-specifiers.rst:495 +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 "" +"Пост-релизы позволяют опускать цифру, в этом случае она неявно принимается " +"за ``0``. Нормальной формой для этого является явное указание ``0``. Это " +"позволяет использовать такие версии, как ``1.2.post``, которые нормализуются " +"до ``1.2.post0``." + +#: ../source/specifications/version-specifiers.rst:501 +msgid "Implicit post releases" +msgstr "Неявные пост-релизы" + +#: ../source/specifications/version-specifiers.rst:503 +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 "" +"Релизы Post позволяют полностью отказаться от обозначения ``post``. При " +"использовании этой формы разделитель ДОЛЖЕН быть ``-`` и никакая другая " +"форма не допускается. Это позволяет нормализовать такие версии, как " +"``1.0-1``, до ``1.0.post1``. Эта конкретная нормализация НЕ ДОЛЖНА " +"использоваться в сочетании с правилом неявного номера релиза. Другими " +"словами, ``1.0-`` - это *не* допустимая версия, и она *не* нормализуется до " +"``1.0.post0``." + +#: ../source/specifications/version-specifiers.rst:512 +msgid "Development release separators" +msgstr "Сепараторы для выпуска продукции" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" +"В релизах разработки допускается использование разделителя ``.``, ``-`` или " +"``_``, а также полное отсутствие разделителя. Обычная форма - с разделителем " +"``.``. Это позволяет использовать такие версии, как ``1.2-dev2`` или " +"``1.2dev2``, которые нормализуются до ``1.2.dev2``." + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "Номер выпуска неявной разработки" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" +"В релизах разработки допускается опускать цифру, в этом случае она неявно " +"принимается за ``0``. Нормальной формой для этого является явное указание " +"``0``. Это позволяет использовать такие версии, как ``1.2.dev``, которые " +"нормализуются до ``1.2.dev0``." + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "Сегменты локальной версии" + +#: ../source/specifications/version-specifiers.rst:532 +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 "" +"В локальной версии, помимо использования ``.`` в качестве разделителя " +"сегментов, допустимо также использование ``-`` и ``_``. Нормальной формой " +"является использование символа ``.``. Это позволяет нормализовать такие " +"версии, как ``1.0+ubuntu-1``, до ``1.0+ubuntu.1``." + +#: ../source/specifications/version-specifiers.rst:539 +msgid "Preceding v character" +msgstr "Предшествующий символ v" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" +"Для поддержки общепринятой нотации версий ``v1.0`` версии могут предваряться " +"одним литеральным символом ``v``. Этот символ ДОЛЖЕН игнорироваться для всех " +"целей и должен быть опущен во всех нормализованных формах версии. Одна и та " +"же версия с ``v`` и без него считается эквивалентной." + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "Ведущие и отслеживающие Белое пространство" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" +"Ведущие и завершающие пробельные символы должны молча игнорироваться и " +"удаляться из всех нормализованных форм версии. Это включает в себя ``\"\"``, " +"``\\t``, ``\\n``, ``\\r``, ``\\f`` и ``\\v``. Это позволяет разумно " +"обрабатывать случайные пробелы, например, версия ``1.0\\n`` нормализуется до " +"``1.0``." + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "Примеры совместимых схем версий" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" +"Стандартная схема версий разработана таким образом, чтобы охватить широкий " +"спектр методов идентификации в государственных и частных проектах Python. На " +"практике один проект, пытающийся использовать всю гибкость, предлагаемую " +"схемой, создаст ситуацию, когда пользователям будет трудно определить " +"относительный порядок версий, хотя приведенные выше правила гарантируют, что " +"все совместимые инструменты будут упорядочивать их последовательно." + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" +"Следующие примеры иллюстрируют небольшую подборку различных подходов, " +"которые проекты могут выбрать для идентификации своих релизов, при этом " +"гарантируя, что \"последний релиз\" и \"последний стабильный релиз\" могут " +"быть легко определены как людьми, так и автоматизированными инструментами." + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "Простая версификация \"major.minor\" ::" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "Простая версия \"major.minor.micro\" ::" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" +"Версии \"major.minor\" с предварительными выпусками альфа-версий, бета-" +"версий и кандидатов::" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" +"«major.minor»-версия с релизами, кандидатами на выпуск и пост-релизами для " +"незначительных исправлений ::" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" +"Релизы, основанные на дате, с использованием возрастающей серии в пределах " +"каждого года, пропуская нулевой::" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "Краткое описание разрешенных суффиксов и относительного порядка" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" +"Этот раздел предназначен в первую очередь для авторов инструментов, " +"автоматически обрабатывающих метаданные дистрибутива, а не для разработчиков " +"дистрибутивов Python, принимающих решение о выборе схемы версионирования." + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" +"Сегмент эпохи в идентификаторах версий ДОЛЖЕН быть отсортирован в " +"соответствии с числовым значением данной эпохи. Если сегмент эпохи " +"отсутствует, неявное числовое значение равно ``0``." + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" +"Сегмент выпуска идентификаторов версий ДОЛЖЕН быть отсортирован в том же " +"порядке, что и сортировка кортежей в Python, когда нормализованный сегмент " +"выпуска разбирается следующим образом::" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" +"Все сегменты релиза, участвующие в сравнении, ДОЛЖНЫ быть приведены к единой " +"длине путем заполнения более коротких сегментов нулями по мере необходимости." + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" +"В числовом выпуске (``1.0``, ``2.7.3``) разрешены следующие суффиксы, " +"которые ДОЛЖНЫ быть упорядочены, как показано на рисунке::" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" +"Обратите внимание, что ``c`` считается семантически эквивалентным ``rc`` и " +"должен быть отсортирован так же, как если бы он был ``rc``. Инструментальные " +"средства МОГУТ отклонить случай наличия одинакового ``N`` для ``c`` и ``rc`` " +"в одном сегменте выпуска как неоднозначный и остаться в соответствии со " +"спецификацией." + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" +"Внутри альфа-версии (``1.0a1``), бета-версии (``1.0b1``) или релиз-кандидата " +"(``1.0rc1``, ``1.0c1``) разрешены следующие суффиксы, которые ДОЛЖНЫ быть " +"упорядочены, как показано::" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" +"Внутри пост-релиза (``1.0.post1``) разрешены следующие суффиксы, которые " +"ДОЛЖНЫ быть упорядочены, как показано::" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" +"Обратите внимание, что перед ``devN`` и ``postN`` ДОЛЖНА всегда стоять " +"точка, даже если они используются сразу после числовой версии (например, " +"``1.0.dev456``, ``1.0.post1``)." + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" +"Внутри сегмента предрелиза, пострелиза или релиза разработки с общим " +"префиксом упорядочивание ДОЛЖНО осуществляться по значению числового " +"компонента." + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "Следующий пример охватывает многие из возможных комбинаций::" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "Упорядочивание версий в различных версиях метаданных" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" +"Метаданные v1.0 (:pep:`241`) и метаданные v1.1 (:pep:`314`) не определяют " +"стандартную схему идентификации или упорядочивания версий. Однако в " +"метаданных v1.2 (:pep:`345`) указана схема, которая определена в :pep:`386`." + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" +"Из-за природы простого API инсталлятора он не может знать, какую версию " +"метаданных использует тот или иной дистрибутив. Кроме того, инсталляторам " +"требовалась возможность создать разумно приоритетный список, включающий все " +"или как можно больше версий проекта, чтобы определить, какие версии следует " +"установить. Эти требования обуславливают необходимость стандартизации одного " +"механизма разбора, который будет использоваться для всех версий проекта." + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" +"В связи с вышесказанным, эта спецификация ДОЛЖНА использоваться для всех " +"версий метаданных и заменяет :pep:`386` даже для метаданных v1.2. " +"Инструменты ДОЛЖНЫ игнорировать любые версии, которые не могут быть " +"разобраны по правилам этой спецификации, но МОГУТ вернуться к схемам разбора " +"и упорядочивания версий, определенным реализацией, если версии, " +"соответствующие этой спецификации, недоступны." + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" +"Пользователи дистрибутива могут захотеть явно удалить несоответствующие " +"версии из всех частных индексов пакетов, которые они контролируют." + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "Совместимость с другими схемами версий" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" +"Некоторые проекты могут использовать схему версий, которая требует перевода, " +"чтобы соответствовать схеме публичных версий, определенной в данной " +"спецификации. В таких случаях версия для конкретного проекта может храниться " +"в метаданных, а переведенная публичная версия публикуется в поле версии." + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" +"Это позволяет автоматизированным средствам распространения обеспечивать " +"стабильно корректное упорядочивание публикуемых релизов, в то же время " +"позволяя разработчикам использовать внутреннюю схему версионирования, " +"которую они предпочитают для своих проектов." + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" +"`Semantic versioning`_ - это популярная схема идентификации версий, которая " +"более предписательна, чем эта спецификация, в отношении значимости различных " +"элементов номера релиза. Даже если проект решает не придерживаться деталей " +"семантического версионирования, схему стоит понять, поскольку она охватывает " +"многие вопросы, которые могут возникнуть при зависимости от других " +"дистрибутивов, а также при публикации дистрибутива, на который полагаются " +"другие." + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" +"Аспекты \"Major.Minor.Patch\" (описанные в данной спецификации как " +"\"major.minor.micro\") семантической версионности (пункты 1-8 в спецификации " +"2.0.0) полностью совместимы со схемой версий, определенной в данной " +"спецификации, и соблюдение этих аспектов приветствуется." + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" +"Семантические версии, содержащие дефис (предвыпуск - пункт 10) или знак плюс " +"(бабочки - пункт 11), не совместимы с этой спецификацией и не разрешены в " +"поле публичной версии." + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" +"Одним из возможных механизмов перевода таких семантических версий, " +"основанных на метках источника, в совместимые публичные версии является " +"использование суффикса ``.devN`` для указания соответствующего порядка " +"версий." + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" +"Информация о конкретной сборке также может быть включена в локальные метки " +"версий." + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "Метки версий на базе DVCS" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" +"Многие инструменты сборки интегрируются с распределенными системами контроля " +"версий, такими как Git и Mercurial, чтобы добавить идентифицирующий хэш к " +"идентификатору версии. Поскольку хэши не могут быть надежно упорядочены, " +"такие версии не допускаются в поле публичной версии." + +#: ../source/specifications/version-specifiers.rst:776 +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 "" +"Как и в случае с семантическим версионированием, общедоступный суффикс " +"``.devN`` может использоваться для уникальной идентификации таких релизов " +"для публикации, а оригинальная метка, основанная на DVCS, может храниться в " +"метаданных проекта." + +#: ../source/specifications/version-specifiers.rst:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" +"Идентифицирующая хэш-информация также может быть включена в метки локальных " +"версий." + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "Версия базы данных Олсона" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" +"Проект ``pytz`` наследует свою схему версий от соответствующей схемы версий " +"базы данных часового пояса Olson: год, за которым следует строчный символ, " +"указывающий на версию базы данных в пределах этого года." + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" +"Это можно перевести в соответствующий идентификатор публичной версии как " +"``<год>.<серия>``, где серия начинается с нуля или единицы (для релиза " +"'<год>a') и увеличивается с каждым последующим обновлением базы данных в " +"течение года." + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" +"Как и в случае с другими идентификаторами переведенных версий, " +"соответствующая версия базы данных Olson может быть записана в метаданных " +"проекта." + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" +"Спецификатор версии состоит из ряда пунктов версии, разделенных запятыми. " +"Например::" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "Оператор сравнения определяет тип положения версии:" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "``~=``: `Совместимый релиз`_ пункт" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "``==``: `Версия соответствует`_ пункту" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "``!=``: `исключение версии`_ пункт" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "``<=``, ``>=``: предложение ``включенного упорядоченного сравнения`_" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "``<``, ``>``: предложение ``исключительного упорядоченного сравнения``" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "``===``: предложение `произвольного равенства`." + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" +"Запятая (\",\") эквивалентна логическому оператору **и**: версия-кандидат " +"должна соответствовать всем заданным пунктам версии, чтобы соответствовать " +"спецификатору в целом." + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" +"Пробелы между условным оператором и следующим идентификатором версии " +"необязательны, как и пробелы вокруг запятых." + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" +"За исключением случаев, оговоренных ниже, локальные идентификаторы версий НЕ " +"ДОЛЖНЫ быть разрешены в спецификаторах версий, а локальные метки версий " +"ДОЛЖНЫ полностью игнорироваться при проверке соответствия версий-кандидатов " +"заданному спецификатору версий." + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "Совместимый выпуск" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" +"Условие совместимого выпуска состоит из оператора совместимого выпуска " +"``~=`` и идентификатора версии. Он соответствует любой версии-кандидату, " +"которая, как ожидается, будет совместима с указанной версией." + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" +"Указанный идентификатор версии должен быть в стандартном формате, описанном " +"в `Схема версии`_. Локальные идентификаторы версий в этом спецификаторе " +"версий НЕ допускаются." + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" +"Для данного идентификатора выпуска ``V.N`` совместимое положение о выпуске " +"приблизительно эквивалентно паре положений сравнения::" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" +"Этот оператор НЕ ДОЛЖЕН использоваться с номером версии одного сегмента, " +"таким как ``~=1``." + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "Например, следующие группы положений о версии эквивалентны::" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" +"Если предрелиз, пострелиз или релиз разработки назван в положении о " +"совместимом релизе как ``V.N.suffix``, то суффикс игнорируется при " +"определении требуемого соответствия префикса::" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" +"Правила вставки для сравнения сегментов выпуска означают, что предполагаемая " +"степень прямой совместимости в положении о совместимом выпуске может " +"контролироваться путем добавления дополнительных нулей к спецификатору " +"версии::" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "Соответствие версий" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" +"Условие сопоставления версий включает оператор сопоставления версий ``==`` и " +"идентификатор версии." + +#: ../source/specifications/version-specifiers.rst:891 +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 "" +"Указанный идентификатор версии должен быть в стандартном формате, описанном " +"в `Version scheme`_, но в идентификаторах публичных версий допускается " +"наличие конца ``.*``, как описано ниже." + +#: ../source/specifications/version-specifiers.rst:895 +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." +msgstr "" +"По умолчанию оператор сопоставления версий основан на строгом сравнении " +"равенства: указанная версия должна быть точно такой же, как и запрашиваемая. " +"Единственная выполняемая замена - это нулевое заполнение сегмента выпуска, " +"чтобы гарантировать, что сегменты выпуска сравниваются с одинаковой длиной." + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" +"Уместно ли строгое соответствие версии или нет, зависит от конкретного " +"случая использования спецификатора версии. Автоматизированные инструменты " +"ДОЛЖНЫ как минимум выдавать предупреждения, а могут и полностью отклонять " +"их, если строгое соответствие версий используется неуместно." + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" +"Вместо строгого сравнения можно запросить префиксное сопоставление, добавив " +"к идентификатору версии в предложении о сопоставлении версий сдерживающий " +"сегмент ``.*``. Это означает, что при определении соответствия " +"идентификатора версии условию дополнительные сегменты в конце фразы будут " +"игнорироваться. Если указанная версия включает в себя только сегмент релиза, " +"то сдерживающие компоненты (или их отсутствие) в сегменте релиза также " +"игнорируются." + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" +"Например, для версии ``1.1.post1`` следующие пункты будут совпадать или не " +"совпадать, как показано на рисунке::" + +#: ../source/specifications/version-specifiers.rst:920 +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 "" +"Для целей сопоставления префиксов сегмент pre-release считается имеющим " +"подразумеваемый предшествующий ``.``, поэтому, учитывая версию ``1.1a1``, " +"следующие фразы будут соответствовать или не соответствовать, как показано::" + +#: ../source/specifications/version-specifiers.rst:928 +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::" +msgstr "" +"Точное совпадение также считается совпадением с префиксом (такая " +"интерпретация подразумевается обычными правилами нулевого заполнения для " +"сегмента release в идентификаторах версий). Для версии ``1.1`` следующие " +"пункты будут совпадать или не совпадать, как показано на рисунке::" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" +"Недопустимо использовать префиксное соответствие, содержащее релиз " +"разработки или локальный релиз, например ``1.0.dev1.*`` или ``1.0+foo1.*``. " +"Если они присутствуют, сегмент релиза разработки всегда является последним " +"сегментом публичной версии, а локальная версия игнорируется для целей " +"сравнения, поэтому использование любого из них в префиксном совпадении не " +"имеет смысла." + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" +"Использование ``==`` (без суффикса подстановки) при определении зависимостей " +"для опубликованных дистрибутивов категорически не рекомендуется, так как это " +"значительно усложняет развертывание исправлений безопасности. Строгий " +"оператор сравнения версий предназначен в первую очередь для использования " +"при определении зависимостей для повторяющихся *развертываний приложений* " +"при использовании общего индекса дистрибутива." + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +msgid "Version exclusion" +msgstr "Исключение версии" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" +"Предложение об исключении версии включает оператор исключения версии ``!=`` " +"и идентификатор версии." + +#: ../source/specifications/version-specifiers.rst:970 +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 "" +"Допустимые идентификаторы версий и семантика сравнения те же, что и у " +"оператора `Version matching`_, за исключением того, что смысл любого " +"совпадения инвертируется." + +#: ../source/specifications/version-specifiers.rst:983 +msgid "Inclusive ordered comparison" +msgstr "Всеобъемлющее упорядоченное сравнение" + +#: ../source/specifications/version-specifiers.rst:985 +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 "" +"Предложение инклюзивного упорядоченного сравнения включает оператор " +"сравнения и идентификатор версии, и будет соответствовать любой версии, где " +"сравнение корректно на основе относительного положения версии-кандидата и " +"указанной версии с учетом последовательного упорядочивания, определенного " +"стандартной `Version scheme`_." + +#: ../source/specifications/version-specifiers.rst:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "Инклюзивные операторы упорядоченного сравнения - ``<=`` и ``>=``." + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" +"Локальные идентификаторы версий в этом спецификаторе версий НЕ допускаются." + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "Исключительное упорядоченное сравнение" + +#: ../source/specifications/version-specifiers.rst:1002 +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 "" +"Исключительные упорядоченные сравнения ``>`` и ``<``` похожи на инклюзивные " +"упорядоченные сравнения в том, что они полагаются на относительное положение " +"версии-кандидата и указанной версии с учетом последовательного " +"упорядочивания, определенного стандартной `Version scheme`_. Однако они " +"специально исключают пре-релизы, пост-релизы и локальные версии указанной " +"версии." + +#: ../source/specifications/version-specifiers.rst:1008 +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 "" +"Исключительное упорядоченное сравнение ``>V`` **НЕ ДОЛЖНО** допускать пост-" +"релиз данной версии, если только ``V`` сам не является пост-релизом. Вы " +"можете запретить релизы более поздние, чем определенный пост-релиз, включая " +"дополнительные пост-релизы, используя ``>V.postN``. Например, ``>1.7`` " +"разрешит ``1.7.1``, но не ``1.7.0.post1``, а ``>1.7.post2`` разрешит " +"``1.7.1`` и ``1.7.0.post3``, но не ``1.7.0``." + +#: ../source/specifications/version-specifiers.rst:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" +"Исключительное упорядоченное сравнение ``>V`` **НЕ ДОЛЖНО** соответствовать " +"локальной версии указанной версии." + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" +"Для ссылок на исходный архив и колесо ожидаемое хэш-значение может быть " +"указано путем включения записи ``=`` в " +"качестве части фрагмента URL." + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" +"Для ссылок на систему контроля версий схема ``VCS+protocol`` ДОЛЖНА " +"использоваться для идентификации как системы контроля версий, так и " +"безопасного транспорта, и ДОЛЖНА использоваться система контроля версий с " +"идентификаторами фиксаций на основе хэшей. Автоматизированные инструменты " +"МОГУТ не выдавать предупреждения об отсутствии хэшей для систем контроля " +"версий, которые не предоставляют идентификаторы фиксации на основе хэшей." + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" +"Для работы с системами контроля версий, которые не поддерживают включение " +"ссылок на коммит или тег непосредственно в URL, эта информация может быть " +"добавлена в конец URL с помощью нотации ``@`` или " +"``@#``." + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" +"Это не совсем то же самое, что существующая нотация ссылок на VCS, " +"поддерживаемая pip. Во-первых, имя дистрибутива переносится вперёд, а не " +"вставляется в URL. Во-вторых, хэш коммита включается даже при поиске по " +"тегу, чтобы выполнить требование выше, что *каждая* ссылка должна включать " +"хэш, чтобы затруднить подделку (создать вредоносное репо с определённым " +"тегом легко, а создать репо с определённым *хэшем* - менее)." + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "Примеры удаленных URL::" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "URL-адреса файлов" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" +"URL-адреса файлов имеют вид ``file:///``. Если ```` " +"опущен, предполагается, что это ``localhost``, и даже если ```` " +"опущен, третья косая черта ДОЛЖНА существовать. Параметр ```` " +"определяет путь к файлу в файловой системе, к которому необходимо получить " +"доступ." + +#: ../source/specifications/version-specifiers.rst:1184 +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 "" +"В различных операционных системах \\*nix единственным допустимым значением " +"для ```` является опущение, ``localhost`` или другое FQDN, которое, по " +"мнению текущей машины, соответствует ее собственному хосту. Другими словами, " +"в \\*nix схема ``file://`` может использоваться только для доступа к путям " +"на локальной машине." + +#: ../source/specifications/version-specifiers.rst:1189 +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 "" +"В Windows формат файла должен включать букву диска, если это применимо, как " +"часть ``<пути>`` (например, ``file:///c:/path/to/a/file``). В отличие от " +"\\*nix в Windows параметр ```` может использоваться для указания " +"файла, находящегося на сетевом ресурсе. Другими словами, если перевести ``\\" +"\\\\machine\\volume\\file`` в урл ``file://``, то в итоге получится ``file://" +"machine/volume/file``. Дополнительную информацию об URL-адресах ``file://`` " +"в Windows можно найти в `MSDN `_." + +#: ../source/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "Краткое описание отличий от pkg_resources.parse_version" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.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 "" +"Примечание: это сравнение с ``pkg_resources.parse_version`` в том виде, в " +"котором он существовал на момент написания :pep:`440`. После того, как PEP " +"был принят, setuptools 6.0 и более поздние версии приняли описанное здесь " +"поведение." + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" +"Локальные версии сортируются по-разному, эта спецификация требует, чтобы они " +"сортировались как большие, чем та же версия без локальной версии, в то время " +"как ``pkg_resources.parse_version`` считает это маркером предрелизности." + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" +"Эта спецификация намеренно ограничивает синтаксис, который представляет " +"собой правильную версию, в то время как ``pkg_resources.parse_version`` " +"пытается получить некоторое значение из *любой* произвольной строки." + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" +"``pkg_resources.parse_version`` позволяет произвольно глубоко вложенные " +"указатели версий, такие как ``1.0.dev1.post1.dev5``. Однако эта спецификация " +"допускает только одно использование каждого типа, и они должны существовать " +"в определенном порядке." + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "Приложение: Разбор строк версий с помощью регулярных выражений" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" +"Как отмечалось ранее в разделе :ref:`public-version-identifiers`, " +"идентификаторы опубликованных версий ДОЛЖНЫ использовать канонический " +"формат. В этом разделе приведены регулярные выражения, которые можно " +"использовать для проверки того, имеет ли версия уже такую форму, и, если " +"нет, извлечь различные компоненты для последующей нормализации." + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" +"Чтобы проверить, соответствует ли идентификатор версии каноническому " +"формату, можно воспользоваться следующей функцией:" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" +"Чтобы извлечь компоненты идентификатора версии, используйте следующее " +"регулярное выражение (как определено в проекте `packaging `_):" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "Август 2014 г: Эта спецификация была одобрена через :pep:`440`." + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "Виртуальные среды Python" + +#: ../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/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "Обнаружение виртуальных сред во время выполнения" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +msgstr "" +"Во время выполнения виртуальные среды можно определить по тому, что " +"значение :py:data:`sys.prefix` (расположение файловой системы запущенного " +"интерпретатора) отличается от значения :py:data:`sys.base_prefix` " +"(расположение файловой системы по умолчанию для каталогов стандартной " +"библиотеки)." + +#: ../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)." +msgstr "" +":ref:`venv-explanation` в документации по стандартной библиотеке Python для " +"модуля :py:mod:`venv` рассказывает об этом, а также о концепции " +"\"активации\" виртуальной среды в интерактивной оболочке операционной " +"системы (этот шаг активации необязателен, и поэтому изменения, которые он " +"вносит, не могут быть надежно использованы для определения того, запущена ли " +"программа Python в виртуальной среде или нет)." + +#: ../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." +msgstr "" +"Как описано в :pep:`405`, виртуальная среда Python в своей простейшей форме " +"состоит не более чем из копии или симлинка двоичного файла Python, " +"сопровождаемого каталогом ``ite-packages`` и файлом ``pyvenv.cfg`` с ключом " +"``home``, указывающим, где найти модули стандартной библиотеки Python." + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" +"Хотя он разработан для удовлетворения потребностей стандартного " +"модуля :py:mod:`venv`, этот подход с раздельной установкой и файлом " +"``pyvenv.cfg`` может быть использован *любым* поставщиком установки Python, " +"который хочет, чтобы инструменты, специфичные для Python, знали, что они уже " +"работают в виртуальной среде, и дальнейшее вложение среды не требуется или " +"нежелательно." + +#: ../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 "" +"Даже при отсутствии файла ``pyvenv.cfg``, любой подход (например, " +"``ситэкастомайзер.py``, исправление установленной среды исполнения Python), " +"который приводит к тому, что :py: данные:`sys. префикс` и :py: " +"данные:`sys.базовый_префикс`` имеют разные значения, но при этом " +"обеспечивает совпадение схемы установки пакетов по умолчанию " +"в :py:mod:`sysconfig``, будет обнаружен и будет вести себя как виртуальная " +"среда Python." + +#: ../source/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "Май 2012 г: Эта спецификация была одобрена через :pep:`405`." + +#: ../source/specifications/well-known-project-urls.rst:5 +msgid "Well-known Project URLs in Metadata" +msgstr "Известные URL-адреса проектов в метаданных" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" +"Этот документ представляет интерес в первую очередь для *потребителей* " +"метаданных, которые должны использовать правила нормализации и известный " +"список ниже, чтобы сделать представление URL-адресов проектов согласованным " +"во всей экосистеме Python." + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" +"Производители *метаданных* (такие как инструменты сборки и отдельные " +"сопровождающие пакетов) могут продолжать использовать любые метки по своему " +"усмотрению, в рамках общих ограничений длины ``Project-URL``. Однако, когда " +"это возможно, пользователям *приветствуется* выбирать значимые метки, " +"которые нормализуются к известным меткам." + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" +"Смотрите :ref:`Writing your pyproject.toml - urls ` для ориентированного на пользователя руководства по выбору меток URL " +"проекта в метаданных вашего пакета." + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "Эта спецификация была первоначально определена в :pep:`753`." + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" +":pep:`753` упраздняет поля метаданных :ref:`core-metadata-home-page` " +"и :ref:`core-metadata-download-url` в пользу :ref:`core-metadata-project-" +"url`, и определяет процедуру нормализации и поиска для определения того, " +"является ли ``Project-URL`` \"хорошо известным\", т.е. имеет семантику, " +"присущую ``Home-page``, ``Download-URL``, или другим распространенным URL " +"проекта." + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" +"Это позволяет индексам (таким как Python Package Index) и другим " +"потребителям метаданных представлять URL-адреса проектов в согласованном " +"виде." + +#: ../source/specifications/well-known-project-urls.rst:42 +msgid "Label normalization" +msgstr "Нормализация меток" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" +"Нормализация меток выполняется *потребителями* метаданных, а не " +"производителями метаданных." + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" +"Чтобы определить, является ли метка ``Project-URL`` \"хорошо известной\", " +"потребители метаданных должны нормализовать ее перед сравнением " +"со :ref:`списком хорошо известных меток `." + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" +"Процедура нормализации меток ``Project-URL`` определяется следующей функцией " +"Python:" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" +"Простым языком: метка *нормализуется* путем удаления всех знаков препинания " +"и пробельных символов ASCII, а затем преобразуется в строчные буквы." + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" +"В следующей таблице приведены примеры меток до (сырой) и после нормализации:" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "Необработанный" + +#: ../source/specifications/well-known-project-urls.rst:75 +msgid "Normalized" +msgstr "Нормализованный" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "``Homepage``" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "``homepage``" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "``Home-page``" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "``Home page``" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "``Change_Log``" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "``changelog``" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "``What's New?``" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "``whatsnew``" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "``github``" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "Известные лейблы" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" +"Список известных лейблов - это живой стандарт, поддерживаемый в рамках " +"данного документа." + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" +"В следующей таблице перечислены метки, которые хорошо известны для целей " +"специализации представления метаданных ``Project-URL``:" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "Этикетка (человекочитаемый эквивалент)" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "Псевдонимы" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "``Домашняя страница`` (Домашняя страница)" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "Домашняя страница проекта" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "*(никто)*" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "``Источник`` (Исходный код)" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "Размещенный исходный код проекта или репозиторий" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "``repository``, ``sourcecode``, ``github``" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "``Загрузить`` (Загрузка)" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" +"URL-адрес загрузки текущего дистрибутива, эквивалентный ``Скачать-URL``" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "``changelog`` (журнал изменений)" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "Полный журнал изменений проекта" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "``changes``, ``whatsnew``, ``history``" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "``releasenotes`` (Заметки о выпуске)" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "Примечания к выпуску проекта" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "``документация`` (Документация)" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "Онлайн-документация проекта" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "``docs``" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "``issues`` (Трекер проблем)" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "Трекер ошибок проекта" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "``финансирование`` (Финансирование)" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "Информация о финансировании" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "``спонсор``, ``пожертвовать``, ``пожертвование``" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +#, fuzzy +msgid "Example behavior" +msgstr "Пример" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +#, fuzzy +msgid "Core metadata representation" +msgstr "Спецификации основных метаданных" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "Как получить поддержку" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" +"Для получения поддержки, связанной с конкретным проектом, смотрите ссылки на " +"странице :doc:`Projects `." + +#: ../source/support.rst:8 +msgid "" +"For something more general, or when you're just not sure, please `open an " +"issue `_ on the `packaging-problems `_ repository on GitHub." +msgstr "" +"Для чего-то более общего, или если вы просто не уверены, пожалуйста, " +"`откройте проблему `_ в репозитории `packaging-problems `_ на GitHub." + +#: ../source/tutorials/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "Создание документации" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" +"Это руководство было удалено, поскольку оно не имеет отношения к упаковке и " +"не поддерживается. Пожалуйста, обратитесь к учебнику `Sphinx `_ вместо этого." + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" +"**Учебники** - это пошаговые руководства, которые помогут вам ознакомиться с " +"концепциями упаковки. Более подробную информацию по конкретным темам " +"упаковки можно найти в :doc:`/guides/index`." + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "Установка Пакетов" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" +"В этом разделе рассматриваются основы установки Python :term:`packages " +"`." + +#: ../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 "" +"Важно отметить, что термин \"пакет\" в данном контексте используется для " +"описания пакета программного обеспечения, подлежащего установке (т.е. как " +"синоним :term:`distribution `). Он не относится к " +"типу :term:`package `, который вы импортируете в исходный " +"код Python (т.е. контейнер модулей). В сообществе Python принято ссылаться " +"на :term:`distribution `, используя термин \"пакет\". " +"Использование термина \"дистрибутив\" часто не является предпочтительным, " +"поскольку его легко спутать с дистрибутивом Linux или другим большим " +"дистрибутивом программного обеспечения, таким как сам Python." + +#: ../source/tutorials/installing-packages.rst:24 +msgid "Requirements for Installing Packages" +msgstr "Требования к установке пакетов" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +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 +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:" +msgstr "" +"Прежде чем продолжить, убедитесь, что у вас есть Python и что ожидаемая " +"версия доступна в командной строке. Вы можете проверить это, выполнив " +"команду:" + +#: ../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`_ или " +"обратитесь к разделу :ref:`Установка Python ` " +"руководства \"Путеводитель автостопщика по Питону\"." + +#: ../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:62 +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." +msgstr "" +"Это связано с тем, что данная команда и другие команды, предложенные в этом " +"руководстве, предназначены для запуска в *оболочке* (также называемой " +"*терминалом* или *консолью*). О том, как использовать оболочку операционной " +"системы и взаимодействовать с Python, читайте в учебнике Python для " +"начинающих `Начало работы`_." + +#: ../source/tutorials/installing-packages.rst:68 +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:" +msgstr "" +"Если вы используете расширенную оболочку, такую как IPython или блокнот " +"Jupyter, вы можете запускать системные команды, подобные тем, что приведены " +"в этом руководстве, предваряя их символом ``!``:" + +#: ../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 "" +"Рекомендуется писать ``{sys.executable}``, а не просто ``python``, чтобы " +"обеспечить выполнение команд в установке Python, соответствующей текущему " +"запущенному блокноту (которая может быть не той установкой Python, на " +"которую ссылается команда ``python``)." + +#: ../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, пользователям Linux, использующим системный Python без создания " +"виртуальной среды, следует заменить команду ``python`` в этом руководстве на " +"``python3``, а команду ``python -m pip`` на ``python3 -m pip --user``. Не " +"запускайте ни одну из команд в этом руководстве с ``sudo`: если вы получите " +"ошибку разрешения, вернитесь к разделу о создании виртуальных сред, " +"настройте их, а затем продолжите руководство, как написано." + +#: ../source/tutorials/installing-packages.rst:95 +msgid "Ensure you can run pip from the command line" +msgstr "Убедитесь, что вы можете запустить pip из командной строки" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" +"Кроме того, вам нужно убедиться, что у вас доступен :ref:`pip`. Вы можете " +"проверить это, выполнив команду:" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" +"Если вы установили Python из исходников, с помощью инсталлятора с сайта " +"`python.org`_ или через `Homebrew`_, у вас уже должен быть pip. Если вы " +"работаете в Linux и устанавливали с помощью менеджера пакетов вашей ОС, вам, " +"возможно, придется установить pip отдельно, см. :doc:`/guides/installing-" +"using-linux-tools`." + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" +"Если ``pip`` еще не установлен, то сначала попробуйте загрузить его из " +"стандартной библиотеки:" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" +"Безопасная загрузка `get-pip.py `_ [1]_" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" +"Запустите ``python get-pip.py``. [2]_ Это приведет к установке или " +"обновлению pip. Кроме того, будут установлены :ref:`setuptools` " +"и :ref:`wheel`, если они еще не установлены." + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" +"Будьте осторожны, если вы используете установку Python, управляемую " +"операционной системой или другим менеджером пакетов. get-pip.py не " +"координируется с этими инструментами и может оставить вашу систему в " +"несовместимом состоянии. Вы можете использовать ``python get-pip.py --" +"prefix=/usr/local/`` для установки в ``/usr/local``, который предназначен " +"для локально установленного программного обеспечения." + +#: ../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 "" +"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 "" +"Хотя одного ``pip`` достаточно для установки из предварительно собранных " +"бинарных архивов, актуальные копии проектов ``setuptools`` и ``wheel`` " +"полезны для обеспечения возможности установки из исходных архивов:" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "По желанию создайте виртуальную среду" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"See :ref:`section below ` for " +"details, but here's the basic :doc:`venv ` [3]_ command " +"to use on a typical Linux system:" +msgstr "" +"Подробности см. в :ref:`разделе ниже <Создание и использование виртуальных " +"сред>`, а вот основная :doc:`venv ` [3]_ команда для " +"использования в типичной системе Linux:" + +#: ../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 "" +"Это создаст новое виртуальное окружение в подкаталоге ``tutorial_env`` и " +"настроит текущую оболочку на использование его в качестве окружения по " +"умолчанию ``python``." + +#: ../source/tutorials/installing-packages.rst:199 +msgid "Creating Virtual Environments" +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 "" +"Виртуальные среды Python позволяют устанавливать Python :term:`packages " +"` в изолированное место для конкретного приложения, а " +"не устанавливать глобально. Если вы хотите безопасно установить глобальные " +"инструменты командной строки, смотрите :doc:`/guides/installing-stand-alone-" +"command-line-tools`." + +#: ../source/tutorials/installing-packages.rst:207 +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." +msgstr "" +"Представьте, что у вас есть приложение, которому нужна версия 1 LibFoo, а " +"другому приложению требуется версия 2. Как вы можете использовать оба этих " +"приложения? Если вы установите все в /usr/lib/python3.6/site-packages (или в " +"любое другое стандартное место вашей платформы), легко попасть в ситуацию, " +"когда вы непреднамеренно обновите приложение, которое не должно быть " +"обновлено." + +#: ../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/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 "" +"Кроме того, что делать, если вы не можете установить :term:`packages " +"` в глобальный каталог site-packages? Например, на " +"общем хосте." + +#: ../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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" +"В настоящее время существует два распространенных инструмента для создания " +"виртуальных сред Python:" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" +": док:`venv ` доступен по умолчанию в Python 3.3 и " +"выше, и устанавливает : ссылка:`pip` в созданные виртуальные среды в Python " +"3.4 и выше (версии Python до 3.12 также устанавливали :ссылка:`setuptools`)." + +#: ../source/tutorials/installing-packages.rst:229 +#, fuzzy +#| 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)." +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +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/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "Использование :doc:`venv `:" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "Использование :ref:`virtualenv`:" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" +"Дополнительную информацию можно найти в документах :doc:`venv " +"` или :doc:`virtualenv `." + +#: ../source/tutorials/installing-packages.rst:271 +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)." +msgstr "" +"Использование :command:`source` в оболочках Unix гарантирует, что переменные " +"виртуального окружения будут установлены в текущей оболочке, а не в " +"подпроцессе (который затем исчезает, не оказывая никакого полезного " +"воздействия)." + +#: ../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 "" +"В обоих случаях пользователям Windows не следует использовать " +"команду :command:`source`, а лучше запустить скрипт :command:`activate` " +"непосредственно из командной оболочки, как показано выше:" + +#: ../source/tutorials/installing-packages.rst:286 +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 "" +"Непосредственное управление несколькими виртуальными средами может стать " +"утомительным, поэтому в учебнике по управлению зависимостями ` представлен инструмент более высокого уровня, :ref:`Pipenv`, " +"который автоматически управляет отдельной виртуальной средой для каждого " +"проекта и приложения, над которым вы работаете." + +#: ../source/tutorials/installing-packages.rst:293 +msgid "Use pip for Installing" +msgstr "Используйте pip для установки" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" +":ref:`pip` - это рекомендуемая программа установки. Ниже мы рассмотрим " +"наиболее распространенные сценарии использования. Более подробную информацию " +"можно найти в :doc:`pip docs `, который включает в себя " +"полное :doc:`Reference Guide `." + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "Установка из PyPI" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" +"Чаще всего :ref:`pip` используется для установки из индекса " +"пакетов :term:`Python ` с помощью спецификатора " +"требований :term:`Requirement Specifier `. Вообще " +"говоря, спецификатор требований состоит из имени проекта, за которым следует " +"необязательный :term:`спецификатор версии `. Полное " +"описание поддерживаемых спецификаторов можно найти в " +"спецификации :ref:`Version specifier `. Ниже приведены " +"некоторые примеры." + +#: ../source/tutorials/installing-packages.rst:311 +msgid "To install the latest version of \"SomeProject\":" +msgstr "Чтобы установить последнюю версию \"SomeProject\":" + +#: ../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 "Чтобы установить версию больше или равную одной и меньше другой:" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" +"Чтобы установить версию, которая :ref:`совместима ` с определенной версией: [4]_" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" +"В данном случае это означает установку любой версии \"==1.4.*\", которая " +"также \">=1.4.2\"." + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "Дистрибутивы источников против колес" + +#: ../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:`Source Distributions (sdist) " +"<Источниковый дистрибутив (или \"sdist\")>`, так и из :term:`Wheels " +"`, но если оба присутствуют на PyPI, pip предпочтет " +"совместимый :term:`wheel `. Вы можете переопределить поведение pip по " +"умолчанию, например, используя его опцию :ref:`--no-binary `." + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" +":term:`Колеса ` - это предварительно собранный :term:`дистрибутив " +"` формата, который обеспечивает более быструю " +"установку по сравнению с :term:`Source Distributions (sdist) `, особенно когда проект содержит " +"скомпилированные расширения." + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" +"Если :ref:`pip` не находит колеса для установки, он локально собирает колесо " +"и кэширует его для будущих установок, вместо того, чтобы пересобирать " +"исходный дистрибутив в будущем." + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" +"Обновление уже установленного ``SomeProject`` до последней версии из PyPI." + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "Установка в пользовательский каталог :file:`site`" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" +"Чтобы установить :term:`пакеты `, которые изолированы " +"от текущего пользователя, используйте флаг ``--user``:" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" +"Для получения дополнительной информации смотрите раздел `User Installs " +"`_ из документации " +"pip." + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +msgstr "" +"Обратите внимание, что флаг ``--user`` не влияет на виртуальную среду - все " +"команды установки будут влиять на виртуальную среду." + +#: ../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`:" +msgstr "" +"Если ``SomeProject`` определяет какие-либо скрипты командной строки или " +"консольные точки входа, ``--user`` заставит их быть установленными в " +"бинарную директорию ``user base`_, которая может присутствовать или не " +"присутствовать в :envvar:`PATH`` вашей оболочки. (Начиная с версии 10, pip " +"выводит предупреждение при установке любых скриптов в каталог " +"вне :envvar:`PATH`). Если скрипты недоступны в вашей оболочке после " +"установки, вам нужно добавить каталог в :envvar:`PATH`:" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" +"В Linux и macOS вы можете найти бинарный каталог пользовательской базы, " +"выполнив команду ``python -m site --user-base`` и добавив ``bin`` в конце. " +"Например, обычно выводится ``~/.local`` (при этом ``~`` расширяется до " +"абсолютного пути к вашей домашней директории), поэтому вам нужно будет " +"добавить ``~/.local/bin`` в ваш ``PATH``. Вы можете установить свой " +"``PATH`` постоянно, ``изменив ~/.profile``." + +#: ../source/tutorials/installing-packages.rst:450 +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." +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``. Вы можете " +"установить пользовательский ``PATH'' постоянно в ``Панели управления''. " +"Чтобы изменения ``PATH'' вступили в силу, вам может потребоваться выйти из " +"системы." + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" +"Установка списка требований, указанных в :ref:`Requirements File " +"`." + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "Установка из СКВ" + +#: ../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 `." +msgstr "" +"Установка проекта из VCS в \"редактируемом\" режиме. Полное описание " +"синтаксиса см. в разделе pip по :ref:`VCS Support `." + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "Установка из других индексов" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "Установка из альтернативного индекса" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" +"Поиск дополнительного индекса во время установки, в дополнение к :term:`PyPI " +"`" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "Установка из локального дерева исходных кодов" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" +"Установка из локального src в :doc:`Режиме разработки `, т.е. таким образом, что проект кажется установленным, но " +"при этом его можно редактировать из дерева src." + +#: ../source/tutorials/installing-packages.rst:558 +msgid "You can also install normally from src" +msgstr "Вы также можете установить обычную установку из src" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" +"Установите из локальной директории, содержащей архивы (и не " +"проверяйте :term:`PyPI `)" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "Установка из других источников" + +#: ../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 "" +"Для установки из других источников данных (например, из хранилища Amazon S3) " +"вы можете создать вспомогательное приложение, представляющее данные в " +"формате, совместимом с :ref:`simple repository API :, " +"и использовать флаг ``--extra-index-url``, чтобы направить pip на " +"использование этого индекса." + +#: ../source/tutorials/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "Установка предварительных выпусков" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" +"Найдите предварительные версии и версии для разработки в дополнение к " +"стабильным версиям. По умолчанию pip находит только стабильные версии." + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "Установка \"Дополнений\"" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" +"Дополнения - это необязательные \"варианты\" пакета, которые могут включать " +"дополнительные зависимости и тем самым обеспечивать дополнительную " +"функциональность пакета. Если вы хотите установить дополнительное " +"расширение для пакета, который, как вы знаете, его публикует, вы можете " +"включить его в команду установки pip:" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" +"\"Безопасный\" в данном контексте означает использование современного " +"браузера или такого инструмента, как :command:`curl`, который проверяет SSL-" +"сертификаты при загрузке с https-адресов." + +#: ../source/tutorials/installing-packages.rst:675 +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`." +msgstr "" +"Начиная с Python 3.4, ``venv`` (stdlib-альтернатива :ref:`virtualenv`) будет " +"создавать виртуальные среды virtualenv с предустановленным ``pip``, что " +"делает его равноправной альтернативой :ref:`virtualenv``." + +#: ../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" +msgstr "" +"Спецификатор совместимого выпуска был принят в :pep:`440` и поддержка была " +"выпущена в :ref:`setuptools` v8.0 и :ref:`pip` v6.0" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "Управление зависимостями приложений" + +#: ../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." +msgstr "" +"В :ref:`учебнике по установке пакетов ` рассматривались " +"основы настройки установки и обновления пакетов Python." + +#: ../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." +msgstr "" +"Однако интерактивное выполнение этих команд может быть утомительным даже для " +"ваших личных проектов, и все становится еще сложнее, когда вы пытаетесь " +"автоматически настроить среду разработки для проектов с несколькими " +"соавторами." + +#: ../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/managing-dependencies.rst:17 +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." +msgstr "" +"Не забывайте, что Python используется для множества различных целей, и то, " +"как именно вы хотите управлять зависимостями, может измениться в зависимости " +"от того, как вы решите опубликовать свое программное обеспечение. " +"Представленное здесь руководство наиболее непосредственно применимо к " +"разработке и развертыванию сетевых сервисов (включая веб-приложения), но оно " +"также очень хорошо подходит для управления средами разработки и тестирования " +"для любого проекта." + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" +"Альтернативные варианты см. в разделе `Другие инструменты для управления " +"зависимостями приложений`_." + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "Установка Pipenv" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" +":ref:`Pipenv` - это менеджер зависимостей для Python-проектов. Если вы " +"знакомы с `npm`_ в Node.js или `bundler`_ в Ruby, то он схож по духу с этими " +"инструментами. Хотя для личного использования часто достаточно " +"одного :ref:`pip`, Pipenv рекомендуется для совместных проектов, так как это " +"инструмент более высокого уровня, который упрощает управление зависимостями " +"для общих случаев использования." + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "Используйте ``pip`` для установки Pipenv:" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" +"При этом выполняется ``пользовательская установка``, чтобы не нарушить " +"общесистемные пакеты. Если ``pipenv`` недоступен в вашей оболочке после " +"установки, вам нужно добавить бинарную директорию :py:data:`user base " +"` в ваш ``PATH``. Дополнительную информацию см. в " +"разделе :ref:`Установка на сайт пользователя`." + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "Установка пакетов для вашего проекта" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +msgstr "" +"Pipenv управляет зависимостями на основе каждого проекта. Чтобы установить " +"пакеты, перейдите в каталог вашего проекта (или просто в пустой каталог для " +"этого руководства) и выполните команду:" + +#: ../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):" +msgstr "" +"Pipenv установит библиотеку `Requests`_ и создаст для вас ``Pipfile`` в " +"каталоге вашего проекта. Этот :ref:`Pipfile` используется для отслеживания " +"зависимостей, необходимых вашему проекту, на случай, если вам понадобится их " +"переустановить, например, когда вы делитесь своим проектом с другими. Вы " +"должны получить результат, похожий на этот (хотя точные пути могут " +"отличаться):" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "Использование установленных пакетов" + +#: ../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 "" +"Теперь, когда Requests установлен, вы можете создать простой " +"файл :file:`main.py` для его использования:" + +#: ../source/tutorials/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "Затем вы можете запустить этот скрипт с помощью ``pipenv run``:" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "Вы должны получить результат, похожий на этот:" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" +"Использование ``pipenv run`` гарантирует, что установленные пакеты будут " +"доступны вашему скрипту. Также можно породить новую оболочку, которая " +"обеспечит доступ всех команд к установленным пакетам с помощью ``pipenv " +"shell``." + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "Следующие шаги" + +#: ../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 "" +"Поздравляем, теперь вы знаете, как эффективно управлять зависимостями и " +"средами разработки в совместном проекте на Python! ✨ 🍰 ✨" + +#: ../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/managing-dependencies.rst:148 +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``)." +msgstr "" +"Обратите внимание, что если ваше приложение включает определения пакетов с " +"исходным кодом Python, они (и их зависимости) могут быть добавлены в ваше " +"окружение ``pipenv`` с помощью ``pipenv install -e <относительный-патч-к-" +"директории-источника>`` (например, ``pipenv install -e .`` или ``pipenv " +"install -e src``)." + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "Другие инструменты для управления зависимостями приложений" + +#: ../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/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/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 "" +"`micropipenv `_ для " +"легковесной обертки вокруг pip, поддерживающей файлы ``requirements.txt``, " +"Pipenv и Poetry lock, или конвертирующей их в совместимый с pip-tools вывод. " +"Предназначена для контейнерных Python-приложений, но не ограничивается ими." + +#: ../source/tutorials/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" +"`PDM `_ для современного управления " +"пакетами Python, опирающегося на такие стандарты, как :pep:`517` " +"и :pep:`621`." + +#: ../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 "" +"`pip-tools `_ для создания файла " +"блокировки всех зависимостей из списка пакетов, непосредственно используемых " +"в проекте, и обеспечения установки только этих зависимостей." + +#: ../source/tutorials/managing-dependencies.rst:175 +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." +msgstr "" +"`Poetry `__ для инструмента, " +"сопоставимого с Pipenv по масштабу, который в большей степени ориентирован " +"на случаи использования, когда управляемый проект структурирован как " +"распространяемый пакет Python с действительным файлом ``pyproject.toml``. В " +"отличие от этого, Pipenv явно избегает предположений о том, что приложение, " +"над которым ведется работа, будет поддерживать распространение в виде " +"``pip``-инсталлируемого Python-пакета." + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "Упаковка Python'ьих проектов" + +#: ../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 Package Index (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 "" +"Если у вас возникли проблемы с выполнением команд в этом руководстве, " +"скопируйте команду и ее вывод, а затем `откройте проблему`_ в репозитории " +"`packaging-problems`_ на GitHub. Мы сделаем все возможное, чтобы помочь вам!" + +#: ../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:" +msgstr "" +"Некоторые из команд требуют более новой версии :ref:`pip`, поэтому для " +"начала убедитесь, что у вас установлена последняя версия:" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "Простой проект" + +#: ../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 "" +"В этом руководстве используется простой проект с именем " +"``example_package_YOUR_USERNAME_HERE``. Если ваше имя пользователя ``me``, " +"то пакет будет ``example_package_me``; это гарантирует, что у вас будет " +"уникальное имя пакета, которое не будет конфликтовать с пакетами, " +"загруженными другими людьми, следующими этому руководству. Мы рекомендуем " +"следовать этому руководству как есть, используя этот проект, прежде чем " +"упаковывать свой собственный проект." + +#: ../source/tutorials/packaging-projects.rst:44 +msgid "Create the following file structure locally:" +msgstr "Создайте локально следующую структуру файлов:" + +#: ../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 "" +"Каталог, содержащий файлы Python, должен совпадать с именем проекта. Это " +"упрощает настройку и более очевидно для пользователей, устанавливающих пакет." + +#: ../source/tutorials/packaging-projects.rst:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" +"Создание файла : файл:`__init__.py` рекомендуется, потому что наличие " +"файла :файл:`__init__.py` позволяет пользователям импортировать каталог как " +"обычный пакет, даже если (как в этом руководстве) :файл:`__init__.py` пуст. " +"[#пространство имен-пакетов]_" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" +"Файл:`example.py` - это пример модуля внутри пакета, который может содержать " +"логику (функции, классы, константы и т.д.) вашего пакета. Откройте этот файл " +"и введите следующее содержимое:" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" +"Если вы не знакомы с :term:`модулями ` и :term:`импортными пакетами " +"`, потратьте несколько минут на чтение `документации Python " +"по пакетам и модулям`_." + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"Once you create this structure, you'll want to run all of the commands in " +"this tutorial within the ``packaging_tutorial`` directory." +msgstr "" +"Как только вы создадите эту структуру, вам нужно будет запустить все команды " +"этого руководства в директории ``packaging_tutorial``." + +#: ../source/tutorials/packaging-projects.rst:83 +msgid "Creating the package files" +msgstr "Создание файлов пакета" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" +"Теперь вы будете добавлять файлы, которые используются для подготовки " +"проекта к распространению. Когда вы закончите, структура проекта будет " +"выглядеть следующим образом:" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "Создание тестового каталога" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" +":file:`tests/` - это заполнитель для тестовых файлов. Оставьте его пока " +"пустым." + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "Выбор бэкенда для сборки" + +#: ../source/tutorials/packaging-projects.rst:113 +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 "" +"Такие инструменты, как :ref:`pip` и :ref:`build`, на самом деле не " +"преобразуют ваши исходники в :term:`дистрибутивный пакет ` (как колесо); эту работу выполняет :term:`build backend `. Бэкенд сборки определяет, как ваш проект будет задавать свою " +"конфигурацию, включая метаданные (информацию о проекте, например, название и " +"теги, которые отображаются на PyPI) и входные файлы. Бэкенды сборки имеют " +"различные уровни функциональности, например, поддерживают ли они " +"сборку :term:`модулей расширения `, и вы должны выбрать " +"тот, который соответствует вашим потребностям и предпочтениям." + +#: ../source/tutorials/packaging-projects.rst:122 +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 "" +"Вы можете выбрать один из нескольких бэкендов; в этом руководстве по " +"умолчанию используется :ref:`Hatchling `, но он будет работать " +"идентично с :ref:`setuptools`, :ref:`Flit `, :ref:`PDM ` и " +"другими, которые поддерживают таблицу ``[project]`` для :ref:`metadata " +"`." + +#: ../source/tutorials/packaging-projects.rst:129 +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:134 +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." +msgstr "" +"В :file:`pyproject.toml` указывается :term:`build frontend ` " +"инструментам, таким как :ref:`pip` и :ref:`build`, какой бэкенд использовать " +"для вашего проекта. Ниже приведены примеры для распространенных бэкендов " +"сборки, но для получения более подробной информации обратитесь к " +"документации по вашему бэкенду." + +#: ../source/tutorials/packaging-projects.rst:141 +#, fuzzy +#| 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." +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" +"Ключ ``requires`` - это список пакетов, которые необходимы для сборки вашего " +"пакета. Функция :term:`frontend ` должна установить их " +"автоматически при сборке вашего пакета. Фронтенды обычно выполняют сборку в " +"изолированном окружении, поэтому отсутствие зависимостей здесь может " +"привести к ошибкам во время сборки. Это всегда должно включать пакет вашего " +"бэкенда и может иметь другие зависимости во время сборки." + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"The ``build-backend`` key is the name of the Python object that frontends " +"will use to perform the build." +msgstr "" +"Ключ ``build-backend`` - это имя объекта Python, который фронтенды будут " +"использовать для выполнения сборки." + +#: ../source/tutorials/packaging-projects.rst:153 +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:157 +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." +msgstr "" +"Дополнительная конфигурация инструмента сборки будет находиться либо в " +"секции ``tool`` в файле ``pyproject.toml``, либо в специальном файле, " +"определяемом инструментом сборки. Например, при использовании ``setuptools`` " +"в качестве бэкенда сборки, дополнительные настройки могут быть добавлены в " +"файл ``setup.py`` или ``setup.cfg``, а указание ``setuptools.build_meta`` в " +"вашей сборке позволяет инструментам автоматически находить и использовать их." + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "Конфигурирование метаданных" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" +"Откройте :file:`pyproject.toml` и введите следующее содержимое. Измените " +"``имя``, чтобы оно включало ваше имя пользователя; это гарантирует, что у " +"вас будет уникальное имя пакета, которое не будет конфликтовать с пакетами, " +"загруженными другими людьми, следующими этому руководству." + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" +"``имя`` - это *имя дистрибутива* вашего пакета. Это может быть любое имя, " +"если оно содержит только буквы, цифры, ``.``, ``_`` и ``-``. Оно также не " +"должно быть уже занято на PyPI. **Убедитесь, что вы указали в нем свое имя " +"пользователя** для этого руководства, так как это гарантирует, что вы не " +"попытаетесь загрузить пакет с тем же именем, что и уже существующий." + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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`` - это версия пакета. (Некоторые сборки позволяют указывать ее " +"другим способом, например, из файла или Git-тега)" + +#: ../source/tutorials/packaging-projects.rst:203 +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." +msgstr "" +"``authors`` используется для идентификации автора пакета; вы указываете имя " +"и email для каждого автора. В таком же формате можно перечислить " +"``maintainers``." + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "``description`` - это краткое, в одно предложение, описание пакета." + +#: ../source/tutorials/packaging-projects.rst:207 +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:`pyproject.toml `." + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" +"``requires-python`` указывает версии Python, поддерживаемые вашим проектом. " +"Программа установки, такая как :ref:`pip`, будет просматривать старые версии " +"пакетов, пока не найдет ту, которая имеет соответствующую версию Python." + +#: ../source/tutorials/packaging-projects.rst:215 +#, fuzzy +#| 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/." +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on and which operating systems your package " +"will work on. For a complete list of classifiers, see https://pypi.org/" +"classifiers/." +msgstr "" +"``классификаторы`` дают индексу и :ref:`pip`` некоторые дополнительные " +"метаданные о вашем пакете. В данном случае пакет совместим только с Python " +"3, лицензируется по лицензии MIT и не зависит от ОС. Вы всегда должны " +"указывать, по крайней мере, на какой версии (версиях) Python работает ваш " +"пакет, под какой лицензией он доступен, и на каких операционных системах он " +"будет работать. Полный список классификаторов можно найти на сайте https://" +"pypi.org/classifiers/." + +#: ../source/tutorials/packaging-projects.rst:222 +#, fuzzy +#| msgid "" +#| "This is a valid :term:`SPDX license expression ` " +#| "consisting of one or more :term:`license identifiers `. The full license list is available at the `SPDX license " +#| "list page `_. The supported list version is 3.17 or any " +#| "later compatible one." +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" +"Это действительное выражение лицензии :term:`SPDX `, " +"состоящее из одного или нескольких :term:`license identifiers `. Полный список лицензий доступен на странице `списка лицензий " +"SPDX `_. Поддерживаемая версия списка - 3.17 или любая " +"более поздняя совместимая." + +#: ../source/tutorials/packaging-projects.rst:224 +#, fuzzy +#| msgid "" +#| "Now run this command from the same directory where :file:`pyproject.toml` " +#| "is located:" +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" +"Теперь запустите эту команду из той же директории, где " +"находится :file:`pyproject.toml`:" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" +"``urls`` позволяет вам перечислить любое количество дополнительных ссылок, " +"которые нужно показать на PyPI. Обычно это могут быть ссылки на исходный " +"текст, документацию, трекеры проблем и т.д." + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" +"Подробности об этих и других полях, которые могут быть определены в таблице " +"``[проект]``, см. в руководстве `. Другими " +"распространенными полями являются ``ключевые слова'' для повышения удобства " +"поиска и ``зависимости'', необходимые для установки вашего пакета." + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "Создание файла :file:`README.md`" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" +"Откройте :file:`README.md` и введите следующее содержимое. Вы можете " +"настроить его по своему усмотрению." + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "Создание файла :file:`LICENSE`" + +#: ../source/tutorials/packaging-projects.rst:253 +#, fuzzy +#| 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:" +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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 "" +"Важно, чтобы каждый пакет, загруженный в Python Package Index, содержал " +"лицензию. Это указывает пользователям, устанавливающим ваш пакет, на каких " +"условиях они могут его использовать. О том, как выбрать лицензию, читайте на " +"сайте https://choosealicense.com/. Выбрав лицензию, откройте :file:`LICENSE` " +"и введите текст лицензии. Например, если вы выбрали лицензию MIT:" + +#: ../source/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "Включение других файлов" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" +"Перечисленные выше файлы будут автоматически включены в ваш :term:`source " +"дистрибутив `. Если вы хотите включить " +"дополнительные файлы, обратитесь к документации по вашему бэкенду сборки." + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "Создание архивов дистрибутивов" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" +"Следующим шагом будет создание :term:`distribution packages ` для пакета. Это архивы, которые загружаются в индекс пакетов " +"Python и могут быть установлены с помощью :ref:`pip`." + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "Убедитесь, что у вас установлена последняя версия PyPA :ref:`build`:" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" +"Если у вас возникли проблемы с их установкой, обратитесь к " +"руководству :doc:`installing-packages`." + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" +"Теперь запустите эту команду из той же директории, где " +"находится :file:`pyproject.toml`:" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" +"Эта команда должна вывести много текста и по завершении создать два файла в " +"каталоге :file:`dist`:" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" +"Файл ``tar.gz`` представляет собой :term:``исходный дистрибутив ``, а файл ``.whl`` представляет " +"собой :term:``сборный дистрибутив `. Более новые " +"версии :ref:`pip` предпочитают устанавливать собранные дистрибутивы, но при " +"необходимости возвращаются к исходным дистрибутивам. Вы всегда должны " +"загружать исходный дистрибутив и предоставлять собранные дистрибутивы для " +"платформ, с которыми совместим ваш проект. В данном случае наш пример пакета " +"совместим с Python на любой платформе, поэтому требуется только один " +"собранный дистрибутив." + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "Загрузка архивов дистрибутива" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "Наконец, пришло время загрузить ваш пакет в Python Package Index!" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" +"Первое, что вам нужно сделать, это зарегистрировать аккаунт на TestPyPI, " +"который представляет собой отдельный экземпляр индекса пакетов, " +"предназначенный для тестирования и экспериментов. Он отлично подходит для " +"таких вещей, как этот учебник, где мы не обязательно хотим загружать в " +"настоящий индекс. Чтобы зарегистрировать учетную запись, перейдите по адресу " +"https://test.pypi.org/account/register/ и выполните все шаги на этой " +"странице. Вам также потребуется подтвердить свой адрес электронной почты, " +"прежде чем вы сможете загружать пакеты. Более подробную информацию можно " +"найти в :doc:`/guides/using-testpypi`." + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" +"Чтобы безопасно загрузить свой проект, вам понадобится токен PyPI `API " +"token`_. Создайте его на сайте https://test.pypi.org/manage/account/#api-" +"tokens, установив для параметра \"Область действия\" значение \"Весь " +"аккаунт\". **Не закрывайте страницу, пока не скопируете и не сохраните токен " +"- больше вы его не увидите**" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"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/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" +"После установки запустите Twine, чтобы загрузить все архивы в " +"папку :file:`dist`:" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "После выполнения команды вы должны увидеть вывод, похожий на этот:" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"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/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "Установка нового загруженного пакета" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "Обязательно укажите свое имя пользователя в названии пакета!" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" +"pip должен установить пакет из TestPyPI, и результат должен выглядеть " +"примерно так:" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" +"В этом примере используется флаг ``--index-url``, чтобы указать TestPyPI " +"вместо живого PyPI. Кроме того, в нем указано ``no-deps``. Так как TestPyPI " +"не содержит тех же пакетов, что и живой PyPI, возможно, что попытка " +"установить зависимости может закончиться неудачей или установить что-то " +"неожиданное. Хотя наш пример не имеет зависимостей, рекомендуется избегать " +"установки зависимостей при использовании TestPyPI." + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" +"Вы можете проверить, что он был установлен правильно, импортировав пакет. " +"Убедитесь, что вы все еще находитесь в виртуальной среде, а затем запустите " +"Python:" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "и импортировать пакет:" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" +"**Поздравляем, вы упаковали и распространили проект на Python!** ✨ 🍰 ✨" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" +"Помните, что в этом руководстве показано, как загрузить ваш пакет на Test " +"PyPI, который не является постоянным хранилищем. Система Test время от " +"времени удаляет пакеты и аккаунты. Лучше всего использовать TestPyPI для " +"тестирования и экспериментов, подобных этому руководству." + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" +"Когда вы будете готовы загрузить реальный пакет в Python Package Index, вы " +"можете сделать все то же самое, что и в этом уроке, но с важными отличиями:" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" +"Выберите запоминающееся и уникальное имя для своего пакета. Не обязательно " +"добавлять имя пользователя, как это было в учебнике, но нельзя использовать " +"существующее имя." + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" +"Зарегистрируйте учетную запись на https://pypi.org - обратите внимание, что " +"это два отдельных сервера и данные для входа с тестового сервера не " +"передаются на основной сервер." + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" +"Используйте ``twine upload dist/*`` для загрузки пакета и введите свои " +"учетные данные для аккаунта, который вы зарегистрировали на настоящем PyPI. " +"Теперь, когда вы загружаете пакет в production, вам не нужно указывать ``--" +"репозиторий``; пакет будет загружен на https://pypi.org/ по умолчанию." + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" +"Установите свой пакет из настоящего PyPI с помощью ``python3 -m pip install " +"[your-package]``." + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" +"На этом этапе, если вы хотите прочитать больше об упаковке библиотек Python, " +"вот некоторые вещи, которые вы можете сделать:" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" +"Прочитайте о расширенной конфигурации для выбранного вами бэкенда сборки: " +"`Hatchling `_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" +"Более подробную практическую информацию можно найти в :doc:`guides ` на этом сайте или в :doc:`discussions ` для " +"объяснений и справочной информации по конкретным темам." + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" +"Рассмотрите инструменты для упаковки, которые предоставляют единый интерфейс " +"командной строки для управления проектом и упаковки, такие " +"как :ref:`hatch`, :ref:`flit`, :ref:`pdm` и :ref:`poetry`." + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "Примечания" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" +"Технически вы также можете создать Python пакеты без файла ``__init__.py``, " +"но они называются :doc:`namespace Package ` и считаются **продвинутой темой** (не охваченной этим учебником). " +"Если вы только начинаете с Python упаковки, рекомендуется придерживаться " +"*регулярных пакетов* и ``__init__.py`` (даже если файл пуст)." + +#~ msgid "" +#~ "This specification was originally defined in :pep:`518` and :pep:`621`." +#~ msgstr "" +#~ "Эта спецификация была первоначально определена в :pep:`518` и :pep:`621`." + +#~ msgid "" +#~ "Refer to the `pkg_resources documentation `__ for more details." +#~ msgstr "" +#~ "За более подробной информацией обратитесь к документации по " +#~ "`pkg_resources `__." + +#~ msgid "" +#~ "A complete working example of two pkg_resources-style namespace packages " +#~ "can be found in the `pkg_resources namespace example project`_." +#~ msgstr "" +#~ "Полный рабочий пример двух пакетов пространства имен в стиле " +#~ "pkg_resources можно найти в проекте `pkg_resources namespace example`_." + +#, fuzzy +#~| msgid "The ``versions`` key was added with API version 1.1." +#~ msgid "The ``project-status-reason`` key was added with API version 1.4." +#~ msgstr "Ключ ``версии`` был добавлен в API версии 1.1." + +#~ msgid "" +#~ "RECORD.jws is used for digital signatures. It is not mentioned in RECORD." +#~ msgstr "" +#~ "RECORD.jws используется для цифровых подписей. Он не упоминается в " +#~ "RECORD." + +#~ 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 "" +#~ "RECORD.p7s разрешен в качестве любезности для тех, кто предпочитает " +#~ "использовать подписи S/MIME для защиты своих колесных файлов. Она не " +#~ "упоминается в RECORD." + +#~ msgid "Signed wheel files" +#~ msgstr "Подписанные файлы колес" + +#~ 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::" +#~ msgstr "" +#~ "Файлы колес включают расширенную запись RECORD, которая позволяет " +#~ "использовать цифровые подписи. В PEP 376 RECORD изменен, чтобы включать " +#~ "безопасный хэш ``digestname=urlsafe_b64encode_nopad(digest)`` (кодировка " +#~ "urlsafe base64 без задних символов =) в качестве второго столбца вместо " +#~ "md5sum. Хешируются все возможные записи, включая любые сгенерированные " +#~ "файлы, такие как файлы .pyc, но не RECORD, который не может содержать " +#~ "свой собственный хеш. Например::" + +#~ 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." +#~ msgstr "" +#~ "Файл(ы) подписи RECORD.jws и RECORD.p7s вообще не упоминаются в RECORD, " +#~ "поскольку они могут быть добавлены только после создания RECORD. Все " +#~ "остальные файлы в архиве должны иметь правильный хэш в RECORD, иначе " +#~ "установка завершится неудачей." + +#~ 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:" +#~ msgstr "" +#~ "Если используются веб-подписи JSON, одна или несколько подписей JSON Web " +#~ "Signature JSON Serialization (JWS-JS) хранятся в файле RECORD.jws, " +#~ "примыкающем к RECORD. JWS используется для подписи RECORD путем " +#~ "включения SHA-256 хэша RECORD в качестве полезной нагрузки JSON подписи:" + +#~ msgid "(The hash value is the same format used in RECORD.)" +#~ msgstr "(Хеш-значение имеет тот же формат, что и в RECORD)" + +#~ msgid "" +#~ "If RECORD.p7s is used, it must contain a detached S/MIME format signature " +#~ "of RECORD." +#~ msgstr "" +#~ "Если используется файл RECORD.p7s, он должен содержать отделенную подпись " +#~ "RECORD в формате S/MIME." + +#~ 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." +#~ msgstr "" +#~ "Программа установки колеса не обязана понимать цифровые подписи, но " +#~ "ДОЛЖНА проверять хэши в RECORD по содержимому извлеченного файла. Когда " +#~ "программа установки сверяет хэши файлов с RECORD, отдельному средству " +#~ "проверки подписи достаточно убедиться, что RECORD соответствует подписи." + +#~ msgid "See" +#~ msgstr "Смотрите" + +#~ msgid "https://datatracker.ietf.org/doc/html/rfc7515" +#~ msgstr "https://datatracker.ietf.org/doc/html/rfc7515" + +#~ msgid "" +#~ "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" +#~ "serialization-01" +#~ msgstr "" +#~ "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" +#~ "serialization-01" + +#~ msgid "https://datatracker.ietf.org/doc/html/rfc7517" +#~ msgstr "https://datatracker.ietf.org/doc/html/rfc7517" + +#~ msgid "" +#~ "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" +#~ msgstr "" +#~ "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" + +#~ msgid "Why does wheel include attached signatures?" +#~ msgstr "Почему колесо включает в себя прикрепленные подписи?" + +#~ 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." +#~ msgstr "" +#~ "Прикрепленные подписи более удобны, чем отсоединенные, поскольку они " +#~ "путешествуют вместе с архивом. Поскольку подписываются только отдельные " +#~ "файлы, архив можно перекомпрессировать, не аннулируя подпись, или " +#~ "проверить отдельные файлы без необходимости загружать весь архив." + +#~ msgid "Why does wheel allow JWS signatures?" +#~ msgstr "Почему колесо разрешает подписи JWS?" + +#~ msgid "" +#~ "The JOSE specifications of which JWS is a part are designed to be easy to " +#~ "implement, a feature that is also one of wheel's primary design goals. " +#~ "JWS yields a useful, concise pure-Python implementation." +#~ msgstr "" +#~ "Спецификации JOSE, частью которых является JWS, разработаны для простоты " +#~ "реализации, что также является одной из основных целей дизайна Wheel. " +#~ "JWS представляет собой полезную и лаконичную реализацию на чистом Python." + +#~ msgid "Why does wheel also allow S/MIME signatures?" +#~ msgstr "Почему wheel также позволяет использовать подписи S/MIME?" + +#~ msgid "" +#~ "S/MIME signatures are allowed for users who need or want to use existing " +#~ "public key infrastructure with wheel." +#~ msgstr "" +#~ "Подписи S/MIME разрешены для пользователей, которым необходимо или " +#~ "хочется использовать существующую инфраструктуру открытых ключей с " +#~ "помощью колеса." + +#~ msgid "" +#~ "Signed packages are only a basic building block in a secure package " +#~ "update system. Wheel only provides the building block." +#~ msgstr "" +#~ "Подписанные пакеты являются лишь базовым элементом системы безопасного " +#~ "обновления пакетов. Wheel предоставляет только строительный блок." + +#~ msgid "The license expressions for these projects are:" +#~ msgstr "Лицензионные выражения для этих проектов следующие:" + +#~ msgid "TUF Support - PEP 458" +#~ msgstr "Поддержка TUF - PEP 458" + +#~ 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." +#~ msgstr "" +#~ ":pep:`458` требует, чтобы все ответы API были хэшируемыми и чтобы их " +#~ "можно было однозначно идентифицировать по пути относительно корня " +#~ "репозитория. Для репозитория Simple API целевым путем является корень " +#~ "нашего API (например, ``/простой/`` на PyPI). Это создает проблемы при " +#~ "доступе к API с помощью клиента TUF, а не напрямую с помощью стандартного " +#~ "HTTP-клиента, поскольку клиент TUF не может справиться с тем, что цель " +#~ "может иметь несколько различных представлений, которые хэшируются по-" +#~ "разному." + +#~ 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 "" +#~ ":pep:`458` не указывает, каким должен быть целевой путь для простой API, " +#~ "но TUF требует, чтобы целевые пути были \"файлоподобными\", другими " +#~ "словами, путь типа ``простой/ПРОЕКТ/`` неприемлем, потому что технически " +#~ "он указывает на каталог." + +#~ 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." +#~ msgstr "" +#~ "Спасением является то, что целевой путь не *обязательно* должен " +#~ "соответствовать URL, получаемому из Простой API, и он может быть просто " +#~ "символом, который код получения знает, как преобразовать в реальный URL, " +#~ "который нужно получить. То же самое можно сказать и о других аспектах " +#~ "фактического HTTP-запроса, таких как заголовок ``принять``." + +#~ 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." +#~ msgstr "" +#~ "В конечном счете, выяснение того, как сопоставить каталог с именем файла, " +#~ "выходит за рамки данной спецификации (но это было бы в " +#~ "рамках :pep:`458`), и данная спецификация откладывает принятие решения о " +#~ "том, как именно представлять это в метаданных :pep:`458`." + +#~ 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``." +#~ msgstr "" +#~ "Однако, похоже, что текущая ветка WIP в pip, которая пытается " +#~ "реализовать :pep:`458`, использует целевой путь типа ``простой/ПРОЕКТ/" +#~ "индекс.html``. Это можно изменить, чтобы включить версию API и формат " +#~ "сериализации, используя что-то вроде ``простой/ПРОЕКТ/vnd.pypi. " +#~ "простой.vN. ФОРМАТ``. Таким образом, формат v1 HTML будет ``простой/" +#~ "ПРОЕКТ/vnd.pypi. простой.v1.html``, а формат v1 JSON будет ``простой/" +#~ "ПРОЕКТ/vnd.pypi.простой.v1.json``." + +#~ 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." +#~ msgstr "" +#~ "В данном случае, поскольку ``текст/html`` является псевдонимом для " +#~ "``приложения/vnd.pypi. простой.v1+html`` при взаимодействии через TUF, " +#~ "скорее всего, будет разумнее нормализовать к более явному имени." + +#~ msgid "" +#~ "Likewise the ``latest`` metaversion should not be included in the " +#~ "targets, only explicitly declared versions should be supported." +#~ msgstr "" +#~ "Аналогично, метаверсия ``последней`` не должна включаться в цели, должны " +#~ "поддерживаться только явно объявленные версии." + +#~ msgid "`Vagrant `_" +#~ msgstr "`Vagrant `_" + +#, fuzzy +#~| msgid ":ref:`pyproject-toml-spec`" +#~ msgid "**Inspiration**: :ref:` pyproject-tool-table`" +#~ msgstr ":ref:`pyproject-toml-spec`" + +#~ 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." +#~ msgstr "" +#~ "Ниже корневого URL находится еще один URL для каждого отдельного проекта, " +#~ "содержащегося в репозитории. Формат этого URL - ``/<проект>/``, где " +#~ "``<проект>`` заменяется нормализованным именем проекта, поэтому проект с " +#~ "именем \"HolyGrail\" будет иметь URL вида ``/holygrail/``. В ответ на " +#~ "этот URL должна появиться корректная HTML5-страница с одним элементом " +#~ "якоря для каждого файла проекта. Атрибут href **ДОЛЖЕН** быть URL, " +#~ "который ссылается на местоположение файла для загрузки, а текст тега " +#~ "якоря **ДОЛЖЕН** совпадать с конечным компонентом пути (именем файла) в " +#~ "URL. URL **ДОЛЖЕН** включать хэш в виде фрагмента URL со следующим " +#~ "синтаксисом: ``#<хэш-имя>=<хэш-значение>``, где ``<хэш-имя>`` - строчное " +#~ "имя хэш-функции (например, ``sha256``), а ``<хэш-значение>`` - " +#~ "шестнадцатеричное кодирование дайджеста." + +#~ msgid "Adding \"Yank\" Support to the Simple API" +#~ msgstr "Добавление поддержки \"Янк\" в простой API" + +#~ msgid "Signing the distribution packages" +#~ msgstr "Подписание пакетов распространения" + +#~ msgid "" +#~ "The following job signs the distribution packages with `Sigstore`_, the " +#~ "same artifact signing system `used to sign CPython `_." +#~ msgstr "" +#~ "Следующее задание подписывает пакеты дистрибутива с помощью `Sigstore`_, " +#~ "той же системы подписи артефактов, которая `использовалась для подписи " +#~ "CPython `_." + +#~ 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 "" +#~ "Сначала используется GitHub Action `sigstore/gh-action-sigstore-python`_ " +#~ "для подписи дистрибутивных пакетов. На следующем этапе с помощью ``gh`` " +#~ "CLI создается пустой GitHub Release из текущего тега. Обратите внимание, " +#~ "что этот шаг может быть дополнительно настроен. См. документацию `gh " +#~ "release `_ в качестве ссылки." + +#~ 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." +#~ msgstr "" +#~ "Вам может потребоваться изменить права ``GITHUB_TOKEN``, чтобы разрешить " +#~ "создание релиза GitHub. Инструкции см. в документации по GitHub `_. В частности, токену необходимо разрешение ``содержимое: " +#~ "запись``." + +#~ msgid "" +#~ "Finally, the signed distributions are uploaded to the GitHub Release." +#~ msgstr "Наконец, подписанные дистрибутивы загружаются на GitHub Release." + +#~ 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." +#~ msgstr "" +#~ "Это замена для подписей GPG, поддержка которых была `удалена из PyPI " +#~ "`_. Тем не менее, " +#~ "это задание не является обязательным для загрузки в PyPI и может быть " +#~ "пропущено." + +#~ msgid "" +#~ ":pep:`639` (accepted in August 2024) has changed the way the ``license`` " +#~ "field is declared. Make sure your preferred build backend " +#~ "supports :pep:`639` before trying to apply the newer guidelines. As of " +#~ "February 2025, :doc:`setuptools ` " +#~ "and :ref:`flit ` don't support :pep:`639` " +#~ "yet." +#~ msgstr "" +#~ ":pep:`639` (принят в августе 2024 года) изменил способ объявления поля " +#~ "``лицензия``. Убедитесь, что предпочитаемый вами бэкенд сборки " +#~ "поддерживает :pep:`639`, прежде чем пытаться применить новые " +#~ "рекомендации. По состоянию на февраль 2025 года, :doc:`setuptools " +#~ "` и :ref:`flit " +#~ "` пока не поддерживают :pep:`639`." + +#~ msgid ":pep:`639` license declaration" +#~ msgstr ":pep:`639` Лицензионная декларация" + +#~ msgid "Legacy license declaration" +#~ msgstr "Декларация унаследованной лицензии" + +#~ msgid "" +#~ "This can take two forms. You can put your license in a file, " +#~ "typically :file:`LICENSE` or :file:`LICENSE.txt`, and link that file here:" +#~ msgstr "" +#~ "Это может быть сделано в двух формах. Вы можете поместить лицензию в " +#~ "файл, обычно :file:`LICENSE` или :file:`LICENSE.txt`, и сослаться на этот " +#~ "файл здесь:" + +#~ msgid "or you can write the name of the license:" +#~ msgstr "или вы можете написать название лицензии:" + +#~ msgid "" +#~ "If you are using a standard, well-known license, it is not necessary to " +#~ "use this field. Instead, you should use 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 "" +#~ "Если вы используете стандартную, хорошо известную лицензию, нет " +#~ "необходимости использовать это поле. Вместо этого следует использовать " +#~ "один из :ref:`classifiers`, начинающийся с ``License ::``. (Как правило, " +#~ "рекомендуется использовать стандартную, хорошо известную лицензию, как " +#~ "для того, чтобы избежать путаницы, так и потому, что некоторые " +#~ "организации избегают программ, лицензия которых не утверждена)." + +#~ msgid "" +#~ ":pep:`639` (accepted in August 2024) has introduced the ``license-files`` " +#~ "field. Make sure your preferred build backend supports :pep:`639` before " +#~ "declaring the field. As of February 2025, :doc:`setuptools " +#~ "` and :ref:`flit " +#~ "` don't support :pep:`639` yet." +#~ msgstr "" +#~ "В :pep:`639` (принят в августе 2024 года) появилось поле ``license-" +#~ "files``. Убедитесь, что ваш бэкенд сборки поддерживает :pep:`639`, прежде " +#~ "чем объявлять это поле. По состоянию на февраль 2025 " +#~ "года, :doc:`setuptools ` " +#~ "и :ref:`flit ` пока не " +#~ "поддерживают :pep:`639`." + +#~ msgid "" +#~ "Text string that is a valid SPDX `license expression `__ as `defined in PEP " +#~ "639 `__." +#~ msgstr "" +#~ "Текстовая строка, являющаяся действительным выражением SPDX-лицензии " +#~ "`__, как " +#~ "определено в PEP 639 `__." + +#~ msgid "The table subkeys of the ``license`` key are deprecated." +#~ msgstr "Табличные подключи ключа ``license`` устарели." + +#~ msgid "Rename dist-info-metadata in the Simple API" +#~ msgstr "Переименование dist- инфо-метаданных в простом API" + +#~ msgid "Servers" +#~ msgstr "Серверы" + +#~ 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." +#~ msgstr "" +#~ "Метаданные : ссылка:спецификация файла метаданных API `, используемые в HTML-представлении простого API, " +#~ "**ОБЯЗАТЕЛЬНО** передаются с помощью атрибута ``данные-ядро-метаданные``, " +#~ "при этом поддерживаемые значения остаются прежними." + +#~ 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." +#~ msgstr "" +#~ "Метаданные из файла метаданных API , " +#~ "используемые в JSON-представлении простого API , **МОЖНО** передавать с помощью ключа ``ядро-метаданные``, при этом " +#~ "поддерживаемые значения остаются неизменными." + +#~ 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``." +#~ msgstr "" +#~ "Для поддержки клиентов, использующих предыдущие имена ключей, HTML-" +#~ "представление **МОЖЕТ** также выдаваться с использованием ``данные-дист-" +#~ "инфо-метаданные``, и если оно это делает, то **ДОЛЖНО** соответствовать " +#~ "значению ``данные-ядро-метаданные``." + +#~ 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." +#~ msgstr "" +#~ "Клиенты, использующие любое из HTML-представлений Простого API, " +#~ "**ОБЯЗАНЫ** считывать :ref:`спецификацию файла метаданных API ` метаданные из ключа ``данные-ядро-" +#~ "метаданные``, если он присутствует. Они **МОГУТ** опционально " +#~ "использовать унаследованные ``данные-дист-инфо-метаданные``, если они " +#~ "присутствуют, но ``данные-ядро-метаданные`` отсутствуют." + +#~ 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." +#~ msgstr "" +#~ "Клиенты, потребляющие JSON-представление простого API, **ОБЯЗАНЫ** " +#~ "читать : ссылка:спецификация файла метаданных API ` метаданные из ключа ``ядро-метаданные``, если он " +#~ "присутствует. Они **МОГУТ** опционально использовать унаследованный ключ " +#~ "``дист-инфо-метаданные``, если он присутствует, а ``ядро-метаданные`` - " +#~ "нет." + +#~ 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." +#~ msgstr "" +#~ "Эта спецификация устанавливает текущую версию API на \"1.0\" и ожидает, " +#~ "что будущие спецификации, которые будут развивать простой API, будут " +#~ "увеличивать номер минорной версии." + +#~ msgid "Additional Fields for the Simple API for Package Indexes" +#~ msgstr "Дополнительные поля для простого API для индексов пакетов" + +#~ 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:" +#~ msgstr "" +#~ "Эта спецификация определяет версию 1.1 простого API репозитория. Для HTML-" +#~ "версии API нет никаких изменений по сравнению с версией 1.0. Для JSON-" +#~ "версии API сделаны следующие изменения:" + +#~ msgid "The ``api-version`` must specify version 1.1 or later." +#~ msgstr "В ``api-версия`` должна быть указана версия 1.1 или более поздняя." + +#~ msgid "" +#~ "Two new \"file information\" keys, ``size`` and ``upload-time``, are " +#~ "added to the ``files`` data." +#~ msgstr "" +#~ "В данные ``файлы`` добавлены два новых ключа \"информации о файле\", " +#~ "``размер`` и ``время загрузки``." + +#~ msgid "" +#~ "The ``versions`` and ``size`` keys are mandatory. The ``upload-time`` key " +#~ "is optional." +#~ msgstr "" +#~ "Ключи ``версии`` и ``размер`` являются обязательными. Ключ ``время " +#~ "загрузки`` является необязательным." + +#~ msgid "Additional file information" +#~ msgstr "Дополнительная информация о файле" + +#~ msgid "Two new keys are added to the ``files`` key." +#~ msgstr "К ключу ``файлы`` добавляются два новых ключа." + +#~ msgid "" +#~ "Most build backends automatically include license files in packages. See " +#~ "your backend's documentation for more details." +#~ msgstr "" +#~ "Большинство бэкендов сборки автоматически включают файлы лицензий в " +#~ "пакеты. Более подробную информацию можно найти в документации к вашему " +#~ "бэкенду." + +#~ msgid "" +#~ "In this example, after installing your project, a ``spam-cli`` command " +#~ "will be available. Executing this command will do the equivalent of " +#~ "``from spam import main_cli; main_cli()``." +#~ msgstr "" +#~ "В этом примере после установки вашего проекта будет доступна команда " +#~ "``spam-cli''. Выполнение этой команды будет эквивалентно выполнению " +#~ "команды ``from spam import main_cli; main_cli()``." + +#~ 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." +#~ msgstr "" +#~ "conda - это инструмент управления пакетами для установки `Anaconda " +#~ "`__ Python. Anaconda Python - это " +#~ "дистрибутив от `Anaconda, Inc `__, ориентированный на научное сообщество, в частности, на " +#~ "Windows, где установка бинарных расширений часто бывает затруднена." + +#~ 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." +#~ msgstr "" +#~ "Вам будет предложено ввести имя пользователя и пароль. Для имени " +#~ "пользователя используйте ``__token__``. Для пароля используйте значение " +#~ "токена, включая префикс ``pypi-``." + +#~ msgid "Update this page for build backends other than setuptools." +#~ msgstr "Обновите эту страницу для бэкендов сборки, отличных от setuptools." + +#~ msgid "" +#~ "Read the file in :file:`setup.py` and get the version. Example (from `pip " +#~ "setup.py `_)::" +#~ msgstr "" +#~ "Прочитайте файл в : файл:`setup.py` и получите версию. Пример (из `pip " +#~ "setup.py `_)::" + +#~ 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\" на " +#~ "импортное имя пакета):" + +#~ msgid "" +#~ "As of the release of setuptools 61.0.0, one can specify the version " +#~ "dynamically in the project's :file:`pyproject.toml` file." +#~ msgstr "" +#~ "Начиная с версии setuptools 61.0.0, можно динамически указывать версию в " +#~ "файле проекта :file:`pyproject.toml`." + +#~ msgid "" +#~ "Please be aware that declarative config indicators, including the " +#~ "``attr:`` directive, are not supported in parameters to :file:`setup.py`." +#~ msgstr "" +#~ "Обратите внимание, что декларативные показатели конфигурации, включая " +#~ "директиву ``attr:``, не поддерживаются в параметрах к :file:`setup.py``." + +#~ msgid "" +#~ "Use an external build tool that either manages updating both locations, " +#~ "or offers an API that both locations can use." +#~ msgstr "" +#~ "Используйте внешний инструмент сборки, который либо управляет обновлением " +#~ "в обоих местах, либо предлагает API, который могут использовать оба места." + +#~ 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 " +#~ "`_." + +#~ msgid "" +#~ "Set the value to a ``__version__`` global variable in a dedicated module " +#~ "in your project (e.g. :file:`version.py`), then have :file:`setup.py` " +#~ "read and ``exec`` the value into a variable." +#~ msgstr "" +#~ "Задайте значение глобальной переменной ``__version__`` в специальном " +#~ "модуле вашего проекта (например, :file:`version.py`), а затем " +#~ "пусть :file:`setup.py` прочитает и ``исполнит`` значение в переменной." + +#~ msgid "" +#~ "Example using this technique: `warehouse `_." +#~ msgstr "" +#~ "Пример использования этой техники: `warehouse `_." + +#~ 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``, так и код проекта." + +#~ msgid "" +#~ "An advantage with this technique is that it's not specific to Python. " +#~ "Any tool can read the version." +#~ msgstr "" +#~ "Преимущество этой техники в том, что она не привязана к Python. Любой " +#~ "инструмент может прочитать версию." + +#~ msgid "" +#~ "With this approach you must make sure that the ``VERSION`` file is " +#~ "included in all your source and binary distributions (e.g. add ``include " +#~ "VERSION`` to your :file:`MANIFEST.in`)." +#~ msgstr "" +#~ "При таком подходе вы должны убедиться, что файл ``VERSION`` включен во " +#~ "все ваши исходные и бинарные дистрибутивы (например, добавьте ``include " +#~ "VERSION`` в ваш :file:`MANIFEST.in``)." + +#~ 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::" +#~ msgstr "" +#~ "Задайте значение в :file:`setup.py`, а код проекта пусть использует API " +#~ "``importlib.metadata`` для получения значения во время выполнения. " +#~ "(``importlib.metadata`` был представлен в Python 3.8 и доступен для более " +#~ "старых версий в виде проекта ``importlib-metadata``). Версия " +#~ "установленного проекта может быть получена с помощью API следующим " +#~ "образом::" + +#~ msgid "" +#~ "Be aware that the ``importlib.metadata`` API only knows about what's in " +#~ "the installation metadata, which is not necessarily the code that's " +#~ "currently imported." +#~ msgstr "" +#~ "Имейте в виду, что API ``importlib.metadata`` знает только о том, что " +#~ "находится в метаданных установки, а это не обязательно код, который " +#~ "импортируется в данный момент." + +#~ msgid "" +#~ "If a project uses this method to fetch its version at runtime, then its " +#~ "``install_requires`` value needs to be edited to install ``importlib-" +#~ "metadata`` on pre-3.8 versions of Python like so::" +#~ msgstr "" +#~ "Если проект использует этот метод для получения своей версии во время " +#~ "выполнения, то его значение ``install_requires`` должно быть " +#~ "отредактировано для установки ``importlib-metadata`` на версии Python до " +#~ "3.8 следующим образом::" + +#~ msgid "" +#~ "An older (and less efficient) alternative to ``importlib.metadata`` is " +#~ "the ``pkg_resources`` API provided by ``setuptools``::" +#~ msgstr "" +#~ "Более старой (и менее эффективной) альтернативой ``importlib.metadata`` " +#~ "является API ``pkg_resources``, предоставляемый ``setuptools``::" + +#~ 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`` для получения собственной версии " +#~ "во время выполнения, то ``setuptools`` должен быть добавлен в список " +#~ "``install_requires`` проекта." + +#~ msgid "" +#~ "Example using this technique: `setuptools `_." +#~ msgstr "" +#~ "Пример использования этой техники: `setuptools `_." + +#~ msgid "" +#~ "Set the value to ``__version__`` in ``sample/__init__.py`` and import " +#~ "``sample`` in :file:`setup.py`." +#~ msgstr "" +#~ "Установите значение ``__version__`` в файле ``sample/__init__.py`` и " +#~ "импортируйте ``sample`` в :file:`setup.py``." + +#~ msgid "" +#~ "Although this technique is common, beware that it will fail if ``sample/" +#~ "__init__.py`` imports packages from ``install_requires`` dependencies, " +#~ "which will very likely not be installed yet when :file:`setup.py` is run." +#~ msgstr "" +#~ "Хотя эта техника широко распространена, помните, что она не сработает, " +#~ "если ``sample/__init__.py`` импортирует пакеты из зависимостей " +#~ "``install_requires``, которые, скорее всего, еще не будут установлены на " +#~ "момент запуска :file:`setup.py``." + +#~ 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 `_." +#~ msgstr "" +#~ "Храните номер версии в тегах системы контроля версий (Git, Mercurial и " +#~ "т.д.), а не в коде, и автоматически извлекайте его оттуда с помощью " +#~ "`setuptools_scm `_." + +#~ 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]``. Первая должна присутствовать всегда, независимо от того, " +#~ "какой бэкенд сборки вы используете (поскольку она *определяет* " +#~ "инструмент, который вы используете). Вторая понимается *большинством* " +#~ "бэкендов сборки, но некоторые бэкенды используют другой формат." + +#~ 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." +#~ msgstr "" +#~ "Это руководство предназначено специально для " +#~ "пользователей :ref:`setuptools`, другие инструменты упаковки, такие как " +#~ "``flit``, могут предлагать аналогичную функциональность, но пользователям " +#~ "необходимо обратиться к соответствующей документации." + +#~ msgid "This workflow requires that:" +#~ msgstr "Этот рабочий процесс требует, чтобы:" + +#~ msgid "The publisher is using the latest version of :ref:`setuptools`," +#~ msgstr "Издатель использовал последнюю версию :ref:`setuptools`," + +#~ msgid "The latest version of :ref:`twine` is used to upload the package," +#~ msgstr "Для загрузки пакета использовалась последняя версия :ref:`twine`," + +#~ 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." +#~ msgstr "" +#~ "Поскольку настройки :file:`setup.cfg` можно переопределить с помощью " +#~ "флагов CLI, убедитесь, что в ваших скриптах создания пакетов нет ``--" +#~ "universal``." + +#~ msgid "1. Download the newest version of Setuptools" +#~ msgstr "1. Скачайте новейшую версию Setuptools" + +#~ msgid "" +#~ "Ensure that before you generate source distributions or binary " +#~ "distributions, you update Setuptools and install twine." +#~ msgstr "" +#~ "Убедитесь, что перед созданием дистрибутивов исходных кодов или двоичных " +#~ "дистрибутивов вы обновили Setuptools и установили twine." + +#~ msgid "Steps:" +#~ msgstr "Шаги:" + +#~ msgid "``setuptools`` version should be above 24.0.0." +#~ msgstr "``setuptools`` версия должна быть выше 24.0.0." + +#~ msgid "" +#~ "The way to set those values is within the call to ``setup`` within " +#~ "your :file:`setup.py` script. This will insert the ``Requires-Python`` " +#~ "metadata values based on the argument you provide in ``python_requires``." +#~ msgstr "" +#~ "Установить эти значения можно с помощью вызова ``setup`` в вашем " +#~ "скрипте :file:`setup.py``. Он вставит значения метаданных ``Requires-" +#~ "Python`` на основе аргумента, указанного в ``python_requires``." + +#~ msgid "4. Using Twine to publish" +#~ msgstr "4. Используйте Twine для публикации" + +#~ msgid "" +#~ "Twine has a number of advantages, apart from being faster it is now the " +#~ "supported method for publishing packages." +#~ msgstr "" +#~ "Twine имеет ряд преимуществ, кроме того, что он быстрее, теперь это " +#~ "поддерживаемый метод для публикации пакетов." + +#~ msgid "Make sure you are using the newest version of Twine, at least 1.9." +#~ msgstr "" +#~ "Убедитесь, что вы используете новейшую версию Twine, по крайней мере, 1,9." + +#~ msgid "" +#~ "Once you have published a package with the Requires-Python metadata, you " +#~ "can then make a further update removing that Python runtime from support." +#~ msgstr "" +#~ "После того, как вы опубликовали пакет с метаданными Needs-Python, вы " +#~ "можете сделать еще одно обновление, удалив время выполнения Python из " +#~ "поддержки." + +#~ msgid "It must be done in this order for the automated fallback to work." +#~ msgstr "" +#~ "Чтобы автоматический откат сработал, его нужно выполнить именно в таком " +#~ "порядке." + +#~ msgid "" +#~ "For example, you published the Requires-Python: \">=2.7\" as version " +#~ "1.0.0 of your package." +#~ msgstr "" +#~ "Например, вы опубликовали Needs-Python: «>=2.7» в качестве версии 1.0.0 " +#~ "вашего пакета." + +#~ 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." + +#~ msgid "The summary description of the project." +#~ msgstr "Краткое описание проекта." + +#~ msgid "Wheel vs Egg" +#~ msgstr "Колеса против яиц" + +#~ 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 "" +#~ ":термин: `Wheel' и :term:`Egg' - это оба формата упаковки, которые " +#~ "направлены на поддержку случая использования объекта установки, который " +#~ "не требует строительства или компиляции, что может быть дорогостоящим в " +#~ "тестировании и производстве рабочих процессов." + +#~ msgid "" +#~ ":term:`Wheel` is currently considered the standard for :term:`built " +#~ "` and :term:`binary ` packaging " +#~ "for Python." +#~ msgstr "" +#~ ":term:`Wheel` в настоящее время считается стандартом для :term:`built " +#~ "` и :term:`binary ` упаковки для " +#~ "Python." + +#~ msgid "" +#~ ":term:`Egg` uploads have been disabled for upload to PyPI, " +#~ "per :pep:`715`. Read the `deprecation notice `_ for more information." +#~ msgstr "" +#~ "Загрузки :term:`Egg` были отключены для загрузки в PyPI, " +#~ "согласно :pep:`715`. Для получения дополнительной информации читайте " +#~ "уведомление о депривации `_." + +#~ 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:`Built Distribution`, введенный официальной " +#~ "спецификацией :doc:`standard specification `, который призван заменить формат :term:`Egg`. В " +#~ "настоящее время Wheel поддерживается :ref:`pip`." + +#~ msgid "" +#~ "If you're familiar with Python packaging and installation, and just want " +#~ "to know what tools are currently recommended, then here it is." +#~ msgstr "" +#~ "Если вы знакомы с упаковкой и установкой Python и просто хотите узнать, " +#~ "какие инструменты сейчас рекомендуются, то вам сюда." + +#~ msgid "Application dependency management" +#~ msgstr "Управление зависимостями приложения" + +#~ msgid "" +#~ "Use :ref:`pip` in a `secure manner`_ to install a Python application and " +#~ "its dependencies during deployment." +#~ msgstr "" +#~ "Используйте :ref:`pip` `безопасным способом`_ для установки приложения " +#~ "Python и его зависимостей во время развертывания." + +#~ msgid "" +#~ "Use :ref:`virtualenv` or :doc:`venv ` to isolate " +#~ "application-specific dependencies from a shared Python installation. [4]_" +#~ msgstr "" +#~ "Используйте :ref:`virtualenv` или :doc:`venv ` для " +#~ "изоляции специфических для приложения зависимостей от общей установки " +#~ "Python. [4]_" + +#~ msgid "" +#~ "Use `pip-tools`_, :ref:`pipenv`, or `poetry`_ to generate the fully-" +#~ "specified application-specific dependencies, when developing Python " +#~ "applications." +#~ msgstr "" +#~ "Используйте `pip-tools`_, :ref:`pipenv` или `poetry`_ для генерации " +#~ "полностью определенных зависимостей, специфичных для приложения, при " +#~ "разработке приложений на Python." + +#~ msgid "Installation tool recommendations" +#~ msgstr "Рекомендации по инструментам установки" + +#~ msgid "" +#~ "Use :ref:`pip` to install Python :term:`packages ` " +#~ "from :term:`PyPI `. [1]_ [2]_ Depending on " +#~ "how :ref:`pip` is installed, you may need to also install :ref:`wheel` to " +#~ "get the benefit of wheel caching. [3]_" +#~ msgstr "" +#~ "Используйте :ref:`pip` для установки Python :term:`packages " +#~ "<Дистрибутивный пакет>` из :term:`PyPI <Индекс пакетов Python (PyPI)>`. " +#~ "[1]_ [2]_ В зависимости от того, как установлен :ref:`pip`, вам может " +#~ "потребоваться также установить :ref:`wheel`, чтобы получить преимущества " +#~ "кэширования колес. [3]_" + +#~ msgid "" +#~ "Use :ref:`virtualenv` or :doc:`venv ` to isolate " +#~ "project-specific dependencies from a shared Python installation. [4]_" +#~ msgstr "" +#~ "Используйте :ref:`virtualenv` или :doc:`venv `, " +#~ "чтобы изолировать специфические для проекта зависимости от общей " +#~ "установки Python. [4]_" + +#~ msgid "" +#~ "If you're looking for management of fully integrated cross-platform " +#~ "software stacks, consider:" +#~ msgstr "" +#~ "Если вам требуется управление полностью интегрированными " +#~ "кроссплатформенными программными стеками, рассмотрите этот вариант:" + +#~ msgid ":ref:`buildout`: primarily focused on the web development community" +#~ msgstr "" +#~ ":ref:`buildout`: в первую очередь ориентирован на сообщество веб-" +#~ "разработчиков" + +#~ msgid "" +#~ ":ref:`spack`, :ref:`hashdist`, or :ref:`conda`: primarily focused on the " +#~ "scientific community." +#~ msgstr "" +#~ ":ref:`spack`, :ref:`hashdist` или :ref:`conda`: в первую очередь " +#~ "ориентированы на научное сообщество." + +#~ msgid "Packaging tool recommendations" +#~ msgstr "Рекомендации по инструментам упаковки" + +#~ msgid "Use :ref:`setuptools` to define projects. [5]_ [6]_" +#~ msgstr "Используйте :ref:`setuptools` для определения проектов. [5]_ [6]_" + +#~ msgid "" +#~ "Use :ref:`build` to create :term:`Source Distributions ` and :term:`wheels `." +#~ msgstr "" +#~ "Используйте :ref:`build` для создания :term:`Source Distributions ` и :term:`wheels `." + +#~ msgid "" +#~ "Use `twine `_ for uploading distributions " +#~ "to :term:`PyPI `." +#~ msgstr "" +#~ "Используйте `twine `_ для загрузки " +#~ "дистрибутивов в :term:`PyPI `." + +#~ msgid "Publishing platform migration" +#~ msgstr "Миграция издательской платформы" + +#~ msgid "" +#~ "The original Python Package Index implementation (previously hosted at " +#~ "`pypi.python.org `_) has been phased out in " +#~ "favour of an updated implementation hosted at `pypi.org `_." +#~ msgstr "" +#~ "Оригинальная реализация Python Package Index (ранее размещавшаяся по " +#~ "адресу `pypi.python.org `_) была постепенно " +#~ "отменена в пользу обновленной реализации, размещенной по адресу `pypi.org " +#~ "`_." + +#~ msgid "" +#~ "See :ref:`Migrating to PyPI.org` for more information on the status of " +#~ "the migration, and what settings to change in your clients." +#~ msgstr "" +#~ "Смотрите :ref:`Миграция на PyPI.org` для получения дополнительной " +#~ "информации о статусе миграции и о том, какие настройки следует изменить в " +#~ "ваших клиентах." + +#~ msgid "" +#~ "There are some cases where you might choose to use ``easy_install`` " +#~ "(from :ref:`setuptools`), e.g. if you need to install from :term:`Eggs " +#~ "` (which pip doesn't support). For a detailed breakdown, " +#~ "see :ref:`pip vs easy_install`." +#~ msgstr "" +#~ "В некоторых случаях вы можете использовать ``easy_install`` " +#~ "(из :ref:`setuptools``), например, если вам нужно установить " +#~ "из :term:`Eggs ` (что pip не поддерживает). Подробное описание " +#~ "смотрите в :ref:`pip vs easy_install`." + +#~ msgid "" +#~ "The acceptance of :pep:`453` means that :ref:`pip` will be available by " +#~ "default in most installations of Python 3.4 or later. See " +#~ "the :pep:`rationale section <453#rationale>` from :pep:`453` as for why " +#~ "pip was chosen." +#~ msgstr "" +#~ "Принятие :pep:`453` означает, что :ref:`pip` будет доступен по умолчанию " +#~ "в большинстве установок Python 3.4 или более поздних версий. О том, " +#~ "почему был выбран pip, читайте в разделе <453#rationale> из :pep:`453`." + +#~ msgid "" +#~ "`get-pip.py `_ " +#~ "and :ref:`virtualenv` install :ref:`wheel`, whereas :ref:`ensurepip` " +#~ "and :ref:`venv ` do not currently. Also, the common \"python-pip\" " +#~ "package that's found in various linux distros, does not depend on " +#~ "\"python-wheel\" currently." +#~ msgstr "" +#~ "`get-pip.py `_ " +#~ "и :ref:`virtualenv` устанавливают :ref:`wheel`, тогда " +#~ "как :ref:`ensurepip` и :ref:`venv ` в настоящее время не " +#~ "устанавливают. Кроме того, распространенный пакет \"python-pip\", " +#~ "который можно найти в различных дистрибутивах linux, в настоящее время не " +#~ "зависит от \"python-wheel\"." + +#~ msgid "" +#~ "Beginning with Python 3.4, ``venv`` will create virtualenv environments " +#~ "with ``pip`` installed, thereby making it an equal alternative " +#~ "to :ref:`virtualenv`. However, using :ref:`virtualenv` will still be " +#~ "recommended for users that need cross-version consistency." +#~ msgstr "" +#~ "Начиная с Python 3.4, ``venv`` будет создавать среды virtualenv с " +#~ "установленным ``pip``, тем самым делая его равноправной " +#~ "альтернативой :ref:`virtualenv``. Тем не менее, " +#~ "использование :ref:`virtualenv` по-прежнему рекомендуется для " +#~ "пользователей, которым необходима кросс-версионная согласованность." + +#~ msgid "" +#~ "Although you can use pure :ref:`distutils` for many projects, it does not " +#~ "support defining dependencies on other projects and is missing several " +#~ "convenience utilities for automatically populating distribution metadata " +#~ "correctly that are provided by ``setuptools``. Being outside the standard " +#~ "library, ``setuptools`` also offers a more consistent feature set across " +#~ "different versions of Python, and (unlike ``distutils``), recent versions " +#~ "of ``setuptools`` support all of the modern metadata fields described " +#~ "in :ref:`core-metadata`." +#~ msgstr "" +#~ "Хотя вы можете использовать чистый :ref:`distutils` для многих проектов, " +#~ "он не поддерживает определение зависимостей от других проектов и лишен " +#~ "нескольких удобных утилит для автоматического заполнения метаданных " +#~ "дистрибутива, которые предоставляются ``setuptools``. Находясь вне " +#~ "стандартной библиотеки, ``setuptools`` также предлагает более " +#~ "согласованный набор функций в разных версиях Python, и (в отличие от " +#~ "``distutils``) последние версии ``setuptools`` поддерживают все " +#~ "современные поля метаданных, описанные в :ref:`core-metadata``." + +#~ msgid "" +#~ "Even for projects that do choose to use ``distutils``, when :ref:`pip` " +#~ "installs such projects directly from source (rather than installing from " +#~ "a prebuilt :term:`wheel ` file), it will actually build your " +#~ "project using :ref:`setuptools` instead." +#~ msgstr "" +#~ "Даже для проектов, которые решили использовать ``distutils``, " +#~ "когда :ref:`pip` устанавливает такие проекты непосредственно из исходного " +#~ "кода (а не устанавливает из предварительно собранного файла :term:`wheel " +#~ "`), он фактически соберет ваш проект, используя вместо " +#~ "этого :ref:`setuptools``." + +#~ msgid "" +#~ "`distribute`_ (a fork of setuptools) was merged back " +#~ "into :ref:`setuptools` in June 2013, thereby making setuptools the " +#~ "default choice for packaging." +#~ msgstr "" +#~ "`distribute`_ (форк setuptools) был объединен обратно в :ref:`setuptools` " +#~ "в июне 2013 года, тем самым сделав setuptools выбором по умолчанию для " +#~ "упаковки." + +#~ msgid "Standards compliance for interoperability" +#~ msgstr "Соответствие стандартам совместимости" + +#~ msgid "Here are some examples of compliant version numbers::" +#~ msgstr "Вот несколько примеров совместимых номеров версий::" + +#~ msgid "" +#~ "To further accommodate historical variations in approaches to version " +#~ "numbering, :pep:`440` also defines a comprehensive technique " +#~ "for :pep:`version normalisation <440#normalization>` that maps variant " +#~ "spellings of different version numbers to a standardised canonical form." +#~ msgstr "" +#~ "Для дальнейшего учета исторических вариаций в подходах к нумерации " +#~ "версий, :pep:`440` также определяет комплексную технику " +#~ "нормализации :pep:`версий <440#normalization>`, которая отображает " +#~ "варианты написания различных номеров версий в стандартизированную " +#~ "каноническую форму." + +#~ msgid "Scheme choices" +#~ msgstr "Выбор схемы" + +#~ msgid "" +#~ "For new projects, the recommended versioning scheme is based on `Semantic " +#~ "Versioning `_, but adopts a different approach to " +#~ "handling pre-releases and build metadata." +#~ msgstr "" +#~ "Для новых проектов рекомендуемая схема версионирования основана на " +#~ "`Semantic Versioning `_, но использует другой подход " +#~ "к работе с пре-релизами и метаданными сборки." + +#~ msgid "" +#~ "Adopting this approach as a project author allows users to make use " +#~ "of :pep:`\"compatible release\" <440#compatible-release>` specifiers, " +#~ "where ``name ~= X.Y`` requires at least release X.Y, but also allows any " +#~ "later release with a matching MAJOR version." +#~ msgstr "" +#~ "Принятие такого подхода автором проекта позволяет пользователям " +#~ "использовать спецификаторы :pep:`\"compatible release\" <440#compatible-" +#~ "release>`, где ``name ~= X.Y`` требует как минимум релиза X.Y, но также " +#~ "позволяет использовать любой более поздний релиз с соответствующей MAJOR-" +#~ "версией." + +#~ msgid "Date based versioning" +#~ msgstr "Версионирование на основе дат" + +#~ msgid "" +#~ "Version numbers for date based projects typically take the form of " +#~ "YEAR.MONTH (for example, ``12.04``, ``15.10``)." +#~ msgstr "" +#~ "Номера версий для проектов, основанных на дате, обычно имеют вид " +#~ "YEAR.MONTH (например, ``12.04``, ``15.10``)." + +#~ msgid "" +#~ "This is the simplest possible versioning scheme, and consists of a single " +#~ "number which is incremented every release." +#~ msgstr "" +#~ "Это простейшая схема версионирования, состоящая из одного числа, которое " +#~ "увеличивается при каждом выпуске." + +#~ msgid "Pre-release versioning" +#~ msgstr "Версионирование предварительных выпусков" + +#~ msgid "" +#~ "Regardless of the base versioning scheme, pre-releases for a given final " +#~ "release may be published as:" +#~ msgstr "" +#~ "Независимо от базовой схемы версий, предварительные выпуски для данного " +#~ "финального выпуска могут быть опубликованы как:" + +#~ msgid "zero or more dev releases (denoted with a \".devN\" suffix)" +#~ msgstr "ноль или более выпусков dev (обозначаются суффиксом \".devN\")" + +#~ msgid "zero or more alpha releases (denoted with a \".aN\" suffix)" +#~ msgstr "ноль или более альфа-релизов (обозначаются суффиксом \".aN\")" + +#~ msgid "zero or more beta releases (denoted with a \".bN\" suffix)" +#~ msgstr "ноль или более бета-версий (обозначаются суффиксом \".bN\")" + +#~ msgid "zero or more release candidates (denoted with a \".rcN\" suffix)" +#~ msgstr "" +#~ "ноль или более кандидатов на выпуск (обозначаются суффиксом \".rcN\")" + +#~ msgid "" +#~ "``pip`` and other modern Python package installers ignore pre-releases by " +#~ "default when deciding which versions of dependencies to install." +#~ msgstr "" +#~ "``pip`` и другие современные программы установки пакетов Python по " +#~ "умолчанию игнорируют предварительные выпуски, когда решают, какие версии " +#~ "зависимостей устанавливать." + +#~ msgid "" +#~ "A local version identifier takes the form ``+``. For example::" +#~ msgstr "" +#~ "Идентификатор локальной версии имеет вид ``<идентификатор публичной " +#~ "версии>+<метка локальной версии>``. Например::" + +#~ msgid "Three options are available in this area:" +#~ msgstr "В этой области доступны три варианта:" + +#~ msgid "pip provides local caching options," +#~ msgstr "pip предоставляет возможности локального кэширования," + +#~ msgid "" +#~ "devpi provides higher-level caching option, potentially shared amongst " +#~ "many users or machines, and" +#~ msgstr "" +#~ "devpi предоставляет возможность кэширования более высокого уровня, " +#~ "потенциально разделяемого между многими пользователями или машинами, и" + +#~ msgid "" +#~ "bandersnatch provides a local complete mirror of all PyPI :term:`packages " +#~ "`." +#~ msgstr "" +#~ "bandersnatch предоставляет локальное полное зеркало всех " +#~ "PyPI :term:`packages `." + +#~ msgid "Caching with devpi" +#~ msgstr "Кэширование с помощью devpi" + +#~ msgid "" +#~ "devpi is a caching proxy server which you run on your laptop, or some " +#~ "other machine you know will always be available to you. See the `devpi " +#~ "documentation for getting started`__." +#~ msgstr "" +#~ "devpi - это кэширующий прокси-сервер, который вы запускаете на своем " +#~ "ноутбуке или другой машине, которая, как вы знаете, всегда будет доступна " +#~ "для вас. Для начала работы смотрите документацию `devpi`." + +#~ msgid "Complete mirror with bandersnatch" +#~ msgstr "Зеркало в комплекте с бандерснатчем" + +#~ msgid "" +#~ "bandersnatch will set up a complete local mirror of all " +#~ "PyPI :term:`packages ` (externally-hosted packages " +#~ "are not mirrored). See the `bandersnatch documentation for getting that " +#~ "going`__." +#~ msgstr "" +#~ "bandersnatch создаст полное локальное зеркало всех пакетов " +#~ "PyPI :term:`packages ` (пакеты, размещенные на " +#~ "внешних хостингах, не зеркалируются). См. документацию `bandersnatch о " +#~ "том, как это сделать`__." + +#~ msgid "" +#~ "A benefit of devpi is that it will create a mirror which " +#~ "includes :term:`packages ` that are external to " +#~ "PyPI, unlike bandersnatch which will only cache :term:`packages " +#~ "` hosted on PyPI." +#~ msgstr "" +#~ "Преимущество devpi в том, что он создаст зеркало, " +#~ "включающее :term:`пакеты `, которые являются " +#~ "внешними по отношению к PyPI, в отличие от bandersnatch, который будет " +#~ "кэшировать только :term:`пакеты `, размещенные на " +#~ "PyPI." + +#, fuzzy +#~ msgid "" +#~ "By default, any hash algorithm available via `hashlib `_ (specifically any that can be " +#~ "passed to ``hashlib.new()`` and do not require additional parameters) can " +#~ "be used as a key for the hashes dictionary. At least one secure algorithm " +#~ "from ``hashlib.algorithms_guaranteed`` **SHOULD** always be included. At " +#~ "the time of this spec, ``sha256`` specifically is recommended." +#~ msgstr "" +#~ "В качестве ключа для словаря хэшей можно использовать любой алгоритм, " +#~ "доступный через ``hashlib`` (в частности, все те, которые можно передать " +#~ "в ``hashlib.new()`` и которые не требуют дополнительных параметров). По " +#~ "крайней мере, один безопасный алгоритм из " +#~ "``hashlib.algorithms_guaranteed`` ДОЛЖЕН быть всегда включен. На момент " +#~ "написания статьи рекомендуется использовать ``sha256``." + +#~ msgid "" +#~ "This specification has been **provisionally accepted**. It is subject to " +#~ "being changed or abandoned. See the `PEP 723 conditional acceptance " +#~ "thread `_ for details." +#~ msgstr "" +#~ "Эта спецификация была **временно принята**. Она может быть изменена или " +#~ "отменена. Подробности см. в ветке `PEP 723 условное принятие `_." + +#~ msgid "This document MAY include the ``[run]`` and ``[tool]`` tables." +#~ msgstr "Этот документ МОЖЕТ включать таблицы ``[run]`` и ``[tool]``." + +#~ msgid "" +#~ "The :ref:`tool table ` MAY be used by any tool, " +#~ "script runner or otherwise, to configure behavior." +#~ msgstr "" +#~ "Таблица инструментов ` МОЖЕТ быть использована " +#~ "любым инструментом, программой запуска скриптов или иным способом, для " +#~ "настройки поведения." + +#~ msgid "The ``[run]`` table MAY include the following optional fields:" +#~ msgstr "Таблица ``[run]`` МОЖЕТ включать следующие необязательные поля:" + +#~ msgid "" +#~ "Any future specifications that define additional fields for the ``[run]`` " +#~ "table when used in a ``pyproject.toml`` file MUST include the " +#~ "aforementioned fields exactly as specified. The fields defined by this " +#~ "specification are equally as applicable to full-fledged projects as they " +#~ "are to single-file scripts." +#~ msgstr "" +#~ "Любые будущие спецификации, определяющие дополнительные поля для таблицы " +#~ "``[run]`` при использовании в файле ``pyproject.toml``, ДОЛЖНЫ включать " +#~ "вышеупомянутые поля именно в том виде, в котором они указаны. Поля, " +#~ "определенные этой спецификацией, одинаково применимы как к полноценным " +#~ "проектам, так и к однофайловым скриптам." + +#~ msgid "" +#~ "The following is an example of a proposed syntax for single-file Rust " +#~ "projects that embeds their equivalent of ``pyproject.toml``, which is " +#~ "called ``Cargo.toml``:" +#~ msgstr "" +#~ "Ниже приведен пример предлагаемого синтаксиса для однофайловых проектов " +#~ "Rust, в которые встраивается эквивалент ``pyproject.toml``, который " +#~ "называется ``Cargo.toml``:" + +#~ msgid "" +#~ "pex is both a library and tool for generating :file:`.pex` (Python " +#~ "EXecutable) files, standalone Python environments in the spirit " +#~ "of :ref:`virtualenv`. :file:`.pex` files are just carefully constructed " +#~ "zip files with a ``#!/usr/bin/env python`` and " +#~ "special :file:`__main__.py`, and are designed to make deployment of " +#~ "Python applications as simple as ``cp``." +#~ msgstr "" +#~ "pex - это библиотека и инструмент для создания :file:`.pex` (Python " +#~ "EXecutable) файлов, автономных окружений Python в " +#~ "духе :ref:`virtualenv`. :file:`.pex` файлы - это просто тщательно " +#~ "сконструированные zip файлы с ``#!/usr/bin/env python`` и " +#~ "специальным :file:`__main__.py``, и предназначены для того, чтобы сделать " +#~ "развертывание Python приложений таким же простым, как ``cp``." + +#~ msgid "" +#~ "The HTML format is defined in :pep:`503`, with the addition of \"yank\" " +#~ "support (allowing a kind of file deletion) in :pep:`592`, specifying the " +#~ "interface version provided by an index server in :pep:`629`, and " +#~ "providing package metadata independently from a package in :pep:`658` and " +#~ "revised in :pep:`714`." +#~ msgstr "" +#~ "Формат HTML определен в :pep:`503`, с добавлением поддержки \"yank\" " +#~ "(позволяющей удалять файлы) в :pep:`592`, указанием версии интерфейса, " +#~ "предоставляемого индексным сервером в :pep:`629`, предоставлением " +#~ "метаданных пакета независимо от пакета в :pep:`658` и пересмотром " +#~ "в :pep:`714`." + +#~ msgid "" +#~ "If you're developing for a \"Platform-as-a-Service\" or \"PaaS\" like " +#~ "Heroku or Google App Engine, you are going to want to follow their " +#~ "respective packaging guides." +#~ msgstr "" +#~ "Если вы разрабатываете для \"платформы как сервиса\" или PaaS, например, " +#~ "Heroku или Google App Engine, вам нужно следовать их соответствующим " +#~ "руководствам по упаковке." + +#~ msgid "" +#~ "`Heroku `_" +#~ msgstr "" +#~ "`Heroku `_" + +#~ msgid "" +#~ "`Google App Engine `_" +#~ msgstr "" +#~ "`Google App Engine `_" + +#~ msgid "`PythonAnywhere `_" +#~ msgstr "`PythonAnywhere `_" + +#~ msgid "`OpenShift `_" +#~ msgstr "`OpenShift `_" + +#~ msgid "\"Serverless\" frameworks like :gh:`Zappa `" +#~ msgstr "\"Бессерверные\" фреймворки, такие как :gh:`Zappa `" + +#~ msgid "" +#~ "The name of the distribution. The name field is the primary identifier " +#~ "for a distribution. A valid name consists only of ASCII letters and " +#~ "numbers, period, underscore and hyphen. It must start and end with a " +#~ "letter or number. Distribution names are limited to those which match the " +#~ "following regex (run with ``re.IGNORECASE``)::" +#~ msgstr "" +#~ "Имя дистрибутива. Поле имени является основным идентификатором " +#~ "дистрибутива. Правильное имя состоит только из букв и цифр ASCII, точки, " +#~ "подчеркивания и дефиса. Оно должно начинаться и заканчиваться буквой или " +#~ "цифрой. Имена дистрибутивов ограничены теми, которые соответствуют " +#~ "следующему regex (выполняется с ``re.IGNORECASE``)::" + +#, fuzzy +#~ msgid "``author``" +#~ msgstr "Автор" + +#, fuzzy +#~ msgid "``python_requires``" +#~ msgstr "python_requires" + +#~ msgid "And so on." +#~ msgstr "И так далее." + +#~ msgid "``entry_points``" +#~ msgstr "``entry_points``" + +#, fuzzy +#~ msgid "``console_scripts``" +#~ msgstr "console_scripts" + +#~ msgid "Rationale" +#~ msgstr "Обоснование" + +#~ msgid "``python -m twine check``" +#~ msgstr "``python -m twine check``" + +#~ msgid "``python -m twine register``" +#~ msgstr "``python -m twine register``" + +#~ msgid "``python -m twine upload``" +#~ msgstr "``python -m twine upload``" + +#~ msgid "``python -m setuptools-scm``" +#~ msgstr "``python -m setuptools-scm``" + +#, fuzzy +#~ msgid ":ref:`declaring-build-dependencies`" +#~ msgstr "Объявление зависимостей системы сборки" + +#, fuzzy +#~ msgid "Current recommendation" +#~ msgstr "Рекомендации по инструментам" + +#, fuzzy +#~ msgid "You can make sure that pip is up-to-date by running:" +#~ msgstr "" +#~ "Установщики Python для Windows включают pip. Вы можете убедиться, что pip " +#~ "обновлён до последней версии, запустив:" + +#~ msgid "Installing pip" +#~ msgstr "Установка pip" + +#~ msgid "Installing virtualenv" +#~ msgstr "Установка virtualenv" + +#, fuzzy +#~ msgid "mention the implications of the GIL for extension modules" +#~ msgstr "Введение в модули расширения на C/C++" + +#~ msgid "" +#~ "Essential tools and concepts for working within the Python development " +#~ "ecosystem are covered in our :doc:`tutorials/index` section:" +#~ msgstr "" +#~ "Основные инструменты и концепции для работы в экосистеме разработки " +#~ "Python описаны в нашем разделе :doc:`tutorials/index`:" + +#~ msgid "Learn more" +#~ msgstr "Подробнее" + +#~ msgid "" +#~ "Beyond our :doc:`tutorials/index`, this guide has several other resources:" +#~ msgstr "" +#~ "Помимо наших :doc:`учебников ` это руководство содержит " +#~ "несколько других ресурсов:" + +#, fuzzy +#~ msgid "" +#~ "`Docs `__ | `Issues " +#~ "`__" +#~ msgstr "" +#~ "`Документация `__ | " +#~ "`Замечания `__" + +#~ msgid "Debian/Ubuntu" +#~ msgstr "Debian/Ubuntu" + +#~ msgid "2014-11-11" +#~ msgstr "2014-11-11" + +#~ msgid "2015-09-17" +#~ msgstr "2015-09-17" + +#~ msgid "Fedora 21:" +#~ msgstr "Fedora 21:" + +#~ msgid "Python 3: ``sudo yum install python3 python3-wheel``" +#~ msgstr "Python 3: ``sudo yum install python3 python3-wheel``" + +#~ msgid "Fedora 22:" +#~ msgstr "Fedora 22:" + +#~ msgid "Python 3: ``sudo dnf install python3 python3-wheel``" +#~ msgstr "Python 3: ``sudo dnf install python3 python3-wheel``" + +#~ msgid "Python 3::" +#~ msgstr "Python 3::" + +#~ msgid "For Python 2.7" +#~ msgstr "Для Python 2.7" + +#~ msgid "Done." +#~ msgstr "Готово." + +#~ msgid "For Python 3.4" +#~ msgstr "Для Python 3.4" + +#~ msgid "Set DISTUTILS_USE_SDK=1" +#~ msgstr "Установите DISTUTILS_USE_SDK=1" + +#~ msgid "For Python 3.5" +#~ msgstr "Для Python 3.5" + +#~ msgid "bento" +#~ msgstr "bento" + +#~ msgid "`Docs `__" +#~ msgstr "`Документация `__" + +#~ msgid "`Enthought Canopy `_" +#~ msgstr "`Enthought Canopy `_" + +#~ msgid "" +#~ "`bbFreeze `_ - Windows, Linux, Python " +#~ "2 only" +#~ msgstr "" +#~ "`bbFreeze `_ --- Windows, Linux, " +#~ "только Python 2;" + +#~ msgid "" +#~ "RFC 822 Long Header Fields: http://www.freesoft.org/CIE/RFC/822/7.htm" +#~ msgstr "" +#~ "RFC 822 Длинные поля заголовков: http://www.freesoft.org/CIE/RFC/822/7.htm" + +#~ msgid "Using `venv`_:" +#~ msgstr "Использование `venv`_:" diff --git a/locales/sai/LC_MESSAGES/messages.po b/locales/sai/LC_MESSAGES/messages.po new file mode 100644 index 000000000..ba2ae7995 --- /dev/null +++ b/locales/sai/LC_MESSAGES/messages.po @@ -0,0 +1,26789 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# gfbdrgng , 2023. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: Automatically generated\n" +"Language-Team: none\n" +"Language: sai\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "" + +#: ../source/contribute.rst:14 +msgid "Translating the guide" +msgstr "" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "" + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "" + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "" + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "" + +#: ../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 +msgid "What is a source distribution?" +msgstr "" + +#: ../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 +msgid "What about eggs?" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python setup.py install``" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python -m pip install --editable .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:104 +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr "" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +msgid "Complete" +msgstr "" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +msgid "Versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +msgid "Calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +msgid "Other schemes" +msgstr "" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 ../source/flow.rst:143 +msgid "" +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../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 :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +msgid "Installed Project" +msgstr "" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +msgid "Project Root Directory" +msgstr "" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "" + +#: ../source/glossary.rst:257 +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:260 +msgid "Pyproject Metadata" +msgstr "" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +msgid "Pyproject Metadata Key" +msgstr "" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "" + +#: ../source/glossary.rst:344 +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:348 +msgid "Root License Directory" +msgstr "" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +msgid "Wheel Project" +msgstr "" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "" +"https://files.pythonhosted.org/packages/eb/" +"45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" +"sampleproject-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "" +"https://files.pythonhosted.org/packages/56/0a/" +"178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" +"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +msgid "" +"https://files.pythonhosted.org/packages/" +"63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" +"sampleproject_nomura-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +msgid "Creating the package" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +msgid "``pyproject.toml``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +msgid "Installing the package with ``pipx``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +msgid "Conclusion" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +msgid "1. Install twine" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +msgid "Dropping a Python version" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:108 +msgid "openSUSE" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:118 +msgid "Debian/Ubuntu and derivatives" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +msgid "Install packages in a virtual environment using pip and venv" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +msgid "Install packages using pip" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +msgid "Install extras" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +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/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python -m build``" +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:126 +msgid "``python -m build --no-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:127 +msgid "``python -m pip install --no-build-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../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 "" +"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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +msgid "Installation" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:233 +msgid "``appveyor-sample/build.cmd``" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:5 +msgid "Tool recommendations" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +msgid "Installing packages" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +msgid "Building distributions" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:313 +msgid "setuptools" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:317 +msgid "uv-build" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +msgid "`Kivy `_" +msgstr "" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "Subdirectory name" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +msgid "``licenses``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*object*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Schema version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "examples" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "version\\_info" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*number*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**implementation**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**flags**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**headers**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +msgid "Package Building" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +msgid ":ref:`Version `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +msgid "``toml``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +msgid "``dependency_groups``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +msgid "Installers" +msgstr "" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +msgid "Reference implementation in Python" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +msgid "Names and normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +msgid "Name normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +msgid "Project Status Markers" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +msgid "Installer semantics: none." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +msgid "Installer semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +msgid "``deprecated``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +msgid "``pylock.toml`` Specification" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +msgid "``lock-version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +msgid "**Required?**: yes" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +msgid "``environments``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +msgid "``dependency-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +msgid "``[[packages]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +msgid "``packages.version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +msgid "The version of the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +msgid "``[[packages.dependencies]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +msgid "The time the file was uploaded." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +msgid "``packages.index``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +msgid "``import-names``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +msgid "Legacy specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +msgid "Examples:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +msgid "Example:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +msgid "PyPA schemas" +msgstr "" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +msgid "Python Description Formats" +msgstr "" + +#: ../source/specifications/section-reproducible-environments.rst:3 +msgid "Reproducible Environments" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +msgid "Normalized Names" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +msgid "HTML Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +msgid "Project List" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +msgid "Project Detail" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +msgid "JSON Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +msgid "Content-Types" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +msgid "Version + Format Selection" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +msgid "Definitions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +msgid "Version scheme" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +msgid "Pre-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +msgid "Version epochs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +msgid "Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +msgid "Integer Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +msgid "Version exclusion" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +msgid "Well-known Project URLs in Metadata" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +msgid "Label normalization" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +msgid "Normalized" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"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/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "" + +#: ../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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "" + +#: ../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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" diff --git a/locales/si/LC_MESSAGES/messages.po b/locales/si/LC_MESSAGES/messages.po new file mode 100644 index 000000000..ce7fbaebf --- /dev/null +++ b/locales/si/LC_MESSAGES/messages.po @@ -0,0 +1,26793 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# HelaBasa , 2021. +# Kushan Gunasekera , 2022. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: 2022-06-11 08:19+0000\n" +"Last-Translator: Kushan Gunasekera \n" +"Language-Team: Sinhala \n" +"Language: si\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=2; plural=n > 1;\n" +"X-Generator: Weblate 4.13-dev\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "මෙම මාර්ගෝපදේශයට දායක වන්න" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "" + +#: ../source/contribute.rst:14 +msgid "Translating the guide" +msgstr "" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "" + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "" + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "" + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "" + +#: ../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 +msgid "What is a source distribution?" +msgstr "" + +#: ../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 +msgid "What about eggs?" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python setup.py install``" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python -m pip install --editable .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:104 +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr "" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +msgid "Complete" +msgstr "" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +msgid "Versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +msgid "Calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +msgid "Other schemes" +msgstr "" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 ../source/flow.rst:143 +msgid "" +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../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 :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +msgid "Installed Project" +msgstr "" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +msgid "Project Root Directory" +msgstr "" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "" + +#: ../source/glossary.rst:257 +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:260 +msgid "Pyproject Metadata" +msgstr "" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +msgid "Pyproject Metadata Key" +msgstr "" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "" + +#: ../source/glossary.rst:344 +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:348 +msgid "Root License Directory" +msgstr "" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +msgid "Wheel Project" +msgstr "" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "" +"https://files.pythonhosted.org/packages/eb/" +"45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" +"sampleproject-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "" +"https://files.pythonhosted.org/packages/56/0a/" +"178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" +"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +msgid "" +"https://files.pythonhosted.org/packages/" +"63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" +"sampleproject_nomura-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +msgid "Creating the package" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +msgid "``pyproject.toml``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +msgid "Installing the package with ``pipx``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +msgid "Conclusion" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +msgid "1. Install twine" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +msgid "Dropping a Python version" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:108 +msgid "openSUSE" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:118 +msgid "Debian/Ubuntu and derivatives" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +msgid "Install packages in a virtual environment using pip and venv" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +msgid "Install packages using pip" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +msgid "Install extras" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +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/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python -m build``" +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:126 +msgid "``python -m build --no-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:127 +msgid "``python -m pip install --no-build-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../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 "" +"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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +msgid "Installation" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:233 +msgid "``appveyor-sample/build.cmd``" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:5 +msgid "Tool recommendations" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +msgid "Installing packages" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +msgid "Building distributions" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:313 +msgid "setuptools" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:317 +msgid "uv-build" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +msgid "`Kivy `_" +msgstr "" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "Subdirectory name" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +msgid "``licenses``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*object*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Schema version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "examples" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "version\\_info" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*number*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**implementation**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**flags**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**headers**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +msgid "Package Building" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +msgid ":ref:`Version `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +msgid "``toml``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +msgid "``dependency_groups``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +msgid "Installers" +msgstr "" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +msgid "Reference implementation in Python" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +msgid "Names and normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +msgid "Name normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +msgid "Project Status Markers" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +msgid "Installer semantics: none." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +msgid "Installer semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +msgid "``deprecated``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +msgid "``pylock.toml`` Specification" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +msgid "``lock-version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +msgid "**Required?**: yes" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +msgid "``environments``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +msgid "``dependency-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +msgid "``[[packages]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +msgid "``packages.version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +msgid "The version of the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +msgid "``[[packages.dependencies]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +msgid "The time the file was uploaded." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +msgid "``packages.index``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +msgid "``import-names``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +msgid "Legacy specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +msgid "Examples:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +msgid "Example:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +msgid "PyPA schemas" +msgstr "" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +msgid "Python Description Formats" +msgstr "" + +#: ../source/specifications/section-reproducible-environments.rst:3 +msgid "Reproducible Environments" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +msgid "Normalized Names" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +msgid "HTML Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +msgid "Project List" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +msgid "Project Detail" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +msgid "JSON Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +msgid "Content-Types" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +msgid "Version + Format Selection" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +msgid "Definitions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +msgid "Version scheme" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +msgid "Pre-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +msgid "Version epochs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +msgid "Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +msgid "Integer Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +msgid "Version exclusion" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +msgid "Well-known Project URLs in Metadata" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +msgid "Label normalization" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +msgid "Normalized" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"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/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "" + +#: ../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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "" + +#: ../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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" diff --git a/locales/sk/LC_MESSAGES/messages.po b/locales/sk/LC_MESSAGES/messages.po new file mode 100644 index 000000000..1d79dbe9d --- /dev/null +++ b/locales/sk/LC_MESSAGES/messages.po @@ -0,0 +1,27010 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# Milan Šalka , 2023, 2024. +# Rafael Fontenelle , 2024. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: 2024-11-02 00:54+0000\n" +"Last-Translator: Milan Šalka \n" +"Language-Team: Slovak \n" +"Language: sk\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=((n==1) ? 0 : (n>=2 && n<=4) ? 1 : 2);\n" +"X-Generator: Weblate 5.8.2-dev\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "Prispieť k tomuto sprievodcu" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "" +"|PyPUG| víta prispievateľov! Existuje veľa spôsobov, ako pomôcť, vrátane:" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "Čítanie sprievodcu a dávať spätnú väzbu" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "Preskúmanie nových príspevkov" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "Odhalenie existujúceho obsahu" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "Písanie nového obsahu" + +#: ../source/contribute.rst:14 +#, fuzzy +#| msgid "Translate the guide" +msgid "Translating the guide" +msgstr "Preložiť sprievodcu" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" +"Väčšina práce na |PyPUG| sa koná na `project's GitHub úložisko`__. Ak chcete " +"začať, pozrite sa na zoznam `open issues'__ a `pull requests'__. Ak " +"plánujete napísať alebo upraviť sprievodcu, prečítajte si :ref:`style guide " +"`." + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" +"Pokračovaním v |PyPUG|, očakáva sa, že budete dodržiavať PSF je `Code of " +"Conduct`__." + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "Typy dokumentov" + +#: ../source/contribute.rst:34 +#, fuzzy +#| msgid "" +#| "This project consists of four distinct documentation types with specific " +#| "purposes. When proposing new additions to the project please pick the " +#| "appropriate documentation type." +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" +"Tento projekt pozostáva z štyroch rôznych typov dokumentácie s konkrétnymi " +"účelmi. Pri navrhovaní nových prírastkov do projektu prosím vyberte vhodný " +"typ dokumentácie." + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "Návody" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" +"Návody sú zamerané na výučbu čitateľa nové koncepty na dosiahnutie cieľa. Sú " +"poctení krok za krokom sprievodcov. Neobsahujú mimoriadne upozornenia alebo " +"informácie. `example tutorial-style dokument`_." + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "Vodítka" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" +"Sprievodcovia sú zamerané na dosiahnutie špecifickej úlohy a môžu " +"predpokladať, že niektoré úrovne vopred otázky. To sú podobné tutoriály, ale " +"majú úzke a jasné zameranie a môže poskytnúť veľa jaskýň a ďalšie " +"informácie, ako je to potrebné. Môžu tiež diskutovať o viacerých prístupov k " +"dosiahnutiu úlohy. :doc:`example sprievodca-style dokument `." + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "Diskusia" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" +"Diskusie sú zamerané na pochopenie a informácie. Tieto skúmajú konkrétnu " +"tému bez konkrétneho cieľa. :doc:`example diskusný dokument `." + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "Špecifikácie" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" +"Špecifikácie sú referenčné dokumenty zamerané na komplexne dokumentujúce " +"dohodnuté rozhranie pre interoperabilitu medzi obalovými " +"nástrojmi. :doc:`example špecifikácia-style dokument `." + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "Preklady" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" +"Používame `Weblate`_ na správu prekladov tohto projektu. Prosím, navštívte " +"`packaging. python.org`_ projekt na Weblate prispieť." + +#: ../source/contribute.rst:80 +#, fuzzy +#| msgid "" +#| "If you are experiencing issues while you are working on translations, " +#| "please open an issue on `Github`_." +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" +"Ak máte problémy, zatiaľ čo pracujete na prekladoch, otvorte prosím problém " +"na `Github`_." + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" +"Akékoľvek preklady tohto projektu by mali nasledovať `reStructuredText " +"syntax`_." + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "Pridanie jazyka" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" +"Ak váš jazyk nie je uvedený na `packaging. python.org`_, kliknite na " +"tlačidlo :guilabel:`Start nový preklad` v dolnej časti zoznamu jazykov a " +"pridajte jazyk, ktorý chcete preložiť." + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "Nasledujúca obnova Text syntax" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" +"Ak nie ste oboznámení s reStructuredText (RST) syntax, prečítajte si `this " +"guide`_ pred prekladanie na Weblate." + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "**Nepreložte text priamo * *" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "Pri preklade textu v referencii ich neprekladajú priamo." + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "Zle: Preložiť nasledujúci text priamo:" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" +"Právo: Preložte nasledujúci text s vlastným jazykom a pridajte originálnu " +"referenciu:" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "Budovanie sprievodcu lokálne" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" +"Aj keď nie je potrebné prispievať, môže byť užitočné vybudovať tento " +"sprievodca lokálne, aby ste testovali svoje zmeny. S cieľom vybudovať tento " +"sprievodca lokálne, budete potrebovať:" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" +":doc:`Nox `. Môžete nainštalovať alebo upgradovať nox pomocou " +"``pip``:" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" +"Python 3.11. Naše scenáre sú zvyčajne testované s Python 3.11 iba. " +"Pozri :doc:`Hitchhiker sprievodca Python inštalačné pokyny ` nainštalovať Python 3.11 na vašom operačnom " +"systéme." + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" +"Ak chcete vybudovať sprievodcu, spustiť nasledujúci príkaz shell v priečinku " +"koreňa projektu:" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" +"Po dokončení procesu nájdete výstup HTML v adresári ``./build/html``. Môžete " +"otvoriť súbor ``index.html`` pre zobrazenie sprievodcu v prehliadači, ale " +"odporúča sa slúžiť sprievodcu pomocou servera HTTP." + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" +"Môžete si vytvoriť sprievodcu a slúžiť cez HTTP server pomocou nasledujúceho " +"príkazu:" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "Sprievodca bude browsable cez http://localhost:8000." + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "Kde je sprievodca nasadený" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" +"Sprievodca je nasadený ReadTheDocs a konfigurácia žije na https://" +"readthedocs.org/projects/python-packaging-user-guide/. Slúži z vlastnej " +"domény a predaný Fast.ly." + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "Štýlový sprievodca" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" +"Tento štýl sprievodca má odporúčania, ako by ste mali napísať |PyPUG|. " +"Predtým, ako začnete písať, prečítajte si to. Podľa štýlu sprievodcu, vaše " +"príspevky pomôžu pridať do cohesive celé a uľahčujú, aby boli prijaté do " +"projektu." + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "Účel" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" +"Účelom |PyPUG| je byť autoritačný zdroj o tom, ako balík, publikovať a " +"nainštalovať Python projekty pomocou súčasných nástrojov." + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "Rozsah" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" +"Sprievodca je určený na odpoveď na otázky a riešenie problémov s presnými a " +"zameranými odporúčaniami." + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" +"Sprievodca nie je určený na komplexné a nie je určený na nahradenie " +"dokumentácie jednotlivých projektov. Napríklad, pip má desiatky príkazov, " +"možností a nastavení. Dokumentácia pip popisuje každý z nich podrobne, " +"zatiaľ čo tento sprievodca popisuje iba časti pip, ktoré sú potrebné na " +"dokončenie konkrétnych úloh opísaných v tomto sprievodcovi." + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "Aktuality" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "Publikum tohto sprievodcu je niekto, kto používa Python s balíkmi." + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" +"Nezabudnite, že komunita Python je veľká a príjemná. Čitatelia nemusia " +"zdieľať svoj vek, pohlavie, vzdelanie, kultúra a ďalšie, ale zaslúžia sa " +"dozvedieť o balení rovnako ako vy." + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" +"Najmä majte na pamäti, že nie všetci ľudia, ktorí používajú Python pozrite " +"sa ako programátori. publikum tohto sprievodcu zahŕňa astronómov alebo " +"maliarov alebo študentov, ako aj profesionálnych vývojárov softvéru." + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "Hlas a tón" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" +"Pri písaní tohto sprievodcu sa snaží písať hlasom, ktorý je prístupný a " +"pokorený, aj keď máte všetky odpovede." + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" +"Predstavte si, že pracujete na projekte Python s niekým, koho viete byť " +"šikovný a šikovný. Máte radi prácu s nimi a radi s vami pracujú. Táto osoba " +"vám položila otázku a poznáte odpoveď. Ako reagujete? *To * je, ako by ste " +"mali napísať tento sprievodca." + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" +"Tu je rýchly check: skúste čítať aloud získať zmysel pre váš hlas a tón. " +"Znie to ako niečo, čo by ste povedali, alebo to znie, ako ste vystupovať " +"časť alebo dať reč? Neváhajte využívať kontrakcie a nebojte sa držať krok za " +"fussssy gramatiky. Tie sú týmto udelené povolenie na ukončenie vety v " +"predložke, ak to chcete skončiť." + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" +"Pri písaní sprievodcu, upravte tón pre závažnosť a ťažkosti témy. Ak píšete " +"úvodný výukový program, je to v poriadku, aby sa vtip, ale ak pokrývate " +"citlivé bezpečnostné odporúčanie, môžete sa vyhnúť vtipom úplne." + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "Dohovory a mechaniky" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "**Napíšte čitateľovi**" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" +"Pri dávať odporúčania alebo kroky, aby sa, adresu čitateľa ako * vy * alebo " +"použiť potrebnú náladu." + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "Zle: Ak chcete nainštalovať, používateľ beží.." + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "Právo: Môžete ho nainštalovať beh.." + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "Právo: Ak chcete nainštalovať, spustiť.." + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "** Stavebné predpoklady**" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" +"Vyhnite sa tomu, aby ste neprestali predpoklady. Čítanie na webe znamená, že " +"každá stránka sprievodcu môže byť prvou stránkou sprievodcu, ktorý čitateľ " +"niekedy vidí. Ak budete robiť predpoklady, potom povedzte, aké predpoklady " +"budete robiť." + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "**Cross-referenčné veľkorysé**" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "" + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "Neúplné" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "" + +#: ../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 +msgid "What is a source distribution?" +msgstr "" + +#: ../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 +msgid "What about eggs?" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python setup.py install``" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 +#, fuzzy +#| msgid "Documentation types" +msgid "Recommendation" +msgstr "Typy dokumentov" + +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python -m pip install .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python -m pip install --editable .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:104 +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +#, fuzzy +#| msgid "Python version" +msgid "``python setup.py --version``" +msgstr "Verzia Pythonu" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr "" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +#, fuzzy +#| msgid "Incomplete" +msgid "Complete" +msgstr "Neúplné" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +msgid "Versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +msgid "Calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +msgid "Other schemes" +msgstr "" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 ../source/flow.rst:143 +msgid "" +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../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 :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +#, fuzzy +#| msgid "Translations" +msgid "Installed Project" +msgstr "Preklady" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "Projekt" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +#, fuzzy +#| msgid "Project name" +msgid "Project Root Directory" +msgstr "Meno projektu" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "" + +#: ../source/glossary.rst:257 +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:260 +#, fuzzy +#| msgid "Project name" +msgid "Pyproject Metadata" +msgstr "Meno projektu" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +#, fuzzy +#| msgid "Project name" +msgid "Pyproject Metadata Key" +msgstr "Meno projektu" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "" + +#: ../source/glossary.rst:344 +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:348 +#, fuzzy +#| msgid "Project name" +msgid "Root License Directory" +msgstr "Meno projektu" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +#, fuzzy +#| msgid "Project" +msgid "Wheel Project" +msgstr "Projekt" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "Poznámka" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "Meno projektu" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "Verzia Pythonu" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "" +"https://files.pythonhosted.org/packages/eb/" +"45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" +"sampleproject-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "" +"https://files.pythonhosted.org/packages/56/0a/" +"178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" +"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +msgid "" +"https://files.pythonhosted.org/packages/" +"63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" +"sampleproject_nomura-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +#, fuzzy +#| msgid "Installing packages" +msgid "Creating the package" +msgstr "Inštalovanie balíčkov" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +#, fuzzy +#| msgid "Project name" +msgid "``pyproject.toml``" +msgstr "Meno projektu" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +#, fuzzy +#| msgid "Installing packages" +msgid "Installing the package with ``pipx``" +msgstr "Inštalovanie balíčkov" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +msgid "Conclusion" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "Vytvoriť účet" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +#, fuzzy +#| msgid "Translations" +msgid "1. Install twine" +msgstr "Preklady" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +#, fuzzy +#| msgid "Python version" +msgid "Dropping a Python version" +msgstr "Verzia Pythonu" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:105 +#, fuzzy +#| msgid "Maintainer" +msgid "unmaintained" +msgstr "Udržiavač" + +#: ../source/guides/installing-scientific-packages.rst:5 +msgid "Installing scientific packages" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:8 +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." +msgstr "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:108 +msgid "openSUSE" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:118 +msgid "Debian/Ubuntu and derivatives" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +#, fuzzy +#| msgid "Installing packages" +msgid "Install packages in a virtual environment using pip and venv" +msgstr "Inštalovanie balíčkov" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +#, fuzzy +#| msgid "Installing packages" +msgid "Install packages using pip" +msgstr "Inštalovanie balíčkov" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +#, fuzzy +#| msgid "Installing packages" +msgid "Install a package" +msgstr "Inštalovanie balíčkov" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +#, fuzzy +#| msgid "Installing packages" +msgid "Install a specific package version" +msgstr "Inštalovanie balíčkov" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +#, fuzzy +#| msgid "Translations" +msgid "Install extras" +msgstr "Preklady" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +#, fuzzy +#| msgid "Installing packages" +msgid "Install a package from source" +msgstr "Inštalovanie balíčkov" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +#, fuzzy +#| msgid "Installing packages" +msgid "Install from other package indexes" +msgstr "Inštalovanie balíčkov" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +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/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +#, fuzzy +#| msgid "Installing packages" +msgid "Installing packages using virtualenv" +msgstr "Inštalovanie balíčkov" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python -m build``" +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:126 +msgid "``python -m build --no-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:127 +msgid "``python -m pip install --no-build-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +#, fuzzy +#| msgid "Project name" +msgid ":ref:`pyproject-toml-spec`" +msgstr "Meno projektu" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../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 "" +"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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +#, fuzzy +#| msgid "Translations" +msgid "Installation" +msgstr "Preklady" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:233 +msgid "``appveyor-sample/build.cmd``" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:5 +msgid "Tool recommendations" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +#, fuzzy +#| msgid "Installing packages" +msgid "Installing packages" +msgstr "Inštalovanie balíčkov" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +#, fuzzy +#| msgid "Reviewing new contributions" +msgid "Building distributions" +msgstr "Preskúmanie nových príspevkov" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:313 +msgid "setuptools" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:317 +msgid "uv-build" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "Používateľská príručka balíka Python" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +msgid "`Kivy `_" +msgstr "" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "Bezpečnosť" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "Detaily" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +#, fuzzy +#| msgid "Project name" +msgid "Subdirectory name" +msgstr "Meno projektu" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +msgid "``licenses``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Project" +msgid "*object*" +msgstr "Projekt" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Python version" +msgid "Schema version." +msgstr "Verzia Pythonu" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "examples" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "version\\_info" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*number*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Documentation types" +msgid "**implementation**" +msgstr "Typy dokumentov" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**flags**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**headers**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "Udržiavač" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +msgid "Package Building" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +#, fuzzy +#| msgid "Documentation types" +msgid "Reference Implementation" +msgstr "Typy dokumentov" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +msgid ":ref:`Version `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +#, fuzzy +#| msgid "Project name" +msgid "``toml``" +msgstr "Meno projektu" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +msgid "``dependency_groups``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +#, fuzzy +#| msgid "Installing packages" +msgid "Python-specific package manager" +msgstr "Inštalovanie balíčkov" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +#, fuzzy +#| msgid "Documentation types" +msgid "Implementation Notes" +msgstr "Typy dokumentov" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +#, fuzzy +#| msgid "Translations" +msgid "Installers" +msgstr "Preklady" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +#, fuzzy +#| msgid "Documentation types" +msgid "Reference implementation in Python" +msgstr "Typy dokumentov" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +msgid "Names and normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +msgid "Name normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +#, fuzzy +#| msgid "Project name" +msgid "Project Status Markers" +msgstr "Meno projektu" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +#, fuzzy +#| msgid "Translations" +msgid "Installer semantics: none." +msgstr "Preklady" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +#, fuzzy +#| msgid "Translations" +msgid "Installer semantics:" +msgstr "Preklady" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +msgid "``deprecated``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +#, fuzzy +#| msgid "Specifications" +msgid "``pylock.toml`` Specification" +msgstr "Špecifikácie" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +msgid "``lock-version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +msgid "**Required?**: yes" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +msgid "``environments``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +msgid "``dependency-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +#, fuzzy +#| msgid "Project name" +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "Meno projektu" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +msgid "``[[packages]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +msgid "``packages.version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +#, fuzzy +#| msgid "Installing packages" +msgid "The version of the package." +msgstr "Inštalovanie balíčkov" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +msgid "``[[packages.dependencies]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +#, fuzzy +#| msgid "Where the guide is deployed" +msgid "The time the file was uploaded." +msgstr "Kde je sprievodca nasadený" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +msgid "``packages.index``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +#, fuzzy +#| msgid "Project name" +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "Meno projektu" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +msgid "``import-names``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +#, fuzzy +#| msgid "Specifications" +msgid "Legacy specification" +msgstr "Špecifikácie" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +msgid "Examples:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +msgid "Example:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +msgid "PyPA schemas" +msgstr "" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +#, fuzzy +#| msgid "Python version" +msgid "Python Description Formats" +msgstr "Verzia Pythonu" + +#: ../source/specifications/section-reproducible-environments.rst:3 +msgid "Reproducible Environments" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +msgid "Normalized Names" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +#, fuzzy +#| msgid "Translations" +msgid "HTML Serialization" +msgstr "Preklady" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +#, fuzzy +#| msgid "Project" +msgid "Project List" +msgstr "Projekt" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +#, fuzzy +#| msgid "Project name" +msgid "Project Detail" +msgstr "Meno projektu" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +msgid "JSON Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +msgid "Content-Types" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +msgid "Version + Format Selection" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +#, fuzzy +#| msgid "Specifications" +msgid "Definitions" +msgstr "Špecifikácie" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +msgid "Version scheme" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +msgid "Pre-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +msgid "Version epochs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +msgid "Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +msgid "Integer Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +msgid "Version exclusion" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +#, fuzzy +#| msgid "Project name" +msgid "Well-known Project URLs in Metadata" +msgstr "Meno projektu" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +msgid "Label normalization" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +msgid "Normalized" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"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/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "" + +#: ../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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "" + +#: ../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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" + +#, fuzzy +#~| msgid "Project name" +#~ msgid "**Inspiration**: :ref:` pyproject-tool-table`" +#~ msgstr "Meno projektu" diff --git a/locales/ta/LC_MESSAGES/messages.po b/locales/ta/LC_MESSAGES/messages.po new file mode 100644 index 000000000..f3816c8f3 --- /dev/null +++ b/locales/ta/LC_MESSAGES/messages.po @@ -0,0 +1,35122 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# "K.B.Dharun Krishna" , 2024. +# தமிழ்நேரம் , 2025. +# WofWca , 2025. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: 2025-07-19 06:36+0000\n" +"Last-Translator: தமிழ்நேரம் \n" +"Language-Team: Tamil \n" +"Language: ta\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=2; plural=n != 1;\n" +"X-Generator: Weblate 5.13-dev\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "இந்த வழிகாட்டிக்கு பங்களிக்கவும்" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "தி | பைபக் | பங்களிப்பாளர்களை வரவேற்கிறது! உட்பட உதவ நிறைய வழிகள் உள்ளன:" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "வழிகாட்டியைப் படித்து கருத்துக்களை வழங்குதல்" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "புதிய பங்களிப்புகளை மதிப்பாய்வு செய்தல்" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "இருக்கும் உள்ளடக்கத்தை திருத்துதல்" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "புதிய உள்ளடக்கத்தை எழுதுதல்" + +#: ../source/contribute.rst:14 +#, fuzzy +#| msgid "Translate the guide" +msgid "Translating the guide" +msgstr "வழிகாட்டியை மொழிபெயர்க்கவும்" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" +"| பைபக் | இல் பெரும்பாலான வேலைகள் `திட்டத்தின் அறிவிலிமையம் களஞ்சியத்தில்`. " +"தொடங்குவதற்கு, `திறந்த சிக்கல்கள்`__ மற்றும்` கோரிக்கைகளை இழுக்கவும்` __ இன் பட்டியலைப் " +"பாருங்கள். வழிகாட்டியை எழுதவோ திருத்தவோ நீங்கள் திட்டமிட்டால், தயவுசெய்து படிக்கவும்: " +"குறிப்பு: `பாணி வழிகாட்டி <பங்களிப்பு_ச்டைல்_கூட்>`." + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "| பைபக் |" + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "ஆவணப்படுத்தல் வகைகள்" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" +"இந்த திட்டம் குறிப்பிட்ட நோக்கங்களுடன் நான்கு தனித்துவமான ஆவணப்படுத்தல் வகைகளைக் " +"கொண்டுள்ளது. தரமான ஆவணங்களை உருவாக்குவதற்கு `டியடாக்சிச் செயல்முறை`_ ஐப் பின்பற்ற இந்த " +"திட்டம் விரும்புகிறது. திட்டத்தில் புதிய சேர்த்தல்களை முன்மொழியும்போது பொருத்தமான " +"ஆவணப்படுத்தல் வகையைத் தேர்ந்தெடுக்கவும்." + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "பயிற்சிகள்" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" +"பயிற்சிகள் ஒரு இலக்கை அடைவதன் மூலம் வாசகருக்கு புதிய கருத்துக்களை கற்பிப்பதில் கவனம் " +"செலுத்துகின்றன. அவர்கள் படிப்படியான வழிகாட்டிகளாக கருதப்படுகிறார்கள். அவை வெளிப்புற " +"எச்சரிக்கைகள் அல்லது தகவல்களைக் கொண்டிருக்கவில்லை. `எடுத்துக்காட்டு பயிற்சி-பாணி ஆவணம்`_." + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "வழிகாட்டிகள்" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" +"வழிகாட்டிகள் ஒரு குறிப்பிட்ட பணியை நிறைவேற்றுவதில் கவனம் செலுத்துகின்றன, மேலும் அவை " +"முன்நிபந்தனைக்கு முந்தைய அறிவை எடுத்துக் கொள்ளலாம். இவை பயிற்சிகளைப் போன்றவை, ஆனால் ஒரு " +"குறுகிய மற்றும் தெளிவான கவனம் செலுத்துகின்றன, மேலும் தேவைக்கேற்ப நிறைய எச்சரிக்கைகள் " +"மற்றும் கூடுதல் தகவல்களை வழங்க முடியும். பணியை நிறைவேற்றுவதற்கான பல அணுகுமுறைகளையும் " +"அவர்கள் விவாதிக்கலாம். ." + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "விவாதங்கள்" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" +"புரிந்துகொள்ளுதல் மற்றும் தகவல்களில் விவாதங்கள் கவனம் செலுத்துகின்றன. இவை ஒரு குறிப்பிட்ட " +"இலக்கை மனதில் கொண்டு ஒரு குறிப்பிட்ட தலைப்பை ஆராய்கின்றன. ." + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "விவரக்குறிப்புகள்" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" +"விவரக்குறிப்புகள் என்பது பேக்கேசிங் கருவிகளுக்கு இடையில் இயங்குதலுக்காக ஒப்புக் கொள்ளப்பட்ட " +"இடைமுகத்தை விரிவாக ஆவணப்படுத்துவதில் கவனம் செலுத்தும் குறிப்பு ஆவணங்கள் ஆகும். : டாக்: " +"`எடுத்துக்காட்டு விவரக்குறிப்பு-பாணி ஆவணம் <விவரக்குறிப்புகள்/கோர்-மெட்டாடேட்டா>`." + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "மொழிபெயர்ப்புகள்" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" +"இந்த திட்டத்தின் மொழிபெயர்ப்புகளை நிர்வகிக்க `வெப்லேட்`_ ஐப் பயன்படுத்துகிறோம். பங்களிக்க " +"வெப்லேட்டில் உள்ள `பேக்கேசிங்.பிதான்.ஆர்ச்`_ திட்டத்தைப் பார்வையிடவும்." + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" +"நீங்கள் மொழிபெயர்ப்புகளில் பணிபுரியும் போது சிக்கல்களைச் சந்திக்கிறீர்கள் என்றால், தயவுசெய்து " +"`github`_ இல் ஒரு சிக்கலைத் திறக்கவும்." + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" +"இந்த திட்டத்தின் எந்த மொழிபெயர்ப்புகளும் `மறுசீரமைப்பு டெக்ச்ட் தொடரியல்`_ ஐப் பின்பற்ற " +"வேண்டும்." + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "ஒரு மொழியைச் சேர்ப்பது" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" +"உங்கள் மொழி `பேக்கேசிங்.பிதான்.ஆர்ச்`_ இல் பட்டியலிடப்படவில்லை என்றால், பொத்தானைக் சொடுக்கு " +"செய்க: கிலாபெல்:` மொழி பட்டியலின் கீழே புதிய மொழிபெயர்ப்பைத் தொடங்கவும், நீங்கள் " +"மொழிபெயர்க்க விரும்பும் மொழியைச் சேர்க்கவும்." + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "மறுசீரமைப்பின் தொடரியல் தொடரியல்" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" +"மறுசீரமைப்பு (RST) தொடரியல் உங்களுக்கு தெரிந்திருக்கவில்லை என்றால், வெப்லேட்டில் " +"மொழிபெயர்ப்பதற்கு முன் `இந்த வழிகாட்டி`_ ஐப் படிக்கவும்." + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "** உரையை நேரடியாக மொழிபெயர்க்க வேண்டாம் **" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "உரையை குறிப்பில் மொழிபெயர்க்கும்போது, அவற்றை நேரடியாக மொழிபெயர்க்க வேண்டாம்." + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "தவறு: பின்வரும் உரையை நேரடியாக மொழிபெயர்க்கவும்:" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" +"வலது: பின்வரும் உரையை உங்கள் சொந்த மொழியுடன் மொழிபெயர்த்து அசல் குறிப்பைச் சேர்க்கவும்:" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "வழிகாட்டியை உள்நாட்டில் உருவாக்குதல்" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" +"பங்களிக்கத் தேவையில்லை என்றாலும், உங்கள் மாற்றங்களைச் சோதிக்க இந்த வழிகாட்டியை உள்நாட்டில் " +"உருவாக்குவது பயனுள்ளதாக இருக்கும். இந்த வழிகாட்டியை உள்ளூரில் உருவாக்க, உங்களுக்குத் " +"தேவை:" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" +": டாக்: `NOX `. `` பிப்`` ஐப் பயன்படுத்தி நீங்கள் NOX ஐ நிறுவலாம் அல்லது " +"மேம்படுத்தலாம்:" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" +"பைதான் 3.11. எங்கள் உருவாக்க ச்கிரிப்ட்கள் பொதுவாக பைதான் 3.11 உடன் மட்டுமே " +"சோதிக்கப்படுகின்றன. பார்க்க: டாக்: `பைதான் நிறுவல் வழிமுறைகளுக்கான இட்சிகரின் வழிகாட்டி " +"<பைதான்-வழிகாட்டி: தொடக்க/நிறுவல்>` உங்கள் இயக்க முறைமையில் பைதான் 3.11 ஐ நிறுவ." + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" +"வழிகாட்டியை உருவாக்க, திட்டத்தின் ரூட் கோப்புறையில் பின்வரும் செல் கட்டளையை இயக்கவும்:" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" +"செயல்முறை முடிந்ததும் நீங்கள் உஉகுமொ வெளியீட்டை ``./பில்ட்/HTML`` கோப்பகத்தில் காணலாம். " +"வலை உலாவியில் வழிகாட்டியைக் காண நீங்கள் `` index.html`` கோப்பைத் திறக்கலாம், ஆனால் HTTP " +"சேவையகத்தைப் பயன்படுத்தி வழிகாட்டியை வழங்க பரிந்துரைக்கப்படுகிறது." + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" +"நீங்கள் வழிகாட்டியை உருவாக்கி பின்வரும் கட்டளையைப் பயன்படுத்தி ஒரு HTTP சேவையகம் வழியாக " +"பணி செய்யலாம்:" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "வழிகாட்டி http: // localhost: 8000 வழியாக உலாவக்கூடியதாக இருக்கும்." + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "வழிகாட்டி பயன்படுத்தப்படும் இடத்தில்" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" +"வழிகாட்டி ReadThedocs வழியாகவும், உள்ளமைவு https://readthedocs.org/projects/" +"python-packaging-user-guide/ இல் பயன்படுத்தப்படுகிறது. இது ஒரு தனிப்பயன் " +"களத்திலிருந்து வழங்கப்படுகிறது மற்றும் ஃபாச்ட்.லியின் முன்னால் உள்ளது." + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "நடை வழிகாட்டி" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" +"இந்த பாணி வழிகாட்டியில் நீங்கள் | பைபக் | ஐ எவ்வாறு எழுத வேண்டும் என்பதற்கான பரிந்துரைகள் " +"உள்ளன. நீங்கள் எழுதத் தொடங்குவதற்கு முன், அதை மதிப்பாய்வு செய்யவும். பாணி வழிகாட்டியைப் " +"பின்பற்றுவதன் மூலம், உங்கள் பங்களிப்புகள் ஒரு ஒருங்கிணைந்த முழுமையைச் சேர்க்க உதவும் மற்றும் " +"உங்கள் பங்களிப்புகளை திட்டத்தில் ஏற்றுக்கொள்வதை எளிதாக்கும்." + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "நோக்கம்" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" +"| பைபக் | இன் நோக்கம் தற்போதைய கருவிகளைப் பயன்படுத்தி பைதான் திட்டங்களை எவ்வாறு தொகுத்தல், " +"வெளியிடுவது மற்றும் நிறுவுவது என்பதற்கான அதிகாரப்பூர்வ ஆதாரமாக இருக்க வேண்டும்." + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "நோக்கம்" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" +"வழிகாட்டி என்பது கேள்விகளுக்கு பதிலளிப்பதற்கும் துல்லியமான மற்றும் கவனம் செலுத்தும் " +"பரிந்துரைகளுடன் சிக்கல்களைத் தீர்ப்பதற்கும் ஆகும்." + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" +"வழிகாட்டி விரிவானதாக இருக்கக்கூடாது, மேலும் இது தனிப்பட்ட திட்டங்களின் ஆவணங்களை " +"மாற்றுவதற்காக அல்ல. எடுத்துக்காட்டாக, பிஐபி டசன் கணக்கான கட்டளைகள், விருப்பங்கள் மற்றும் " +"அமைப்புகளைக் கொண்டுள்ளது. பிஐபி ஆவணங்கள் அவை ஒவ்வொன்றையும் விரிவாக விவரிக்கிறது, அதே " +"நேரத்தில் இந்த வழிகாட்டி இந்த வழிகாட்டியில் விவரிக்கப்பட்டுள்ள குறிப்பிட்ட பணிகளை முடிக்க " +"தேவையான பிஐபி பகுதிகளை மட்டுமே விவரிக்கிறது." + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "பார்வையாளர்கள்" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "இந்த வழிகாட்டியின் பார்வையாளர்கள் பைத்தானை தொகுப்புகளுடன் பயன்படுத்தும் எவரும்." + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" +"பைதான் சமூகம் பெரியது மற்றும் வரவேற்கத்தக்கது என்பதை மறந்துவிடாதீர்கள். வாசகர்கள் உங்கள் " +"அகவை, பாலினம், கல்வி, பண்பாடு மற்றும் பலவற்றைப் பகிர்ந்து கொள்ளக்கூடாது, ஆனால் அவர்கள் " +"உங்களைப் போலவே பேக்கேசிங் பற்றி அறிய தகுதியுடையவர்கள்." + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" +"குறிப்பாக, பைத்தானைப் பயன்படுத்தும் அனைவரும் தங்களை புரோகிராமர்களாகப் பார்க்கவில்லை என்பதை " +"நினைவில் கொள்ளுங்கள். இந்த வழிகாட்டியின் பார்வையாளர்களில் வானியலாளர்கள் அல்லது ஓவியர்கள் " +"அல்லது மாணவர்கள் மற்றும் தொழில்முறை மென்பொருள் உருவாக்குநர்கள் உள்ளனர்." + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "குரல் மற்றும் தொனி" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" +"இந்த வழிகாட்டியை எழுதும் போது, உங்களிடம் எல்லா பதில்களும் இருந்தாலும், அணுகக்கூடிய " +"மற்றும் தாழ்மையான குரலுடன் எழுத முயற்சி செய்யுங்கள்." + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" +"அறிவாளி மற்றும் திறமையானவர் என்று உங்களுக்குத் தெரிந்த ஒருவருடன் நீங்கள் ஒரு பைதான் " +"திட்டத்தில் பணிபுரிகிறீர்கள் என்று கற்பனை செய்து பாருங்கள். நீங்கள் அவர்களுடன் பணியாற்ற " +"விரும்புகிறீர்கள், அவர்கள் உங்களுடன் பணியாற்ற விரும்புகிறார்கள். அந்த நபர் உங்களிடம் ஒரு " +"கேள்வியைக் கேட்டிருக்கிறார், உங்களுக்கு பதில் தெரியும். நீங்கள் எவ்வாறு பதிலளிப்பீர்கள்? * " +"அதுதான்* இந்த வழிகாட்டியை நீங்கள் எவ்வாறு எழுத வேண்டும்." + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" +"இங்கே விரைவான சோதனை: உங்கள் எழுத்தின் குரல் மற்றும் தொனியைப் புரிந்துகொள்ள சத்தமாக படிக்க " +"முயற்சிக்கவும். இது நீங்கள் சொல்வதைப் போலத் தோன்றுகிறதா அல்லது நீங்கள் ஒரு பகுதியை " +"செயல்படுத்துவது அல்லது ஒரு உரையை வழங்குவது போல் தெரிகிறது? சுருக்கங்களைப் பயன்படுத்த " +"தயங்காதீர்கள், மேலும் கடுமையான இலக்கண விதிகளில் ஒட்டிக்கொள்வதைப் பற்றி கவலைப்பட வேண்டாம். " +"ஒரு வாக்கியத்தை ஒரு முன்மொழிவில் முடிக்க உங்களுக்கு இதன்மூலம் இசைவு வழங்கப்படுகிறது, " +"அதுதான் நீங்கள் அதை முடிக்க விரும்பினால்." + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" +"வழிகாட்டியை எழுதும் போது, தலைப்பின் தீவிரத்தன்மைக்கும் சிரமத்திற்கும் உங்கள் தொனியை " +"சரிசெய்யவும். நீங்கள் ஒரு அறிமுக டுடோரியலை எழுதுகிறீர்கள் என்றால், ஒரு நகைச்சுவையை " +"உருவாக்குவது சரி, ஆனால் நீங்கள் ஒரு முக்கியமான பாதுகாப்பு பரிந்துரையை " +"உள்ளடக்கியிருந்தால், நீங்கள் நகைச்சுவைகளை முழுவதுமாக தவிர்க்க விரும்பலாம்." + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "மாநாடுகள் மற்றும் இயக்கவியல்" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "** வாசகருக்கு எழுதுங்கள் **" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" +"எடுக்க வேண்டிய பரிந்துரைகள் அல்லது படிகளை வழங்கும்போது, வாசகரை * நீங்கள் * என " +"உரையாற்றவும் அல்லது கட்டாய மனநிலையைப் பயன்படுத்தவும்." + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "தவறு: அதை நிறுவ, பயனர் இயங்குகிறார்…" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "வலது: இயங்குவதன் மூலம் அதை நிறுவலாம்…" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "வலது: அதை நிறுவ, இயக்க…" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "** மாநில அனுமானங்கள் **" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" +"நிலையற்ற அனுமானங்களைச் செய்வதைத் தவிர்க்கவும். வலையில் படிப்பது என்பது வழிகாட்டியின் எந்தப் " +"பக்கமும் வாசகர் பார்க்கும் வழிகாட்டியின் முதல் பக்கமாக இருக்கலாம். நீங்கள் அனுமானங்களைச் " +"செய்யப் போகிறீர்கள் என்றால், நீங்கள் என்ன செய்யப் போகிறீர்கள் என்று சொல்லுங்கள்." + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "** குறுக்கு-குறிப்பு தாராளமாக **" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" +"முதல் முறையாக நீங்கள் ஒரு கருவி அல்லது பயிற்சியைக் குறிப்பிடும்போது, அதை உள்ளடக்கிய " +"வழிகாட்டியின் ஒரு பகுதியுடன் இணைக்கவும் அல்லது வேறு இடங்களில் தொடர்புடைய ஆவணத்துடன் " +"இணைக்கவும். வாசகரை ஒரு தேடலைச் சேமிக்கவும்." + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "** பெயரிடும் நடைமுறைகளை மதிக்கவும் **" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" +"கருவிகள், தளங்கள், நபர்கள் மற்றும் பிற சரியான பெயர்ச்சொற்களுக்கு பெயரிடும் போது, " +"தங்களுக்கு விருப்பமான மூலதனத்தைப் பயன்படுத்துங்கள்." + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "தவறு: பிஐபி பயன்படுத்துகிறது…" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "வலது: பிஐபி பயன்படுத்துகிறது…" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "தவறு:… கிட்அப்பில் புரவலன் செய்யப்பட்டது." + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "வலது:… கிட்அப்பில் புரவலன் செய்யப்பட்டது." + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "** பாலின-நடுநிலை பாணியைப் பயன்படுத்தவும் **" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" +"பெரும்பாலும், நீங்கள் *நீங்கள் *, *உங்கள் *மற்றும் *உங்களுடைய *உடன் நேரடியாக வாசகரை " +"உரையாற்றுவீர்கள். இல்லையெனில், பாலின-நடுநிலை பிரதிபெயர்களைப் பயன்படுத்துங்கள் *அவை *, " +"*அவற்றின் *, மற்றும் *அவர்களுடைய *அல்லது பிரதிபெயர்களை முழுவதுமாக தவிர்க்கவும்." + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "தவறு: ஒரு பராமரிப்பாளர் கோப்பை பதிவேற்றுகிறார். பின்னர் அவர்…" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "வலது: ஒரு பராமரிப்பாளர் கோப்பை பதிவேற்றுகிறார். பின்னர் அவர்கள்…" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "வலது: ஒரு பராமரிப்பாளர் கோப்பை பதிவேற்றுகிறார். பின்னர் பராமரிப்பாளர்…" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "** தலைப்புகள் **" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" +"வாசகர் தேடும் சொற்களைப் பயன்படுத்தும் தலைப்புகளை எழுதுங்கள். இதைச் செய்வதற்கான ஒரு சிறந்த " +"வழி, உங்கள் தலைப்பு மறைமுகமான கேள்வியை முடிக்க வேண்டும். எடுத்துக்காட்டாக, ஒரு வாசகர் " +"தெரிந்து கொள்ள விரும்பலாம் *மைலிபரியை எவ்வாறு நிறுவுவது? *எனவே ஒரு நல்ல தலைப்பு " +"*மைலிபரியை நிறுவலாம் *." + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" +"பிரிவு தலைப்புகளில், வாக்கிய வழக்கைப் பயன்படுத்துங்கள். வேறு வார்த்தைகளில் கூறுவதானால், " +"நீங்கள் ஒரு பொதுவான வாக்கியத்தை எழுதுவதால் தலைப்புகளை எழுதுங்கள்." + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "தவறு: பைத்தானைப் பற்றி நீங்கள் தெரிந்து கொள்ள வேண்டிய விசயங்கள்" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "உரிமை: பைத்தானைப் பற்றி நீங்கள் தெரிந்து கொள்ள வேண்டிய விசயங்கள்" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "** எண்கள் **" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" +"உடல் உரையில், எண்களை ஒன்பது முதல் சொற்களாக எழுதுங்கள். அட்டவணையில் உள்ள பிற எண்கள் அல்லது " +"எண்களுக்கு, எண்களைப் பயன்படுத்துங்கள்." + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "பைதான் பயன்பாடுகளை வரிசைப்படுத்துதல்" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "பக்க நிலை" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "முழுமையற்ற" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "கடைசியாக மதிப்பாய்வு செய்யப்பட்டது" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "2021-8-24" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "கண்ணோட்டம்" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "பல வன்பொருள் தளங்களை ஆதரிக்கிறது" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "OS பேக்கேசிங் மற்றும் நிறுவிகள்" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" +"`Pynsist ____ என்பது பைதான் நிரல்களை பைதான்-" +"இன்டர்ச்பிரெட்டருடன் NSIS ஐ அடிப்படையாகக் கொண்ட ஒற்றை நிறுவியில் தொகுக்கும் ஒரு " +"கருவியாகும். பெரும்பாலான சந்தர்ப்பங்களில், பேக்கேசிங் மட்டுமே பயனருக்கு பைதான்-" +"இன்டர்ச்பிரீட்டரின் பதிப்பைத் தேர்வுசெய்து நிரலின் சார்புகளை அறிவிக்க வேண்டும். கருவி " +"விண்டோசிற்கான குறிப்பிட்ட பைதான்-இடைக்காலத்தை பதிவிறக்கம் செய்து, விண்டோச்-" +"செயல்படுத்தக்கூடிய நிறுவியில் அனைத்து சார்புகளையும் தொகுப்பாக மாற்றுகிறது." + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" +"நிறுவப்பட்ட நிரலை தொடக்க-மெனுவில் நிறுவி சேர்க்கும் குறுக்குவழியில் இருந்து தொடங்கலாம். " +"இது கணினியில் வேறு எந்த பைதான் நிறுவலிலிருந்தும் சுயாதீனமாக, அதன் பயன்பாட்டு " +"கோப்பகத்தில் நிறுவப்பட்ட பைதான் மொழிபெயர்ப்பாளரைப் பயன்படுத்துகிறது." + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" +"பைன்சிச்ட்டின் ஒரு பெரிய நன்மை என்னவென்றால், சாளரங்கள் தொகுப்புகளை லினக்சில் உருவாக்க " +"முடியும். பல்வேறு வகையான நிரல்களுக்கு (கன்சோல், சி.யு.ஐ) பல எடுத்துக்காட்டுகள் உள்ளன: " +"ஏதேனும்: `ஆவணங்கள் `. கருவி எம்ஐடி-உரிமத்தின் கீழ் வெளியிடப்படுகிறது." + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "பயன்பாட்டு மூட்டைகள்" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" +"`py2exe ____ என்பது ஒரு தொலைதூர நீட்டிப்பு " +"ஆகும், இது பைத்தான் ச்கிரிப்ட்களிலிருந்து முழுமையான சாளரங்கள் இயங்கக்கூடிய நிரல்களை (32-" +"பிட் மற்றும் 64-பிட்) உருவாக்க அனுமதிக்கிறது. உத்தியோகபூர்வ மேம்பாட்டு சுழற்சியில் " +"சேர்க்கப்பட்டுள்ள பைதான் பதிப்புகள் ஆதரிக்கப்படுகின்றன (பைதான் கிளைகளின் நிலையை` என்பதைக் " +"குறிக்கிறது). PY2EXE கன்சோல் இயங்கக்கூடிய மற்றும் சாளரங்கள் (GUI) இயங்கக்கூடியவற்றை " +"உருவாக்க முடியும். சாளரங்கள் சேவைகளை உருவாக்குதல், மற்றும் டி.எல்.எல்/எக்ச்இ காம் " +"சேவையகங்கள் வேலை செய்யக்கூடும், ஆனால் அது தீவிரமாக ஆதரிக்கப்படவில்லை. டிச்டிடில்ச் " +"நீட்டிப்பு எம்ஐடி-உரிமம் மற்றும் மொசில்லா பொது உரிமம் 2.0 இன் கீழ் வெளியிடப்படுகிறது." + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" +"`py2app ____ என்பது ஒரு பைதான் செட்டுப்டூல்ச் " +"கட்டளை, இது பைதான் ச்கிரிப்ட்களிலிருந்து முழுமையான மேகோச் பயன்பாட்டு மூட்டைகள் மற்றும் " +"செருகுநிரல்களை உருவாக்க உங்களை அனுமதிக்கும். பயன்பாடுகளை உருவாக்க மாகோ களில் PY2APP " +"பயன்படுத்தப்பட வேண்டும் என்பதை நினைவில் கொள்க, இது மற்ற தளங்களில் MAC பயன்பாடுகளை " +"உருவாக்க முடியாது. PY2APP MIT-LICENSE இன் கீழ் வெளியிடப்படுகிறது." + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "யூனிக்ச் (லினக்ச் மற்றும் மேகோச் உட்பட)" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "பெக்ச்" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" +". PEX என்பது கோடிட்டுக் காட்டப்பட்டுள்ள கருத்துக்களின் விரிவாக்கமாகும்: PEP: `441` மற்றும் " +"பைதான் பயன்பாடுகளை சிபி போல எளிமையாக பயன்படுத்துகிறது. PEX கோப்புகளில் பல இயங்குதள-" +"குறிப்பிட்ட பைதான் விநியோகங்கள் கூட இருக்கலாம், அதாவது லினக்ச் மற்றும் மேகோச் முழுவதும் " +"ஒற்றை PEX கோப்பு சிறியதாக இருக்கும். PEX அப்பாச்சி உரிமம் 2.0 இன் கீழ் வெளியிடப்பட்டது." + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "உள்ளமைவு மேலாண்மை" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "விநியோக தொகுப்பு எதிராக இறக்குமதி தொகுப்பு" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" +"பல்வேறு கருத்துக்கள் பொதுவாக \"தொகுப்பு\" என்ற வார்த்தையால் குறிப்பிடப்படுகின்றன. பைதான் " +"பேக்கேசிங், \"விநியோக தொகுப்பு\" மற்றும் \"இறக்குமதி தொகுப்பு\" ஆகியவற்றில் இரண்டு " +"தனித்துவமான ஆனால் தொடர்புடைய அர்த்தங்களுக்கு இடையிலான வேறுபாடுகளை இந்த பக்கம் " +"தெளிவுபடுத்துகிறது." + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "விநியோக தொகுப்பு என்றால் என்ன?" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" +"விநியோக தொகுப்பு என்பது நீங்கள் நிறுவக்கூடிய மென்பொருளின் ஒரு பகுதி. பெரும்பாலான " +"நேரங்களில், இது \"திட்டத்திற்கு\" ஒத்ததாகும். நீங்கள் `` பிஐபி நிறுவவும் pkg`` அல்லது " +"உங்கள் `` pyproject.toml`` இல் `` சார்புகள் = [\"pkg\"] `` `` pkg`` ஒரு விநியோக " +"தொகுப்பின் பெயர். பைதான் நூலகங்கள் மற்றும் கருவிகளை நிறுவுவதற்கான மிகவும் பரவலாக " +"அறியப்பட்ட மையப்படுத்தப்பட்ட மூலமான PYPI_ ஐ நீங்கள் தேடும்போது அல்லது உலாவும்போது, நீங்கள் " +"பார்ப்பது விநியோக தொகுப்புகளின் பட்டியல். மாற்றாக, ஒரு திட்டத்தின் ஒரு குறிப்பிட்ட " +"பதிப்பைக் கொண்ட ஒரு குறிப்பிட்ட கோப்பைக் குறிக்க \"விநியோக தொகுப்பு\" என்ற சொல் " +"பயன்படுத்தப்படலாம்." + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" +"லினக்ச் உலகில், ஒரு \"விநியோக தொகுப்பு\", பொதுவாக \"டிச்ட்ரோ தொகுப்பு\" அல்லது " +"\"தொகுப்பு\" என சுருக்கமாக, `லினக்ச் விநியோக ` _ இன் கணினி தொகுப்பு " +"மேலாளரால் வழங்கப்பட்ட ஒன்று என்பதை நினைவில் கொள்க, இது வேறு பொருள்." + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "இறக்குமதி தொகுப்பு என்றால் என்ன?" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" +"இறக்குமதி தொகுப்பு ஒரு பைதான் தொகுதி. ஆகவே, உங்கள் பைதான் குறியீட்டில் பி.கே.சி " +"இறக்குமதி ஃபன்சி` இலிருந்து `` இறக்குமதி pkg`` அல்லது `` எழுதும்போது, `` pkg`` " +"என்பது இறக்குமதி தொகுப்பின் பெயர். இன்னும் துல்லியமாக, இறக்குமதி தொகுப்புகள் சிறப்பு " +"பைதான் தொகுதிகள் ஆகும், அவை சப்மோடூல்களைக் கொண்டிருக்கலாம். எடுத்துக்காட்டாக, `` Numpy`` " +"தொகுப்பில் `` numpy.linalg`` மற்றும் `` numpy.fft`` போன்ற தொகுதிகள் உள்ளன. வழக்கமாக, " +"ஒரு இறக்குமதி தொகுப்பு என்பது கோப்பு முறைமையில் ஒரு கோப்பகமாகும், இதில் `` .பீ`` " +"கோப்புகள் மற்றும் துணை பேக்கேச்கள் துணை அடைப்புகளாக தொகுதிகள் உள்ளன." + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "இறக்குமதி தொகுப்பை நீங்கள் வழங்கும் விநியோக தொகுப்பை நிறுவியவுடன் பயன்படுத்தலாம்." + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "விநியோக தொகுப்புகள் மற்றும் இறக்குமதி தொகுப்புகளுக்கு இடையிலான இணைப்புகள் என்ன?" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" +"பெரும்பாலான நேரங்களில், ஒரு விநியோக தொகுப்பு ஒரு ஒற்றை இறக்குமதி தொகுப்பை (அல்லது " +"பேக்கேச் அல்லாத தொகுதி), பொருந்தக்கூடிய பெயருடன் வழங்குகிறது. எடுத்துக்காட்டாக, `` " +"பிஐபி நிறுவுதல் எண் `` உங்களை `` இறக்குமதி numpy`` உங்களை அனுமதிக்கிறது." + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" +"இருப்பினும், இது ஒரு மாநாடு மட்டுமே. PYPI மற்றும் பிற தொகுப்பு குறியீடுகள் * விநியோக " +"தொகுப்பின் பெயர் மற்றும் அது வழங்கும் இறக்குமதி தொகுப்புகளுக்கு இடையில் எந்த உறவையும் " +"செயல்படுத்த வேண்டாம். ." + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" +"ஒரு விநியோக தொகுப்பு வேறு பெயருடன் இறக்குமதி தொகுப்பை வழங்க முடியும். பட " +"செயலாக்கத்திற்கான பிரபலமான தலையணை_ நூலகம் இதற்கு ஒரு எடுத்துக்காட்டு. அதன் விநியோக " +"தொகுப்பு பெயர் `` தலையணை``, ஆனால் இது இறக்குமதி தொகுப்பை `` pil`` வழங்குகிறது. இது " +"வரலாற்று காரணங்களுக்காக: தலையணை PIL நூலகத்தின் ஒரு முட்கரண்டியாகத் தொடங்கியது, இதனால் " +"இது இறக்குமதி பெயரை `` pil`` உடன் வைத்திருந்தது, இதனால் தற்போதுள்ள PIL பயனர்கள் சிறிய " +"முயற்சியுடன் தலையணைக்கு மாற முடியும். மிகவும் பொதுவாக, தற்போதுள்ள நூலகத்தின் முட்கரண்டி " +"விநியோக தொகுப்பு மற்றும் இறக்குமதி தொகுப்புக்கு இடையில் மாறுபட்ட பெயர்களுக்கு ஒரு " +"பொதுவான காரணம்." + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" +"கொடுக்கப்பட்ட தொகுப்பு குறியீட்டில் (PYPI போன்றது), விநியோக தொகுப்பு பெயர்கள் " +"தனித்துவமாக இருக்க வேண்டும். மறுபுறம், இறக்குமதி தொகுப்புகளுக்கு அத்தகைய தேவை இல்லை. " +"அதே பெயருடன் இறக்குமதி தொகுப்புகளை பல விநியோக தொகுப்புகள் வழங்கலாம். மீண்டும், ஃபோர்க்ச் " +"இதற்கு ஒரு பொதுவான காரணம்." + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" +"மாறாக, ஒரு விநியோக தொகுப்பு பல இறக்குமதி தொகுப்புகளை வழங்க முடியும், இருப்பினும் " +"இது குறைவாகவே காணப்படுகிறது. ஒரு எடுத்துக்காட்டு ATTRS_ விநியோக தொகுப்பு, இது ஒரு " +"புதிய பநிஇ உடன் `` attrs`` இறக்குமதி தொகுப்பு இரண்டையும் வழங்குகிறது, மேலும் பழைய " +"ஆனால் ஆதரிக்கப்பட்ட பநிஇ உடன் `` attr`` இறக்குமதி தொகுப்பு." + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" +"விநியோக தொகுப்பு பெயர்கள் மற்றும் இறக்குமதி தொகுப்பு பெயர்கள் எவ்வாறு ஒப்பிடுகின்றன?" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" +"இறக்குமதி தொகுப்புகளில் செல்லுபடியாகும் பைதான் அடையாளங்காட்டிகள் அவற்றின் பெயராக இருக்க " +"வேண்டும் (தி: ரெஃப்: `சரியான விதிகள் <பைதான்: அடையாளங்காட்டிகள்>` பைதான் ஆவணத்தில் " +"காணப்படுகின்றன) [#அடையாளங்காட்டி அல்லாத-மோட்-பெயர்] _. குறிப்பாக, அவர்கள் " +"அடிக்குறிப்புகளை `` _`` என்ற சொல் பிரிப்பானாகப் பயன்படுத்துகிறார்கள், மேலும் அவை வழக்கு " +"உணர்திறன் கொண்டவை." + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" +"மறுபுறம், விநியோக தொகுப்புகள் ஐபன்களைப் பயன்படுத்தலாம் `` -`` அல்லது `` _`` ஐ " +"அடிக்கோடிட்டுக் காட்டலாம். அவை `` .`` புள்ளிகளையும் கொண்டிருக்கலாம், இது சில நேரங்களில் " +"ஒரு துணைப் பேக்கேசை பேக்கேசிங் செய்யப் பயன்படுகிறது: ref: `பெயர்வெளி தொகுப்பு " +"<பேக்கேசிங்-பெயர்ச்பேச்-பேக்கேச்கள்>`. பெரும்பாலான நோக்கங்களுக்காக, அவை வழக்குக்கு " +"உணர்ச்சியற்றவை மற்றும் `` -` எதிராக `` _`` வேறுபாடுகள், எ.கா. விதிகள் " +"கொடுக்கப்பட்டுள்ளன: ref: `பெயர் இயல்பாக்கம் விவரக்குறிப்பு <பெயர்-இயல்பாக்கம்>`)." + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" +"செல்லுபடியாகும் பைதான் அடையாளங்காட்டி இல்லாத தொகுப்புகள்/தொகுதிகளை அவற்றின் பெயராக " +"இறக்குமதி செய்வது தொழில்நுட்ப ரீதியாக சாத்தியமானது என்றாலும், பயன்படுத்துகிறது: டாக்: " +"`இறக்குமதி <பைதான்: நூலகம்/இறக்குமதி லிப்>`, இது மறைந்துபோகும் அரிதானது மற்றும் " +"கடுமையாக ஊக்கமளிக்கிறது." + +#: ../source/discussions/downstream-packaging.rst:5 +#, fuzzy +#| msgid "Operating system packages" +msgid "Supporting downstream packaging" +msgstr "இயக்க முறைமை தொகுப்புகள்" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:51 +#, fuzzy +#| msgid "Python source distributions" +msgid "Provide complete source distributions" +msgstr "பைதான் மூல வழங்கல்" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" +"** கலந்துரையாடல்கள் ** ஒரு குறிப்பிட்ட தலைப்பைப் பற்றிய விரிவான தகவல்களை வழங்குவதில் " +"கவனம் செலுத்துகின்றன. நீங்கள் விசயங்களைச் செய்ய முயற்சிக்கிறீர்கள் என்றால், காண்க: DOC: `/" +"வழிகாட்டிகள்/குறியீட்டு`." + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "Install_requires vs தேவைகள் கோப்புகள்" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" +"`` install_requires`` என்பது ஒரு: ref: `setuptools`: கோப்பு:` setup.py` முக்கிய " +"சொல் ஒரு திட்டம் ** குறைந்தபட்சமாக ** சரியாக இயங்க வேண்டும் என்பதைக் குறிப்பிட பயன்படுத்த " +"வேண்டும். திட்டத்தை நிறுவும் போது: ref: `பிப்`, இது அதன் சார்புகளை நிறுவ பயன்படும் " +"விவரக்குறிப்பு." + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" +"எடுத்துக்காட்டாக, திட்டத்திற்கு A மற்றும் B தேவைப்பட்டால், உங்கள் `` install_requires`` " +"அவ்வாறு இருக்கும்:" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" +"கூடுதலாக, அறியப்பட்ட குறைந்த அல்லது மேல் எல்லைகளைக் குறிப்பது சிறந்த நடைமுறையாகும்." + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" +"எடுத்துக்காட்டாக, உங்கள் திட்டத்திற்கு குறைந்தது 'A' இன் V1 மற்றும் 'B' இன் V2 " +"தேவைப்படுகிறது, எனவே இது அப்படியே இருக்கும்:" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" +"'A' திட்டம் அதன் V2 இல் ஒரு மாற்றத்தை அறிமுகப்படுத்தியது, இது உங்கள் திட்டத்தின் " +"பொருந்தக்கூடிய தன்மையை 'A' இன் V2 மற்றும் அதற்குப் பிறகு உடைக்கிறது, எனவே V2 ஐ " +"அனுமதிக்காதது அர்த்தமுள்ளதாக இருக்கும்:" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" +"குறிப்பிட்ட பதிப்புகளுக்கு சார்புகளை பின் செய்ய `` install_requires`` ஐப் " +"பயன்படுத்துவது அல்லது துணை சார்புநிலைகளைக் குறிப்பிடுவது சிறந்த நடைமுறையாக " +"கருதப்படவில்லை (அதாவது உங்கள் சார்புகளின் சார்புநிலைகள்). இது அதிகப்படியான " +"கட்டுப்பாடானது, மேலும் பயனர்கள் சார்பு மேம்பாடுகளின் நன்மையைப் பெறுவதைத் தடுக்கிறது." + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" +"கடைசியாக, `` Install_requires`` என்பது \"சுருக்கம்\" தேவைகளின் பட்டியல் என்பதை " +"புரிந்து கொள்ள வேண்டியது தேவை, அதாவது பெயர்கள் மற்றும் பதிப்பு கட்டுப்பாடுகள் " +"சார்புநிலைகள் எங்கிருந்து நிறைவு செய்யப்படும் என்பதை தீர்மானிக்காத (அதாவது எந்த குறியீட்டு " +"அல்லது மூலத்திலிருந்து). எங்கே (அதாவது அவை எவ்வாறு \"கான்கிரீட்\" செய்யப்பட வேண்டும்) " +"நிறுவும் நேரத்தில் தீர்மானிக்கப்பட வேண்டும்: குறிப்பு: `பிப்` விருப்பங்கள். [1] _" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "தேவைகள் கோப்புகள்" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" +":ref:`Requirements கோப்புகள் ` described பெரும்பாலானவை " +"simply, அரே just a பட்டியல் of :ref:`pip:pip install` arguments placed into a " +"file." + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" +"அதேசமயம் `` Install_requires`` ஒரு திட்டத்திற்கான சார்புகளை வரையறுக்கிறது,: ref: " +"`தேவைகள் கோப்புகள் ` ஒரு முழுமையான பைதான் சூழலுக்கான தேவைகளை " +"வரையறுக்க பெரும்பாலும் பயன்படுத்தப்படுகின்றன." + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" +"`` Install_requires`` தேவைகள் மிகக் குறைவு, தேவைகள் கோப்புகள் பெரும்பாலும் " +"அடைவதற்கான நோக்கத்திற்காக பின் செய்யப்பட்ட பதிப்புகளின் முழுமையான பட்டியலைக் " +"கொண்டிருக்கின்றன: குறிப்பு: `மீண்டும் மீண்டும் செய்யக்கூடிய நிறுவல்கள் ` ஒரு முழுமையான சூழலின்." + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" +"`` Install_requires`` தேவைகள் \"சுருக்கம்\", அதாவது எந்தவொரு குறிப்பிட்ட " +"குறியீட்டுடனும் தொடர்புடையவை அல்ல, தேவைகள் கோப்புகளில் பெரும்பாலும் தேவைகள் `` --index-" +"URL`` அல்லது ``-FIND-LINKS`` போன்ற பிஐபி விருப்பங்கள் உள்ளன கான்கிரீட் \", அதாவது " +"தொகுப்புகளின் ஒரு குறிப்பிட்ட குறியீட்டு அல்லது கோப்பகத்துடன் தொடர்புடையது. [1] _" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" +"அதேசமயம் `` Install_requires`` ஒரு நிறுவலின் போது PIP ஆல் தானாகவே பகுப்பாய்வு " +"செய்யப்படுகிறது, தேவைகள் கோப்புகள் இல்லை, மேலும் ஒரு பயனர் குறிப்பாக `` பைதான் -எம் " +"பிஐபி நிறுவல் -r`` ஐப் பயன்படுத்தி அவற்றை நிறுவும்போது மட்டுமே பயன்படுத்தப்படுகிறது." + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" +"\"சுருக்கம்\" Vs \"கான்கிரீட்\" தேவைகள் பற்றி மேலும் அறிய, https://caremad.io/posts/" +"2013/07/setup-vs-requirement/ ஐப் பார்க்கவும்." + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "தொகுப்பு வடிவங்கள்" + +#: ../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 "" +"PYPI_: ** மூல விநியோகங்கள் **, அல்லது ** Sdists ** போன்ற தொகுப்பு குறியீடுகளில் " +"இரண்டு வடிவங்களில் கோப்புகளை நீங்கள் காண்பீர்கள், மற்றும் ** பைனரி விநியோகங்கள் **, பொதுவாக " +"** சக்கரங்கள் ** என்று அழைக்கப்படுகின்றன. எடுத்துக்காட்டாக, பிஐபி 23.3.1 " +"`_ க்கான` பைபி பக்கம் இரண்டு கோப்புகளை பதிவிறக்கம் செய்ய அனுமதிக்கிறது, `` பிஐபி " +"-23.3.1.tar.gz`` மற்றும் `` PIP-23.3.1-NONE -any.whl``. முந்தையது ஒரு SDIST, " +"பிந்தையது ஒரு சக்கரம். கீழே விளக்கப்பட்டுள்ளபடி, இவை வெவ்வேறு நோக்கங்களுக்கு உதவுகின்றன. " +"பைபியில் (அல்லது வேறு இடங்களில்) ஒரு தொகுப்பை வெளியிடும்போது, நீங்கள் எப்போதும் ஒரு " +"SDIST மற்றும் ஒன்று அல்லது அதற்கு மேற்பட்ட சக்கரம் இரண்டையும் பதிவேற்ற வேண்டும்." + +#: ../source/discussions/package-formats.rst:21 +msgid "What is a source distribution?" +msgstr "மூல வழங்கல் என்றால் என்ன?" + +#: ../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 "" +"கருத்தியல் ரீதியாக, ஒரு மூல வழங்கல் என்பது மூல வடிவத்தில் உள்ள மூலக் குறியீட்டின் " +"காப்பகமாகும். இணக்கமாக, ஒரு SDIST என்பது மூலக் குறியீட்டைக் கொண்ட `` .tar.gz`` " +"காப்பகமாகும், மேலும் திட்ட மெட்டாடேட்டாவை வைத்திருக்கும் `` pkg-info`` எனப்படும் கூடுதல் " +"சிறப்புக் கோப்பு. இந்த கோப்பின் இருப்பு மெட்டாடேட்டாவைக் கணக்கிடத் தேவையில்லை என்பதன் மூலம் " +"பேக்கேசிங் கருவிகளை மிகவும் திறமையாக இருக்க உதவுகிறது. `` பி.கே.சி-இன்ஃபோ`` கோப்பு " +"குறிப்பிடப்பட்ட வடிவமைப்பைப் பின்பற்றுகிறது: குறிப்பு: `கோர்-மெட்டாடேட்டா` மற்றும் கையால் " +"எழுதப்பட விரும்பவில்லை [#கோர்-மெட்டாடேட்டா-வடிவ] _." + +#: ../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 "" +"யுனிக்ச் இயங்குதளங்களில் (லினக்ச் மற்றும் மேகோச் போன்றவை) `` கரிக்கீல் -xvf`` போன்ற தார் " +"காப்பகங்களுடன் பணிபுரிய நிலையான கருவிகளைப் பயன்படுத்தி ஒரு SDIST இன் உள்ளடக்கங்களை " +"நீங்கள் ஆய்வு செய்யலாம், OR: ref: `இன் கட்டளை வரி இடைமுகம் பைத்தானின் டார்ஃபைல் தொகுதி " +"<பைதான்: டார்ஃபைல்-கமாண்ட்லைன்> `எந்த தளத்திலும்." + +#: ../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 "" +"SDISTS பேக்கேசிங் சுற்றுச்சூழல் அமைப்பில் பல நோக்கங்களுக்காக பணி செய்கிறது. எப்போது: " +"ref: `பிப்`, நிலையான பைதான் தொகுப்பு நிறுவி, நிறுவ ஒரு சக்கரத்தைக் கண்டுபிடிக்க " +"முடியவில்லை, அது ஒரு மூல விநியோகத்தைப் பதிவிறக்குவது, அதிலிருந்து ஒரு சக்கரத்தை " +"தொகுத்தல் மற்றும் சக்கரத்தை நிறுவுதல் ஆகியவற்றில் மீண்டும் விழும். மேலும், SDISTS " +"பெரும்பாலும் கீழ்நிலை பேக்கேசர்களால் (லினக்ச் விநியோகங்கள், கான்டா, ஓம் ப்ரூ மற்றும் மேக்போர்ட் " +"போன்றவை, ...) தொகுப்பு மூலமாகப் பயன்படுத்தப்படுகின்றன, பல்வேறு காரணங்களுக்காக, அவற்றை " +"விரும்பலாம், எ.கா., ஒரு அறிவிலி களஞ்சியத்திலிருந்து இழுக்கலாம் ." + +#: ../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`, எ.கா." + +#: ../source/discussions/package-formats.rst:50 +msgid "" +"If you want technical details on the sdist format, read the :ref:`sdist " +"specification `." +msgstr "" +"SDIST வடிவத்தில் தொழில்நுட்ப விவரங்களை நீங்கள் விரும்பினால், அதைப் படியுங்கள்: Ref: " +"`SDIST விவரக்குறிப்பு <மூல-விநியோக வடிவங்கள்>`." + +#: ../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 "" +"தொகுப்புகளுக்கான SDISTS மற்றும் சக்கரங்களுக்கு இடையே ஒரு பெரிய வேறுபாடு உள்ளது: கால: " +"`நீட்டிப்பு தொகுதிகள் <நீட்டிப்பு தொகுதி>`, சி, சி ++ மற்றும் ரச்ட் போன்ற தொகுக்கப்பட்ட " +"மொழிகளில் எழுதப்பட்டவை, அவை இயங்குதள சார்ந்த இயந்திரக் குறியீட்டில் தொகுக்கப்பட வேண்டும். " +"இந்த தொகுப்புகள் மூலம், சக்கரங்களில் மூலக் குறியீடு இல்லை (சி மூல கோப்புகள் போன்றவை) ஆனால் " +"தொகுக்கப்பட்ட, இயங்கக்கூடிய குறியீடு (`` .SO`` லினக்சில் கோப்புகள் அல்லது சாளரங்களில் " +"டி.எல்.எல்)." + +#: ../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 "" +"மேலும், ஒரு திட்டத்தின் பதிப்பிற்கு ஒரே ஒரு SDIST மட்டுமே இருக்கும்போது, பல சக்கரங்கள் " +"இருக்கலாம். மீண்டும், நீட்டிப்பு தொகுதிகளின் சூழலில் இது மிகவும் பொருத்தமானது. ஒரு " +"நீட்டிப்பு தொகுதியின் தொகுக்கப்பட்ட குறியீடு ஒரு இயக்க முறைமை மற்றும் செயலி கட்டமைப்புடன் " +"பிணைக்கப்பட்டுள்ளது, மேலும் பெரும்பாலும் பைதான் மொழிபெயர்ப்பாளரின் பதிப்பிலும் " +"பிணைக்கப்பட்டுள்ளது (இல்லையென்றால்: குறிப்பு: `பைதான் நிலையான அபி ` பயன்படுத்தப்படுகிறது)." + +#: ../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 "" +"தூய-பைதான் தொகுப்புகளுக்கு, Sdists மற்றும் சக்கரங்களுக்கு இடையிலான வேறுபாடு குறைவாகக் " +"குறிக்கப்பட்டுள்ளது. எல்லா தளங்களுக்கும் பைதான் பதிப்புகளுக்கும் பொதுவாக ஒரு ஒற்றை சக்கரம் " +"உள்ளது. பைதான் என்பது ஒரு விளக்கமளிக்கப்பட்ட மொழியாகும், இது நேரத்திற்கு முன்னதாகத் " +"தேவையில்லை, எனவே சக்கரங்களில் sdists போலவே `` .py`` கோப்புகள் உள்ளன." + +#: ../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 "" +"`` .பிசி`` பைட்கோட் கோப்புகளைப் பற்றி நீங்கள் யோசிக்கிறீர்கள் என்றால்: அவை சக்கரங்களில் " +"சேர்க்கப்படவில்லை, ஏனெனில் அவை உருவாக்க மலிவானவை, மேலும் அவை உட்பட ஒரு ஒற்றை ஒற்றை " +"பதிப்பிற்கு பதிலாக ஒரு சக்கரத்தை விநியோகிக்க ஏராளமான தொகுப்புகளை தேவையற்ற முறையில் " +"கட்டாயப்படுத்தும் சக்கரம். அதற்கு பதிலாக, நிறுவிகள்: ref: `PIP` தொகுப்பை நிறுவும் போது " +"அவற்றை உருவாக்கவும்." + +#: ../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 "" +"இவ்வாறு கூறப்படுவதால், தூய பைதான் திட்டங்களுக்கு கூட, SDISTS மற்றும் சக்கரங்களுக்கு " +"இடையில் இன்னும் முக்கியமான வேறுபாடுகள் உள்ளன. சக்கரங்கள் நிறுவப்பட வேண்டியவற்றைக் " +"கொண்டிருக்க வேண்டும், அதற்கு மேல் எதுவும் இல்லை. குறிப்பாக, சக்கரங்கள் ஒருபோதும் சோதனைகள் " +"மற்றும் ஆவணங்களை சேர்க்கக்கூடாது, அதே நேரத்தில் Sdists பொதுவாக செய்கின்றன. மேலும், சக்கர " +"வடிவம் SDIST ஐ விட மிகவும் சிக்கலானது. எடுத்துக்காட்டாக, இது ஒரு சிறப்புக் கோப்பை " +"உள்ளடக்கியது - `` பதிவு`` - இது சக்கரத்தில் உள்ள அனைத்து கோப்புகளையும் அவற்றின் " +"உள்ளடக்கத்தின் ஆசுடன் பட்டியலிடுகிறது, இது பதிவிறக்கத்தின் ஒருமைப்பாட்டின் பாதுகாப்பு " +"சோதனையாக." + +#: ../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 "" +"ஒரு பார்வையில், \"வெற்று மற்றும் அடிப்படை\" தூய பைதான் திட்டங்களுக்கு சக்கரங்கள் உண்மையில் " +"தேவையா என்று நீங்கள் ஆச்சரியப்படலாம். SDIST களின் நெகிழ்வுத்தன்மை காரணமாக, PIP போன்ற " +"நிறுவிகள் SDISTS இலிருந்து நேரடியாக நிறுவ முடியாது என்பதை நினைவில் கொள்ளுங்கள் - " +"அவை முதலில் ஒரு சக்கரத்தை உருவாக்க வேண்டும், இதைச் செயல்படுத்துவதன் மூலம்: கால: " +"`பின்தளத்தில் உருவாக்குங்கள்` SDIST குறிப்பிடுகிறது (கட்டர் பின்தளத்தில் அனைத்தையும் " +"செய்யலாம் சி நீட்டிப்புகளை தொகுத்தல் போன்ற சக்கரத்தை உருவாக்கும் போது மாற்றங்கள்). இந்த " +"காரணத்திற்காக, தூய பைதான் திட்டத்திற்கு கூட, நீங்கள் எப்போதும் * ஒரு SDIST மற்றும் PYPI " +"அல்லது பிற தொகுப்பு குறியீடுகளுக்கு ஒரு சக்கரம் இரண்டையும் பதிவேற்ற வேண்டும். ஒரு சக்கரம் " +"நேரடியாக நிறுவக்கூடியதாக இருப்பதால், இது உங்கள் பயனர்களுக்கு நிறுவலை மிக வேகமாக " +"செய்கிறது. நிறுவப்பட வேண்டிய கோப்புகளை மட்டுமே சேர்ப்பதன் மூலம், சக்கரங்கள் சிறிய " +"பதிவிறக்கங்களையும் உருவாக்குகின்றன." + +#: ../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 "" +"தொழில்நுட்ப மட்டத்தில், ஒரு சக்கரம் ஒரு சிப் காப்பகம் (தார் காப்பகங்கள் SDISTS போலல்லாமல்). " +"லினக்ச் மற்றும் மேகோச் போன்ற யூனிக்ச் இயங்குதளங்களில் `` அன்சிப்`` ஐப் பயன்படுத்தி, எ.கா. " +"பைத்தானின் சிப்ஃபைல் தொகுதியின் இடைமுகம் <பைதான்: சிப்ஃபைல்-கமாண்ட்லைன்> `. சக்கரம் " +"உங்களுக்குத் தேவையான அனைத்து கோப்புகளையும் உள்ளடக்கியுள்ளதா என்பதைச் சரிபார்க்க இது " +"மிகவும் பயனுள்ளதாக இருக்கும்." + +#: ../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 "" +"ஒரு சக்கரத்தின் உள்ளே, நீங்கள் தொகுப்பின் கோப்புகளையும், கூடுதல் கோப்பகத்தையும் காணலாம்: " +"SAMP: `{package_name}-{version} .dist-info`. இந்த கோப்பகத்தில் `` மெட்டாடேட்டா`` " +"கோப்பு உள்ளிட்ட பல்வேறு கோப்புகள் உள்ளன, இது Sdists இல் `` pkg-info`` க்கு " +"சமமானதாகும், அத்துடன் `` பதிவு``. உங்கள் சக்கரங்களில் இருந்து கோப்புகள் எதுவும் இல்லை " +"என்பதை உறுதிப்படுத்த இது பயனுள்ளதாக இருக்கும்." + +#: ../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 "" +"ஒரு சக்கரத்தின் கோப்பு பெயர் (அரிதாகவே பயன்படுத்தப்படும் சில அம்சங்களை புறக்கணித்து) " +"இதுபோன்று தெரிகிறது :: SAMP: `{package_name}-{version}-{python_tag}-{abi_tag}-" +"{platform_tag} .whl`. இந்த பெயரிடும் மாநாடு எந்த தளங்கள் மற்றும் பைதான் பதிப்புகள் " +"சக்கரம் இணக்கமானது என்பதை அடையாளம் காட்டுகிறது. எடுத்துக்காட்டாக, `` பிஐபி -23.3.1-பய் " +"3-none-yn.whl`` என்ற பெயர் இதன் பொருள்:" + +#: ../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 "" +"(``py3``) This wheel can be installed on any implementation of பைதான் 3, " +"whether CPython, the பெரும்பாலானவை widely used பைதான் implementation, or an " +"alternative implementation like PyPy_;" + +#: ../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 "" +"தூய பைதான் திட்டங்களுக்கு `` py3-none-any-`` முறை பொதுவானது. நீட்டிப்பு தொகுதிகள் " +"கொண்ட தொகுப்புகள் பொதுவாக பல சக்கரங்களை மிகவும் சிக்கலான குறிச்சொற்களுடன் அனுப்புகின்றன." + +#: ../source/discussions/package-formats.rst:130 +msgid "" +"All technical details on the wheel format can be found in the :ref:`wheel " +"specification `." +msgstr "" +"சக்கர வடிவத்தில் உள்ள அனைத்து தொழில்நுட்ப விவரங்களையும் இதில் காணலாம்: ref: `சக்கர " +"விவரக்குறிப்பு <பைனரி-டிச்ட்ரிபியூசன்-ஃபார்மாட்>`." + +#: ../source/discussions/package-formats.rst:138 +msgid "What about eggs?" +msgstr "முட்டைகள் பற்றி என்ன?" + +#: ../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 "" +"\"முட்டை\" என்பது ஒரு பழைய தொகுப்பு வடிவமாகும், இது சக்கர வடிவத்துடன் " +"மாற்றப்பட்டுள்ளது. இதை இனி பயன்படுத்தக்கூடாது. ஆகச்ட் 2023 முதல், பைபி `முட்டை " +"பதிவேற்றங்களை நிராகரிக்கிறது <பைபி-எக்ச்-டி.இ.பி." + +#: ../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 "" +"முட்டையின் வடிவம் அறிமுகப்படுத்தப்பட்டது: ref: `setuptools` 2004 இல், சக்கர வடிவம் " +"அறிமுகப்படுத்தப்பட்டது: PEP:` 427` 2012 இல்." + +#: ../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 "" +"சக்கர காப்பகங்களில் `` .பிசி`` கோப்புகள் இல்லை. ஆகையால், விநியோகத்தில் பைதான் கோப்புகள் " +"மட்டுமே இருக்கும்போது (அதாவது தொகுக்கப்பட்ட நீட்டிப்புகள் இல்லை), மற்றும் பைத்தான் 2 மற்றும் " +"3 உடன் இணக்கமானது sdist \")>`." + +#: ../source/discussions/package-formats.rst:161 +msgid "" +"Wheel uses standard :ref:`.dist-info directories `. Egg used ``.egg-info``." +msgstr "" +"வீல் தரநிலையைப் பயன்படுத்துகிறது: ref: `.டிச்ட்-இன்ஃபோ கோப்பகங்கள் <பதிவு-நிறுவப்பட்ட-" +"பேக்கேச்கள்>`. முட்டை `` .egg-info``." + +#: ../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 "" +"சக்கரத்தில் ஒரு: குறிப்பு உள்ளது: `பணக்கார கோப்பு பெயரிடும் மாநாடு <சக்கர-கோப்பு-பெயர்-" +"ச்பெக்>`. ஒரு ஒற்றை சக்கர காப்பகம் பல பைதான் மொழி பதிப்புகள் மற்றும் செயலாக்கங்கள், ABIS " +"மற்றும் கணினி கட்டமைப்புகளுடன் அதன் பொருந்தக்கூடிய தன்மையைக் குறிக்கலாம்." + +#: ../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 "" +"இந்த வடிவம் மின்னஞ்சல் அடிப்படையிலானது. இது இன்று தேர்வு செய்யப்பட வாய்ப்பில்லை என்றாலும், " +"பின்னோக்கி பொருந்தக்கூடிய பரிசீலனைகள் நியமன வடிவமாக வைக்கப்படுவதற்கு வழிவகுக்கிறது. " +"பயனர் பார்வையில், இது பெரும்பாலும் கண்ணுக்கு தெரியாதது, ஏனெனில் மேனிலை தரவு பயனரால் " +"கட்டிய பின்தளத்தில் புரிந்து கொள்ளப்பட்ட விதத்தில் குறிப்பிடப்படுகிறது, பொதுவாக `` " +"[திட்டம்] `` `pyproject.toml`` இல், மற்றும் மொழிபெயர்க்கப்பட்டுள்ளது பின்தளத்தில் `` pkg-" +"info`` இல் உருவாக்குங்கள்." + +#: ../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: `இது அதிகாரப்பூர்வமாக இந்த நேரத்தில் " +"ஆதரிக்கப்படவில்லை <பைனரி-விநியோகத்தை உருவாக்கும்-இறக்குமதி-சக்கர>`." + +#: ../source/discussions/pip-vs-easy-install.rst:6 +msgid "pip vs easy_install" +msgstr "PIP vs Ease_install" + +#: ../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 "" +". நிறுவும் நேரத்தில் இது குறிப்பிடத்தக்கதாக இருந்தது: கால: `தொகுப்புகள் <விநியோக " +"தொகுப்பு>` இருந்து: கால: `பைபி <பைதான் தொகுப்பு குறியீட்டு (PYPI)>` தேவை " +"குறிப்பான்களைப் பயன்படுத்துதல் மற்றும் தானாகவே சார்புகளை நிறுவுதல்." + +#: ../source/discussions/pip-vs-easy-install.rst:14 +#, fuzzy +#| 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." +msgid "" +":ref:`pip` came later in 2008, as an 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 "" +". தொகுப்புகளை நிறுவாத நேரத்தில் இது குறிப்பிடத்தக்கதாக இருந்தது: கால: `முட்டை " +"<முட்டை>` அல்லது இருந்து: கால: `முட்டை <முட்டை>` (ஆனால் வெறுமனே 'தட்டையான' " +"தொகுப்புகளிலிருந்து: கால: `Sdists `), மற்றும் " +"யோசனையை அறிமுகப்படுத்துதல்: குறிப்பு:` தேவைகள் கோப்புகள் `, " +"இது பயனர்களுக்கு சூழல்களை எளிதில் நகலெடுக்க சக்தியைக் கொடுத்தது." + +#: ../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 "" +"பிஐபி மற்றும் நீக்கப்பட்ட ஈசி_இன்ச்டால் ஆகியவற்றுக்கு இடையிலான முக்கியமான வேறுபாடுகளின் " +"முறிவு இங்கே:" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "இதிலிருந்து நிறுவுகிறது: கால: `சக்கரங்கள் `" + +#: ../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 "ஆம் (`` பைதான் -எம் பிப் நிறுவல் நீக்குதல்``)" + +#: ../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 "ஆம் (: குறிப்பு: `தேவைகள் கோப்பு <பிப்: தேவைகள் கோப்பு>`)" + +#: ../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 "ஆம் (`` பைதான் -எம் பிப் பட்டியல்`` மற்றும் `` பைதான் -எம் பிப் ஃப்ரீச்``)" + +#: ../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 "'பிளாட்' தொகுப்புகள்: கோப்பு: `முட்டை-இன்ஃபோ` மேனிலை தரவு." + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "இணைக்கப்பட்ட முட்டை வடிவம்" + +#: ../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 "இதிலிருந்து நிறுவுகிறது: கால: `முட்டை <முட்டை>`" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "`பைலாஞ்சர் ஆதரவு`_" + +#: ../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 ": குறிப்பு: `மல்டி-பதிப்பு நிறுவல்கள்`" + +#: ../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 "மெய்நிகர்இன்வியில் மட்டுமே" + +#: ../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 "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "`` Setup.py`` நீக்கப்பட்டதா?" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "இல்லை,: கால: `setup.py` மற்றும்: ref:` setuptools` நீக்கப்படவில்லை." + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" +"Setuptools ஒரு: கால: `பின்தளத்தில் உருவாக்கு` பைதான் திட்டங்களை பேக்கேசிங் செய்வதற்கு " +"முற்றிலும் பயன்படுத்தக்கூடியது. மேலும்: கோப்பு: `setup.py` என்பது இதற்கான சரியான " +"உள்ளமைவு கோப்பு: குறிப்பு:` செட்டப்டூல்ச்` இது பைத்தானில் எழுதப்படுகிறது, " +"எடுத்துக்காட்டாக *டாம்ல் *க்கு பதிலாக (இதேபோன்ற நடைமுறை *Nox *போன்ற பிற கருவிகளால் " +"பயன்படுத்தப்படுகிறது மற்றும் அதன்: கோப்பு: `noxfile.py` உள்ளமைவு கோப்பு, அல்லது * " +"பைட்டெச்ட் * மற்றும்: கோப்பு:` conftest.py`)." + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" +"இருப்பினும், `` பைதான் setup.py`` மற்றும் பயன்பாடு: கோப்பு: `setup.py` ஒரு கட்டளை " +"வரி கருவியாக நீக்கப்படும்." + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "இதன் பொருள் பின்வரும் ** போன்ற கட்டளைகள் ** இனி இயக்கப்படக்கூடாது:" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python setup.py install``" +msgstr "`` பைதான் 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 "`` பைதான் setup.py உருவாக்கு``" + +#: ../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 "`` பைதான் 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 "`` பைதான் 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 "`` பைதான் -எம் பிஐபி நிறுவல் .``" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python -m pip install --editable .``" +msgstr "`` பைதான் -எம் பிஐபி நிறுவல் -அடைக்கக்கூடியது .``" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "`` பைதான் -எம் பில்ட்`` [#தேவைகள் -கட்டுதல்] _" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" +"இதற்கு: ref: `உருவாக்கு` சார்பு தேவை. ஒரு திட்டத்தின் மூல வழங்கல் மற்றும் சக்கரம் " +"இரண்டையும் எப்போதும் உருவாக்கி வெளியிட பரிந்துரைக்கப்படுகிறது, இதுதான் `` பைதான் -எம் " +"பில்ட்`` செய்கிறது. தேவைப்பட்டால் ``--ச்டிச்ட்`` மற்றும் ``-வீல்`` விருப்பங்கள் ஒன்று அல்லது " +"மற்றொன்றை மட்டுமே உருவாக்க பயன்படுத்தப்படலாம்." + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" +"செட்ப்டூல்ச் அடிப்படையிலான திட்டத்தை நிறுவுவதற்கு, இயங்குவது பொதுவானது: கோப்பு: " +"`setup.py` இன்` `நிறுவு` கட்டளை போன்றவை:` `பைதான் அமைவு. இப்போதெல்லாம், " +"பரிந்துரைக்கப்பட்ட முறை பயன்படுத்த வேண்டும்: குறிப்பு: `பிஐபி` இது போன்ற ஒரு கட்டளையுடன் " +"நேரடியாக:` `பைதான் -எம் பிஐபி நிறுவல் .``. புள்ளி `` .`` உண்மையில் ஒரு கோப்பு " +"முறைமை பாதை, இது தற்போதைய கோப்பகத்திற்கான பாதை குறியீடாகும். உண்மையில், * பிப் * உள்ளக " +"கோப்பு முறைமையில் ஒரு திட்டத்தின் மூல மர கோப்பகத்திற்கான பாதையை அதன் `` நிறுவல்` துணை " +"கட்டளைக்கு வாதமாக ஏற்றுக்கொள்கிறது. எனவே இது செல்லுபடியாகும் கட்டளையாகவும் இருக்கும்: " +"`` பைதான் -எம் பிஐபி நிறுவல் பாதை/முதல்/திட்டம்``." + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "* `` பைதான் அமைவு. -M PIP நிறுவல் --diable .``." + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" +"ஒரு பரிந்துரைக்கப்பட்ட, எளிமையான மற்றும் நேரடியான கட்டிடம்: கால: `மூல வழங்கல் <மூல " +"வழங்கல் (அல்லது\" SDIST \")>` மற்றும்: கால: `சக்கரங்கள் ` பயன்படுத்த வேண்டும்: " +"ref: `உருவாக்கு` கருவி a `` பைதான் -எம் பில்ட்` போன்ற கட்டளை இரண்டு விநியோக " +"வடிவங்களின் தலைமுறையையும் தூண்டுகிறது. தேவைப்பட்டால் ``--ச்டிச்ட்`` மற்றும் ``-வீல்`` " +"விருப்பங்கள் ஒன்று அல்லது மற்றொன்றை மட்டுமே உருவாக்க பயன்படுத்தப்படலாம். உருவாக்க கருவி " +"தனித்தனியாக நிறுவப்பட வேண்டும் என்பதை நினைவில் கொள்க." + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "`` பைதான் அமைவு." + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "மற்ற கட்டளைகளைப் பற்றி என்ன?" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "மற்ற `` பைதான் அமைவு.பை`` கட்டளைகளுக்கு சில மாற்றீடுகள் யாவை?" + +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "`` பைதான் setup.py test``" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "Pytest_ போன்ற சோதனை ரன்னரைப் பயன்படுத்த வேண்டும் என்று பரிந்துரை." + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "`` பைதான் அமைவு." + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "நம்பகமான மாற்றீடு: ref: `ட்வைன்`:" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "`` பைதான் -எம் கயிறு காசோலை - -ச்ட்ரிக்ட் டிச்ட்/*``" + +#: ../source/discussions/setup-py-deprecated.rst:104 +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "`` பைதான் -எம் ட்வைன் பதிவு Dist/*." + +#: ../source/discussions/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "`` பைதான் -எம் கயிறு பதிவேற்றியது dist/*``" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" +"தேவையில்லை, அல்லது ஆதரிக்கப்படவில்லை: கால: `பைபி <பைதான் தொகுப்பு அட்டவணை (பைபி)>`. " +"ஆனால் மற்றவற்றில் அவசியமாக இருக்கலாம்: கால: `தொகுப்பு குறியீடுகள் <தொகுப்பு குறியீட்டு>` " +"(எடுத்துக்காட்டாக: குறிப்பு: `தேவ்பி`)." + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "`` பைதான் setup.py --version``" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "சாத்தியமான மாற்று தீர்வு (மற்றவற்றுடன்) Setuptools-SCM_ ஐ நம்புவதாகும்:" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "`` பைதான் -எம் செட்டப்டூல்ச்_எச்சிஎம்``" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "மீதமுள்ள கட்டளைகள்" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "இந்த வழிகாட்டி அந்த கட்டளைகளுக்கு மாற்று தீர்வுகளின் பரிந்துரைகளை வழங்காது:" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "`` மாற்றுப்பெயர்``" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "`` bdist``" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "`` bdist_dumb``" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "`` bdist_egg``" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "`` bdist_rpm``" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "`` பில்ட்``" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "`Build_clib``" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "`` build_ext``" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "`` build_py``" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "`` build_scripts``" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "`` சுத்தம்`" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "`` dist_info``" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "`` ஈசி_இன்ச்டால்``" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "`` எடிபிள்_வீல்``" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "`` முட்டை_இன்ஃபோ``" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "`` install_data``" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "`` install_egg_info``" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "`` install_headers``" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "`` install_lib``" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "`` install_scripts``" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "`` சுழற்றுங்கள்``" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "`` சேமிஆப்ச்``" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "`` Setoptt \"`" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "`` பதிவேற்றம்_டாக்ச்``" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "தனிப்பயன் கட்டளைகள் பற்றி என்ன?" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" +"அதேபோல், தனிப்பயன்: கோப்பு: `setup.py` கட்டளைகள் நீக்கப்படுகின்றன. அந்த தனிப்பயன் " +"கட்டளைகளை ஒரு பணி ரன்னர் கருவி அல்லது வேறு எந்த இதே போன்ற கருவிக்கு மாற்றுவதே " +"பரிந்துரை. அத்தகைய கருவிகளின் சில எடுத்துக்காட்டுகள்: சூய், மேக், நோக்ச் அல்லது டாக்ச், " +"பைடோயிட், பைன்வோக், டாச்கிபி மற்றும் Thx." + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "தனிப்பயன் உருவாக்க படிகள் பற்றி என்ன?" + +#: ../source/discussions/setup-py-deprecated.rst:168 +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 "" +"தனிப்பயன் உருவாக்க படிகள் எடுத்துக்காட்டாக, `` `பில்ட்_பி``,` `பில்ட்_எக்ச்ட்``, மற்றும்` " +"`bdist_wheel`` போன்ற படிகளை மேலெழுதும் அல்லது புதிய உருவாக்க படிகளைச் சேர்க்காது. " +"அவை தானாகவே எதிர்பார்த்தபடி அழைக்கப்படும்." + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "`` Setup.py`` நீக்கப்பட வேண்டுமா?" + +#: ../source/discussions/setup-py-deprecated.rst:177 +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 "" +"இதன் பயன்பாடு: கோப்பு: `setup.py` ஒரு இயங்கக்கூடிய ச்கிரிப்டாக நீக்கப்பட்டாலும், " +"செட்டுப்டூல்களுக்கான உள்ளமைவு கோப்பாக அதன் பயன்பாடு முற்றிலும் நன்றாக உள்ளது. இதில் எந்த " +"மாற்றமும் தேவையில்லை: கோப்பு: `setup.py`." + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "`` Pyproject.toml`` கட்டாயமா?" + +#: ../source/discussions/setup-py-deprecated.rst:185 +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 "" +"இது தொழில்நுட்ப ரீதியாக இன்னும் அவசியமில்லை என்றாலும், ஒரு திட்டத்தை ஒரு திட்டத்தை " +"வைத்திருப்பது ** ** ** ** ஒரு: கோப்பு: `pyproject.toml` கோப்பு அதன் மூல மரத்தின் " +"மூலத்தில் இது போன்ற உள்ளடக்கத்துடன்:" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" +"வழிகாட்டி: ref: `நவீனமயமாக்கல்-செட்டப்-ப்-திட்டத்தை 'இது குறித்த கூடுதல் விவரங்கள் உள்ளன." + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" +"ஒரு: காலத்திற்கான நிலையான குறைவடையும் நடத்தை: `பில்ட் ஃபிரான்டென்ட் <பில்ட் " +"ஃபிரான்டெண்ட்>` ஒரு: கோப்பு: `pyproject.toml` கோப்பு மற்றும் அதன்` `[பில்ட்-சிச்டம்]` " +"`அட்டவணை என்று கருதுவது: காலமானது : `பின்தளத்தில் உருவாக்கு <பின்தளத்தில் உருவாக்கு>` " +"என்பது setuptools." + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "ஏன்? இது என்ன அர்த்தம்?" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" +"அதைப் பார்ப்பதற்கான ஒரு வழி என்னவென்றால், செடுப்டூல்களின் நோக்கம் இப்போது ஒரு கட்டமைப்பை " +"பின்தளத்தில் குறைத்துள்ளது." + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "இதைப் பற்றி மேலும் படிக்க எங்கே?" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" +"`நீங்கள் ஏன் setup.py ஐ நேரடியாக அழைக்கக்கூடாது ` __ பால் கன்ச்லே" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr ": டாக்: `செட்ப்டூல்ச்: நீக்கப்பட்ட/கட்டளைகள்`" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "திட்ட பதிப்பில் ஒற்றை-மூல" + +#: ../source/discussions/single-source-version.rst:7 +msgid "Complete" +msgstr "முழுமையானது" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "2024-10-07" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" +"பல பைதான்: கால: `விநியோக தொகுப்புகள் <விநியோக தொகுப்பு>` ஒரு பைதானை வெளியிடுங்கள்: " +"கால: `இறக்குமதி தொகுப்பு <இறக்குமதி தொகுப்பு>` அங்கு இயக்க நேரம் `__ வழிமுறை__`` " +"இறக்குமதி தொகுப்பில் பண்புக்கூறு அதே பதிப்பு விவரக்குறிப்பை அறிக்கையிட வேண்டும் AS: " +"func: `importlib.metadata.version` விநியோக தொகுப்புக்கான அறிக்கைகள் " +"(விவரிக்கப்பட்டுள்ளபடி: குறிப்பு:` இயக்க நேர-பதிப்பு-அணுகல்`)." + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" +"மூலக் குறியீட்டில் கைமுறையாக புதுப்பிக்கப்படுவதை விட இந்த பதிப்பு செய்தி பதிப்பு " +"கட்டுப்பாட்டு அமைப்பு * குறிச்சொல் * (`` v1.2.3`` போன்றவை) இலிருந்து பெறப்பட வேண்டும் " +"என்பதும் அடிக்கடி விரும்பப்படுகிறது." + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" +"சில திட்டங்கள் தரவு நுழைவு நகலுடன் வாழ தேர்வு செய்யலாம், மேலும் வெவ்வேறு மதிப்புகள் " +"வேறுபடுவதில்லை என்பதை உறுதிப்படுத்த தானியங்கு சோதனையை நம்பியிருக்கலாம்." + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" +"மாற்றாக, ஒரு திட்டத்தின் தேர்ந்தெடுக்கப்பட்ட உருவாக்க அமைப்பு பதிப்பு எண்ணுக்கு உண்மையின் " +"ஒரு மூலத்தை வரையறுக்க ஒரு வழியை வழங்கக்கூடும்." + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "பொதுவாக, விருப்பங்கள்:" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" +"குறியீடு ஒரு பதிப்பு கட்டுப்பாட்டு அமைப்பில் (VCS), அதாவது git போன்றவை என்றால், பதிப்பை " +"பகஅ இலிருந்து பிரித்தெடுக்க முடியும்." + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" +"பதிப்பை: கோப்பு: `pyproject.toml` கோப்பில் கடினமாக குறியிடப்படலாம்-மேலும் கட்டட " +"அமைப்பு அதை தேவைப்படக்கூடிய பிற இடங்களுக்கு நகலெடுக்க முடியும்." + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" +"பதிப்பு சரம் மூலக் குறியீட்டில் கடினமாக குறியிடப்படலாம்-ஒரு சிறப்பு நோக்கக் கோப்பில், " +"போன்றவை: கோப்பு: `_version.txt` (பின்னர் திட்டத்தின் மூல விநியோக தொகுப்பின் ஒரு " +"பகுதியாக அனுப்பப்பட வேண்டும்), அல்லது ஒரு ஒரு குறிப்பிட்ட தொகுதியில் பண்புக்கூறு, " +"போன்றவை: கோப்பு: `__init __. py`. பில்ட் சிச்டம் பின்னர் அதை உருவாக்கும் நேரத்தில் இயக்க " +"நேர இடத்திலிருந்து பிரித்தெடுக்க முடியும்." + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "அவற்றின் பரிந்துரைக்கப்பட்ட முறைக்கு உங்கள் உருவாக்க அமைப்பின் ஆவணங்களை அணுகவும்." + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" +"ஒரு விநியோக தொகுப்பும் அதனுடன் தொடர்புடைய இறக்குமதி தொகுப்பும் ஒரே பதிப்பைப் பகிர்ந்து " +"கொள்ள வேண்டும் என்ற நோக்கம் இருக்கும்போது, திட்டத்தில் ஒரு தானியங்கி சோதனை வழக்கு அடங்கும், " +"இது `` இறக்குமதி_பெயர் .__ பதிப்பு __`` மற்றும் `` இறக்குமதி லிப். பெயர் \")` `அதே " +"மதிப்பைப் புகாரளிக்கவும் (குறிப்பு: பல திட்டங்களுக்கு,` `இறக்குமதி_நாம்`` மற்றும்` `டிச்ட்-" +"பெயர்`` ஒரே பெயராக இருக்கும்)." + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "கணினி பதிப்பு கையாளுதலை உருவாக்குங்கள்" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" +"பதிப்பு சரங்களைக் கையாள்வதற்கான சில உருவாக்க அமைப்பின் ஆவணங்களுக்கான இணைப்புகள் " +"பின்வருமாறு." + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "`ஃபிளிட் ` _" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "`அட்ச்லிங் ` _" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" +"`Pdm ` _" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" +"`Setuptools ` _" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "`setuptools_scm ` _" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "எச்.ஆர்.சி தளவமைப்பு vs பிளாட் தளவமைப்பு" + +#: ../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 "" +"\"பிளாட் தளவமைப்பு\" என்பது ஒரு திட்டத்தின் கோப்புகளை ஒரு கோப்புறை அல்லது களஞ்சியத்தில் " +"ஒழுங்கமைப்பதைக் குறிக்கிறது, அதாவது பல்வேறு உள்ளமைவு கோப்புகள் மற்றும்: கால: `இறக்குமதி " +"தொகுப்புகள் <இறக்குமதி தொகுப்பு>` அனைத்தும் உயர்மட்ட கோப்பகத்தில் உள்ளன." + +#: ../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/`` என்று பெயரிடப்பட்டுள்ளது, எனவே \"SRC " +"தளவமைப்பு\"." + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" +"எச்.ஆர்.சி தளவமைப்பு மற்றும் தட்டையான தளவமைப்புக்கு இடையிலான முக்கியமான நடத்தை " +"வேறுபாடுகளின் முறிவு இங்கே:" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" +"எச்.ஆர்.சி தளவமைப்புக்கு அதன் குறியீட்டை இயக்க திட்டத்தை நிறுவ வேண்டும், மேலும் தட்டையான " +"தளவமைப்பு இல்லை." + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" +"இதன் பொருள் எச்.ஆர்.சி தளவமைப்பு ஒரு திட்டத்தின் மேம்பாட்டு பணிப்பாய்வுகளில் கூடுதல் படியை " +"உள்ளடக்கியது (பொதுவாக, ஒரு: டிஓசி: `திருத்தக்கூடிய நிறுவல் <செட்டப்டூல்ச்: யூசர்சூட்/" +"டெவலப்மென்ட்_மோட்>` வளர்ச்சிக்கு பயன்படுத்தப்படுகிறது மற்றும் சோதனைக்கு வழக்கமான நிறுவல் " +"பயன்படுத்தப்படுகிறது)." + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" +"எச்.ஆர்.சி தளவமைப்பு குறியீட்டின் மேம்பாட்டு நகலின் தற்செயலான பயன்பாட்டைத் தடுக்க " +"உதவுகிறது." + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" +"பைதான் மொழிபெயர்ப்பாளர் இறக்குமதி பாதையில் முதல் உருப்படியாக தற்போதைய பணி கோப்பகத்தை " +"உள்ளடக்கியிருப்பதால் இது பொருத்தமானது. இதன் பொருள், நிறுவப்பட்ட இறக்குமதி தொகுப்பின் அதே " +"பெயருடன் தற்போதைய பணி கோப்பகத்தில் இறக்குமதி தொகுப்பு இருந்தால், தற்போதைய பணி " +"கோப்பகத்திலிருந்து மாறுபாடு பயன்படுத்தப்படும். இது திட்டத்தின் பேக்கேசிங் கருவியின் " +"நுட்பமான தவறான கட்டமைப்பிற்கு வழிவகுக்கும், இதன் விளைவாக கோப்புகள் விநியோகத்தில் " +"சேர்க்கப்படாது." + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" +"எச்.ஆர்.சி தளவமைப்பு இதைத் தவிர்க்க உதவுகிறது, இறக்குமதி தொகுப்புகளை திட்டத்தின் ரூட் " +"கோப்பகத்திலிருந்து பிரித்து, நிறுவப்பட்ட நகல் பயன்படுத்தப்படுவதை உறுதிசெய்கிறது." + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" +"எச்.ஆர்.சி தளவமைப்பு ஒரு: டாக்: `திருத்தக்கூடிய நிறுவல் <செட்டப்டூல்ச்: யூசர்சூட்/" +"டெவலப்மென்ட்_மோட்>` இறக்குமதி செய்யக்கூடிய கோப்புகளை மட்டுமே இறக்குமதி செய்ய முடியும் " +"என்பதை செயல்படுத்த உதவுகிறது." + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" +"`பாதை உள்ளமைவு கோப்பைப் பயன்படுத்தி திருத்தக்கூடிய நிறுவல் செயல்படுத்தப்படும்போது இது " +"மிகவும் பொருத்தமானது _ _ " +"இது கோப்பகத்தை இறக்குமதி பாதையில் சேர்க்கிறது." + +#: ../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 "" +"தட்டையான தளவமைப்பு மற்ற திட்டக் கோப்புகளைச் சேர்க்கும் (எ.கா. ``) இறக்குமதி பாதையில். " +"இது சில இறக்குமதிகள் திருத்தக்கூடிய நிறுவல்களில் செயல்பட வைக்கும், ஆனால் வழக்கமான " +"நிறுவல்கள் அல்ல." + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "எச்.ஆர்.சி-லேஅவுட்டுடன் மூலத்திலிருந்து கட்டளை-வரி இடைமுகத்தை இயக்குகிறது" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" +"எச்.ஆர்.சி தளவமைப்பின் முதன்முதலில் குறிப்பிடப்பட்ட சிறப்பு காரணமாக, ஒரு கட்டளை-வரி " +"இடைமுகத்தை நேரடியாக இயக்க முடியாது: கால: `மூல மரம் <திட்ட மூல மரம்>`, ஆனால் " +"தொகுப்பை நிறுவ வேண்டும்: டாக்: `மேம்பாட்டு முறை < setuptools: USERGUIDE/" +"Development_mode> `சோதனை நோக்கங்களுக்காக. சில சூழ்நிலைகளில் இது நடைமுறைக்கு " +"மாறானதாக இருப்பதால், தொகுப்பு கோப்புறையை பைத்தானுக்கு தயார்படுத்துவது ஒரு " +"பணித்தொகுப்பு: py: data: `sys.path` அதன் வழியாக அழைக்கப்படும்போது: கோப்பு:` __main " +"__. பை` கோப்பு:" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +msgid "Versioning" +msgstr "பதிப்பு" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "இந்த விவாதம் பைதான் தொகுப்புகளை பதிப்பதன் அனைத்து அம்சங்களையும் உள்ளடக்கியது." + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "செல்லுபடியாகும் பதிப்பு எண்கள்" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" +"வெவ்வேறு பைதான் திட்டங்கள் அந்த குறிப்பிட்ட திட்டத்தின் தேவைகளின் அடிப்படையில் வெவ்வேறு " +"பதிப்பு திட்டங்களைப் பயன்படுத்தலாம், ஆனால் போன்ற கருவிகளுடன் இணக்கமாக இருக்க, ref: " +"`பிப்`, அவை அனைத்தும் பதிப்பு அடையாளங்காட்டிகளுக்கு நெகிழ்வான வடிவத்துடன் இணங்க வேண்டும், " +"அதற்காக அதிகாரப்பூர்வ குறிப்பு: ref: `பதிப்பு விவரக்குறிப்புகளின் விவரக்குறிப்பு " +"<பதிப்பு-விவரக்குறிப்புகள்>`. பதிப்பு எண்களின் சில எடுத்துக்காட்டுகள் இங்கே [#பதிப்பு-" +"எடுத்துக்காட்டுகள்] _:" + +#: ../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``" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "ஆல்பா வெளியீடு: `` 1.2.0a1``" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "ஒரு பீட்டா வெளியீடு: `` 1.2.0b1``" + +#: ../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 "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +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``" + +#: ../source/discussions/versioning.rst:30 +#, fuzzy +#| msgid "A version with an epoch: ``1!1.0``" +msgid "A version with an epoch (discouraged): ``1!1.0``" +msgstr "ஒரு சகாப்தத்துடன் ஒரு பதிப்பு: `` 1! 1.0``" + +#: ../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 "" +"இறுதி வெளியீட்டிற்கு முன்னர் தங்கள் பயனர்களால் சோதனையை ஆதரிக்க திட்டங்கள் முன் வெளியீட்டு " +"சுழற்சியைப் பயன்படுத்தலாம். வரிசையில், படிகள்: ஆல்பா வெளியீடுகள், பீட்டா வெளியீடுகள், " +"வெளியீட்டு வேட்பாளர்கள், இறுதி வெளியீடு. பிஐபி மற்றும் பிற நவீன பைதான் தொகுப்பு " +"நிறுவிகள் வெளிப்படையாகக் கோரப்படாவிட்டால் (எ.கா., பி.கே.சி நிறுவும் பி.கே. `)." + +#: ../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 "" +"வளர்ச்சி வெளியீடுகளின் நோக்கம் ஒரு வளர்ச்சி சுழற்சியின் போது ஆரம்பத்தில் செய்யப்பட்ட " +"வெளியீடுகளை ஆதரிப்பதாகும், எடுத்துக்காட்டாக, ஒரு இரவு கட்டமைப்பை அல்லது லினக்ச் " +"விநியோகத்தில் அண்மைக் கால மூலத்திலிருந்து ஒரு கட்டமைப்பை உருவாக்குவது." + +#: ../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/versioning.rst:49 +#, fuzzy +#| 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." +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" +"இறுதியாக, பதிப்புத் திட்டத்தை மாற்றும்போது வரிசையாக்க வரிசையை சரிசெய்ய, அரிதாகப் " +"பயன்படுத்தப்படும் அம்சமான சகாப்தங்கள். எடுத்துக்காட்டாக, ஒரு திட்டம் 23.12 போன்ற " +"பதிப்புகளுடன் காலெண்டர் பதிப்பைப் பயன்படுத்தினால், மற்றும் சொற்பொருள் பதிப்பிற்கு மாறினால், " +"1.0 போன்ற பதிப்புகளுடன், 1.0 மற்றும் 23.12 க்கு இடையிலான ஒப்பீடு தவறான வழியில் " +"செல்லும். இதை சரிசெய்ய, பழைய பதிப்பு எண்களை விட மிக சமீபத்தியதாக கருதப்படுவதற்கு, " +"\"1! 1.0\" இல் உள்ளதைப் போல புதிய பதிப்பு எண்கள் வெளிப்படையான சகாப்தத்தைக் கொண்டிருக்க " +"வேண்டும்." + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "சொற்பொருள் பதிப்பு எதிராக காலண்டர் பதிப்பு" + +#: ../source/discussions/versioning.rst:62 +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 "" +"பதிப்பு எண்ணின் பிரிவுகளை விளக்குவதற்கும், ஒரு தொகுப்பின் புதிய வெளியீட்டிற்கான அடுத்த " +"பதிப்பு எண்ணாக இருக்க வேண்டும் என்பதை தீர்மானிப்பதற்கும் ஒரு பதிப்பு திட்டம் ஒரு முறையான " +"வழியாகும். பைதான் தொகுப்புகள், சொற்பொருள் பதிப்பு மற்றும் காலண்டர் பதிப்பிற்கு இரண்டு " +"பதிப்பு திட்டங்கள் பொதுவாகப் பயன்படுத்தப்படுகின்றன." + +#: ../source/discussions/versioning.rst:69 +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:75 +#, fuzzy +#| 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." +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" +"அடுத்த பதிப்பு எண்ணைத் தேர்ந்தெடுப்பதற்கு அறியப்பட்ட விதிவிலக்குகள் உள்ளன. கடைசி பதிப்பு " +"பிரிவில் பின்னோக்கி-இணக்கமான மாற்றங்கள் மட்டுமே உள்ளன என்ற அனுமானத்தை உடைக்க " +"பராமரிப்பாளர்கள் உணர்வுபூர்வமாக தேர்வு செய்யலாம். பாதுகாப்பு பாதிப்பு தீர்க்கப்பட வேண்டிய " +"ஒரு வழக்கு. பாதுகாப்பு வெளியீடுகள் பெரும்பாலும் ஒட்டு பதிப்புகளில் வருகின்றன, ஆனால் " +"தவிர்க்க முடியாமல் மாற்றங்களை உடைக்கும்." + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "சொற்பொருள் பதிப்பு" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" +"*சொற்பொருள் பதிப்பு *(அல்லது செம்வர்) இன் சிந்தனை 3-பகுதி பதிப்பு எண்களைப் " +"பயன்படுத்துவதாகும், *mater.minor.patch *, அங்கு திட்ட ஆசிரியர் அதிகரிக்கும்:" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "* மேசர்* அவர்கள் பொருந்தாத பநிஇ மாற்றங்களைச் செய்யும்போது," + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "* சிறிய* அவை பின்னோக்கி-இணக்கமான முறையில் செயல்பாட்டைச் சேர்க்கும்போது, மற்றும்" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "*பேட்ச்*, அவை பின்னோக்கி-இணக்கமான பிழை திருத்தங்களைச் செய்யும்போது." + +#: ../source/discussions/versioning.rst:94 +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 "" +"பைதான் திட்டங்களில் பெரும்பாலானவை சொற்பொருள் பதிப்பை ஒத்த ஒரு திட்டத்தைப் " +"பயன்படுத்துகின்றன. இருப்பினும், பெரும்பாலான திட்டங்கள், குறிப்பாக பெரியவை, சொற்பொருள் " +"பதிப்பைக் கண்டிப்பாக கடைப்பிடிக்காது, ஏனெனில் பல மாற்றங்கள் தொழில்நுட்ப ரீதியாக மாற்றங்களை " +"உடைக்கின்றன, ஆனால் பயனர்களில் ஒரு சிறிய பகுதியை மட்டுமே பாதிக்கின்றன. பொருந்தாத தன்மை " +"அதிகமாக இருக்கும்போது இத்தகைய திட்டங்கள் முக்கிய எண்ணிக்கையை அதிகரிக்க முனைகின்றன, " +"அல்லது எந்தவொரு சிறிய பொருந்தாத தன்மையைக் காட்டிலும் [#செம்வர்-ச்ட்ரிக்டெச்] _. மாறாக, " +"முக்கிய பதிப்பு எண்ணின் ஒரு பம்ப் சில நேரங்களில் குறிப்பிடத்தக்க ஆனால் பின்னோக்கி-இணக்கமான " +"புதிய அம்சங்களை சமிக்ஞை செய்யப் பயன்படுகிறது." + +#: ../source/discussions/versioning.rst:104 +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: `இணக்கமான வெளியீட்டு பதிப்பு விவரக்குறிப்புகள் <பதிப்பு-" +"விவரக்குறிப்புகள்-இணக்கமான-வெளியீட்டு>`, `~ ~ =` `ஆபரேட்டருடன். எடுத்துக்காட்டாக, `` " +"பெயர் ~ = X.Y`` தோராயமாக `` பெயர்> = x.y, == x.*``, அதாவது, இதற்கு குறைந்தபட்சம் " +"வெளியீடு X.y க்கு தேவைப்படுகிறது, மேலும் எந்தவொரு பின்னர் வெளியீட்டை அதிக ஒய் உடன் " +"அனுமதிக்கிறது ஃச் ஒன்றே. அதேபோல், `` பெயர் ~ = x.y.z`` தோராயமாக `` பெயர்> = x.y.z, " +"== x.y.*``, அதாவது, அதற்கு குறைந்தபட்சம் x.y.z தேவைப்படுகிறது மற்றும் அதே ஃச் மற்றும் " +"ஒய் உடன் பின்னர் வெளியீட்டை அனுமதிக்கிறது." + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" +"சொற்பொருள் பதிப்பைப் பின்பற்றும் பைதான் திட்டங்கள் `சொற்பொருள் பதிப்பு 2.0.0 விவரக்குறிப்பு " +"<செம்வர்_>` _ `_ ஆகியவற்றின் 1-8 உட்பிரிவுகளுக்கு கட்டுப்பட வேண்டும்." + +#: ../source/discussions/versioning.rst:116 +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 "" +"பிரபலமான: டிஓசி: `ச்பின்க்ச் <ச்பின்க்ச்: இன்டெக்ச்>` ஆவணப்படுத்தல் செனரேட்டர் என்பது " +"கடுமையான சொற்பொருள் பதிப்பைப் பயன்படுத்தும் ஒரு எடுத்துக்காட்டு திட்டமாகும் (: டாக்: " +"`ச்பிங்க்ச் பதிப்பு கொள்கை <ச்பிங்க்ச்: இன்டர்ன்ச்/வெளியீட்டு-செயல்முறை>`). புகழ்பெற்ற: டிஓசி: " +"`நம்பி <நம்பி: இன்டெக்ச்>` அறிவியல் கணினி தொகுப்பு வெளிப்படையாக \"தளர்வான\" சொற்பொருள் " +"பதிப்பைப் பயன்படுத்துகிறது, அங்கு சிறிய பதிப்பை அதிகரிக்கும் வெளியீடுகள் பின்னோக்கி-" +"இணக்கமான பநிஇ மாற்றங்களைக் கொண்டிருக்கலாம் (: டாக்: `நம்பி பதிப்பு கொள்கை <நம்பி: தேவ்/ " +"_ON_NUMPY> `)." + +#: ../source/discussions/versioning.rst:125 +msgid "Calendar versioning" +msgstr "காலண்டர் பதிப்பு" + +#: ../source/discussions/versioning.rst:127 +#, fuzzy +#| 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." +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" +"ஒரு அம்சத்தை அகற்றுவதற்கு முன்னர் பல வெளியீடுகளுக்கு எச்சரிக்கைகளை வழங்கும் வழக்கமான நேர " +"அடிப்படையிலான வெளியீட்டு கேடென்ச் மற்றும் ஒரு மதிப்பிழப்பு செயல்முறை போன்ற அனைத்து " +"திட்டங்களுக்கும் சொற்பொருள் பதிப்பு பொருத்தமான தேர்வாக இல்லை." + +#: ../source/discussions/versioning.rst:131 +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 "" +"தேதி அடிப்படையிலான பதிப்பின் முக்கிய நன்மை, அல்லது `காலண்டர் பதிப்பு <கால்வர்_>` _ " +"(கால்வர்), ஒரு குறிப்பிட்ட வெளியீட்டின் அடிப்படை அம்சத் தொகுப்பிற்கு பதிப்பு எண்ணை எவ்வளவு " +"பழையதாகக் கூறுவது நேரடியானது." + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" +"காலண்டர் பதிப்பு எண்கள் பொதுவாக * year.month * படிவத்தை எடுக்கும் (எடுத்துக்காட்டாக, " +"டிசம்பர் 2023 க்கு 23.12)." + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" +": டாக்: `பிப் <பிப்: இன்டெக்ச்>`, நிலையான பைதான் தொகுப்பு நிறுவி, காலண்டர் பதிப்பைப் " +"பயன்படுத்துகிறது." + +#: ../source/discussions/versioning.rst:143 +msgid "Other schemes" +msgstr "பிற திட்டங்கள்" + +#: ../source/discussions/versioning.rst:145 +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 "" +"சீரியல் பதிப்பு என்பது எளிமையான சாத்தியமான பதிப்பு திட்டத்தைக் குறிக்கிறது, இது ஒவ்வொரு " +"வெளியீட்டையும் அதிகரிக்கும் ஒற்றை எண்ணைக் கொண்டுள்ளது. சீரியல் பதிப்பு ஒரு டெவலப்பராக " +"நிர்வகிக்க மிகவும் எளிதானது என்றாலும், இறுதி பயனராக கண்காணிப்பது கடினம், ஏனெனில் தொடர் " +"பதிப்பு எண்கள் பநிஇ பின்னோக்கி பொருந்தக்கூடிய தன்மை குறித்து சிறிய அல்லது எந்த தகவலையும் " +"தெரிவிக்கின்றன." + +#: ../source/discussions/versioning.rst:151 +#, fuzzy +#| 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." +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 "" +"மேற்கண்ட திட்டங்களின் சேர்க்கைகள் சாத்தியமாகும். எடுத்துக்காட்டாக, ஒரு திட்டம் ஒரு * ஆண்டை " +"உருவாக்க சீரியல் பதிப்போடு தேதி அடிப்படையிலான பதிப்போடு இணைக்கலாம். ஒரு வெளியீட்டின் " +"தோராயமான வயதை உடனடியாக வெளிப்படுத்தும், ஆனால் ஆண்டுக்குள் ஒரு குறிப்பிட்ட வெளியீட்டு " +"கேடென்சுக்கு உறுதியளிக்கவில்லை." + +#: ../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 "" +"பொது பதிப்பு அடையாளங்காட்டிகள் விநியோகத்தை ஆதரிக்க வடிவமைக்கப்பட்டுள்ளன: கால: `பைபி " +"<பைதான் தொகுப்பு குறியீட்டு (PYPI)>`. பைதான் பேக்கேசிங் கருவிகள் A: 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 "" +"உள்ளக பதிப்பு அடையாளங்காட்டி பொது பதிப்பு அடையாளங்காட்டியின் வடிவத்தை எடுக்கிறது, அதைத் " +"தொடர்ந்து \"+\" மற்றும் உள்ளக பதிப்பு சிட்டை. எடுத்துக்காட்டாக, ஃபெடோரா-குறிப்பிட்ட " +"திட்டுகள் பயன்படுத்தப்படும் ஒரு தொகுப்பில் \"1.2.1+ஃபெடோரா 4\" பதிப்பைக் கொண்டிருக்கலாம். " +"மற்றொரு எடுத்துக்காட்டு, செட்ப்டூல்ச்-எச்.சி.எம்_ ஆல் கணக்கிடப்பட்ட பதிப்புகள், செடுப்டூல்ச் " +"சொருகி, இது அறிவிலி தரவிலிருந்து பதிப்பைப் படிக்கிறது. அண்மைக் கால வெளியீட்டிலிருந்து " +"சில கமிட்டுகளுடன் கூடிய ஒரு சிஐடி களஞ்சியத்தில், செடுப்டூல்ச்-எச்.சி.எம் " +"\"0.5.DEV1+GD00980F\" போன்ற ஒரு பதிப்பை உருவாக்குகிறது, அல்லது களஞ்சியத்தில் " +"\"0.5.DEV1+GD00980F.D2021217\" போன்ற மாற்றங்கள் கட்டுப்படுத்தப்படாத மாற்றங்களைக் " +"கொண்டிருந்தால்." + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "இயக்க நேரத்தில் பதிப்பு தகவல்களை அணுகும்" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" +"அனைவருக்கும் பதிப்பு தகவல்: கால: `விநியோக தொகுப்புகள் <விநியோக தொகுப்பு>` தற்போதைய " +"சூழலில் உள்ளூரில் கிடைக்கக்கூடியவை நிலையான நூலகத்தைப் பயன்படுத்தி இயக்க நேரத்தில் " +"பெறலாம்: FUNC: `importlib.metadata.version` செயல்பாடு ::" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" +"பல திட்டங்கள் அவற்றின் உயர் மட்டத்தை பதிப்பதற்கும் தேர்வு செய்கின்றன: கால: `இறக்குமதி " +"தொகுப்புகளை <இறக்குமதி தொகுப்பு>` ஒரு தொகுப்பு நிலையை வழங்குவதன் மூலம் " +"`__version__`` பண்புக்கூறு ::" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" +"சி.எல்.ஐ பயன்பாடுகளுக்கு இந்த நுட்பம் குறிப்பாக மதிப்புமிக்கதாக இருக்கும், இது பதிப்பு " +"வினவல் அழைப்பிதழ்கள் (`` பிப் -வி`` போன்றவை) முடிந்தவரை விரைவாக இயங்குவதை உறுதிசெய்ய " +"விரும்புகின்றன." + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" +"தங்கள் அறிக்கையிடப்பட்ட விநியோக தொகுப்பு மற்றும் இறக்குமதி தொகுப்பு பதிப்புகள் " +"ஒருவருக்கொருவர் ஒத்துப்போகின்றன என்பதை உறுதிப்படுத்த விரும்பும் தொகுப்பு வெளியீட்டாளர்கள் " +"மறுபரிசீலனை செய்யலாம்: Ref: `ஒற்றை-மூல-பதிப்பு` அவ்வாறு செய்வதற்கான சாத்தியமான " +"அணுகுமுறைகளுக்கு விவாதம்." + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" +"இயக்க நேர பதிப்பு தகவல்களை இந்த வழியில் வெளியிட இறக்குமதி தொகுப்புகள் மற்றும் தொகுதிகள் " +"* தேவையில்லை * (திரும்பப் பெறப்பட்ட திட்டத்தைப் பார்க்கவும்: PEP: `PEP 396 <396>`) அவை " +"வழங்குவதாக அறியப்படுகிறது (அதன் சொந்த பதிப்பை வினவுவது அல்லது அதன் நேரடி சார்புகளில் " +"ஒன்றின் பதிப்பு போன்றவை), இல்லையெனில் வினவல் குறியீடு பண்புக்கூறு காணாமல் போன வழக்கைக் " +"கையாள வடிவமைக்கப்பட வேண்டும் [#குறைவுக்கு-தூரத்திற்கு -்வெர்சன்] _." + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" +"சில திட்டங்கள் தொகுதியின் பதிப்பாக இல்லாத வெளிப்புற பநிஇ களுக்கான பதிப்பு தகவல்களை " +"வெளியிட வேண்டியிருக்கலாம். இத்தகைய திட்டங்கள் இயக்க நேரத்தில் தொடர்புடைய தகவல்களைப் " +"பெறுவதற்கான தங்கள் சொந்த திட்ட-குறிப்பிட்ட வழிகளை வரையறுக்க வேண்டும். எடுத்துக்காட்டாக, " +"நிலையான நூலகத்தின்: MOD: `SSL` தொகுதி அடிப்படை OpenSSL நூலக பதிப்பை அணுக பல " +"வழிகளை வழங்குகிறது ::" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" +"அசாதாரண பதிப்பு எண்களின் இன்னும் சில எடுத்துக்காட்டுகள் `வலைப்பதிவு இடுகை <பதிப்புகள்-" +"செத்-லார்சன்_>` _ சேத் லார்சனால் கொடுக்கப்பட்டுள்ளன." + +#: ../source/discussions/versioning.rst:229 +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 "" +"இந்த இதழில் சில தனிப்பட்ட கண்ணோட்டங்களுக்கு, இந்த வலைப்பதிவு இடுகைகளைப் பார்க்கவும்: `ஐனெக் " +"ச்க்லவாக் <செம்வர்-ஐனெக்-ச்லாவாக்_>` _, `டொனால்ட் ச்டஃப் <செம்வர்-டொனால்ட்-ச்டஃப்ட்_>` _, " +"`பெர்னட் கோபர் <செம்வெர்-வெர்னட்- gabor_> `_,` பிரட் கேனன் `_. " +"நகைச்சுவையான எடுத்துக்கொள்ள, Zerover_ பற்றி படியுங்கள்." + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" +"அந்த இறக்குமதி தொகுப்புகள் மற்றும் தொகுதிகளை வழங்கும் விநியோக தொகுப்புகளுக்கு " +"இறக்குமதிக்கு கிடைக்கக்கூடிய உயர் மட்ட பெயர்களை மேப்பிங் செய்யும் முழு பட்டியல் நிலையான " +"நூலகத்தின் மூலம் பெறப்படலாம்: func: `importlib.metadata.packages_distributions` " +"செயல்பாடு. இதன் பொருள் என்னவென்றால், இறக்குமதி செய்யக்கூடிய அனைத்து உயர்மட்ட பெயர்களுக்கும் " +"புகாரளிக்க ஒரு பதிப்பை ஊகிக்க முயற்சிக்கும் குறியீடு கூட `__ பதிப்பு__`` பண்புக்கூறு " +"வரையறுக்கப்பட்டால், விநியோக பதிப்பு தகவல்களைப் புகாரளிக்கத் திரும்புவதற்கான வழிமுறைகள் " +"உள்ளன. நிலையான நூலக தொகுதிகள் மற்றும் பைதான் தொகுப்பு நிறுவலைத் தவிர வேறு வழிகளில் " +"சேர்க்கப்பட்ட தொகுதிகள் மட்டுமே அந்த விசயத்தில் பதிப்பு தகவல்களைப் பெறத் தவறும்." + +#: ../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 "" +"ஒரு: காலத்தை வெளியிட/விநியோகிப்பதில் ஈடுபடும் ஓட்டத்தை கோடிட்டுக் காட்டுவதை ஆவணம் " +"நோக்கமாகக் கொண்டுள்ளது: கால: `விநியோக தொகுப்பு <விநியோக தொகுப்பு>`, வழக்கமாக `பைதான் " +"தொகுப்பு குறியீட்டு (PYPI)` _ க்கு. தொகுப்பு வெளியீட்டாளர்களுக்காக இது எழுதப்பட்டுள்ளது, " +"அவர்கள் தொகுப்பு எழுத்தாளராக கருதப்படுகிறார்கள்." + +#: ../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 "" +"TOP: `டுடோரியல் <டுடோரியல்கள்/பேக்கேசிங்-திட்டங்கள்>` வெளியீட்டிற்கு ஒரு எளிய தொகுப்பைத் " +"தயாரிக்கும் செயல்முறையின் மூலம் நடந்து செல்லும்போது, என்ன படிகள் மற்றும் கோப்புகள் தேவை, " +"எந்த நோக்கத்திற்காக அது முழுமையாகக் கணக்கிடாது." + +#: ../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 "" +"ஒரு தொகுப்பை வெளியிடுவதற்கு ஆசிரியரின் மூலக் குறியீட்டிலிருந்து இறுதி பயனரின் பைதான் " +"சூழலுக்கு ஒரு ஓட்டம் தேவைப்படுகிறது. இதை அடைவதற்கான படிகள்:" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" +"தொகுப்பைக் கொண்ட ஒரு மூல மரத்தை வைத்திருங்கள். இது பொதுவாக பதிப்பு கட்டுப்பாட்டு " +"அமைப்பிலிருந்து (வி.சி.எச்) ஒரு புதுப்பிப்பு ஆகும்." + +#: ../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 "" +"தொகுப்பு மேனிலை தரவு (பெயர், பதிப்பு மற்றும் பல) மற்றும் உருவாக்க கலைப்பொருட்களை " +"எவ்வாறு உருவாக்குவது என்பதை விவரிக்கும் உள்ளமைவு கோப்பைத் தயாரிக்கவும். பெரும்பாலான " +"தொகுப்புகளுக்கு, இது ஒரு: கோப்பு: `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) அனுப்பப்பட வேண்டிய கட்டமைப்புகளை " +"உருவாக்குங்கள்; இவை பொதுவாக ஒரு: காலமாக இருக்கும்: `மூல வழங்கல் (\" SDIST \") <மூல " +"வழங்கல் (அல்லது\" SDIST \")>` மற்றும் ஒன்று அல்லது அதற்கு மேற்பட்டவை: சொல்: `கட்டப்பட்ட " +"விநியோகங்கள் (\" சக்கரங்கள் \") <கட்டப்பட்ட விநியோகம்>`. முந்தைய படியிலிருந்து உள்ளமைவு " +"கோப்பைப் பயன்படுத்தி ஒரு உருவாக்க கருவியால் இவை செய்யப்படுகின்றன. பெரும்பாலும் தூய " +"பைதான் தொகுப்புக்கு ஒரு பொதுவான சக்கரம் மட்டுமே உள்ளது." + +#: ../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 "" +"வழக்கமாக அதன் `` தள-பேக்கேச்கள்`` கோப்பகத்தில் அதை அவற்றின் பைதான் சூழலில் நிறுவவும். இந்த " +"படி ஒரு கட்டமைப்பை/தொகுக்கும் படி, தேவைப்பட்டால், தொகுப்பு மெட்டாடேட்டாவால் விவரிக்கப்பட " +"வேண்டும்." + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" +"இந்த கடைசி 2 படிகள் பொதுவாக நிகழ்த்தப்படுகின்றன: குறிப்பு: `பிப்` ஒரு இறுதி பயனர் " +"இயங்கும்போது` `பிஐபி நிறுவல்``." + +#: ../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 "" +"மூல மரத்தில் தொகுப்பு மூலக் குறியீடு உள்ளது, பொதுவாக ஒரு வி.சி.எச்சிலிருந்து ஒரு " +"புதுப்பிப்பு. உருவாக்க கலைப்பொருட்களை உருவாக்கப் பயன்படுத்தப்படும் குறியீட்டின் குறிப்பிட்ட " +"பதிப்பு பொதுவாக பதிப்போடு தொடர்புடைய குறிச்சொல்லின் அடிப்படையில் ஒரு புதுப்பித்தலாக " +"இருக்கும்." + +#: ../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 "" +"உள்ளமைவு கோப்பு உருவாக்க கலைப்பொருட்களை உருவாக்கப் பயன்படுத்தப்படும் கருவியைப் பொறுத்தது. " +"`டாம்ல் வடிவத்தில்`_ இல்` 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 "" +"குறைந்தபட்சம், தி: கோப்பு: `pyproject.toml` கோப்புக்கு` `[பில்ட்-சிச்டம்]` `உங்கள் " +"உருவாக்க கருவியைக் குறிப்பிடும் அட்டவணை தேவை. இதில் பல கட்டமைப்புக் கருவிகள் உள்ளன, " +"அவற்றில் மட்டுப்படுத்தப்படவில்லை: ref: `flit`,: ref:` அட்ச்`,: ref: `pdm`,: ref:` " +"கவிதை`,: ref: `setuptools`,` trampolim` _, மற்றும் `மோர்`_. ஒவ்வொரு கருவியின் " +"ஆவணங்களும் `` [பில்ட்-சிச்டம்] `` அட்டவணையில் எதை வைக்க வேண்டும் என்பதைக் காண்பிக்கும்." + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "எடுத்துக்காட்டாக, பயன்படுத்த ஒரு அட்டவணை இங்கே: ref: `அட்ச்`:" + +#: ../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 "" +"அத்தகைய அட்டவணையுடன்: கோப்பு: `pyproject.toml` கோப்பு, ஒரு\": கால: `ஃபிரான்டென்ட் " +"<பில்ட் ஃபிரான்டென்ட்>` \"கருவி போன்ற: ref:` பில்ட்` நீங்கள் தேர்ந்தெடுத்த பில்ட் கருவியை " +"இயக்க முடியும் \": கால:` பின்தளத்தில் < உருவாக்க கலைப்பொருட்களை உருவாக்க பின்தளத்தில்> " +"`\" உருவாக்குங்கள். உங்கள் உருவாக்க கருவி அதன் சொந்த முன்பக்கத்தையும் வழங்கக்கூடும். ஒரு " +"நிறுவும் கருவி: ref: `பிப்` ஒரு மூல விநியோகத்திலிருந்து நிறுவ உங்கள் உருவாக்க " +"கருவியின் பின்தளத்தில் இயக்கும்போது ஒரு முன்பக்கமாகவும் செயல்படுகிறது." + +#: ../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 "" +"நீங்கள் தேர்வுசெய்த குறிப்பிட்ட உருவாக்க கருவி: கோப்பு: `pyproject.toml` கோப்பில் என்ன " +"கூடுதல் செய்தி தேவை என்பதைக் குறிக்கிறது. எடுத்துக்காட்டாக, நீங்கள் குறிப்பிடலாம்:" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" +"ஒரு `` [திட்டம்] `` திட்டத்தைக் கொண்ட அட்டவணை: டாக்: `கோர் மேனிலை தரவு ` (பெயர், பதிப்பு, ஆசிரியர் மற்றும் பல)," + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "கருவி-குறிப்பிட்ட உள்ளமைவு விருப்பங்களைக் கொண்ட ஒரு `` [கருவி] `` அட்டவணை." + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" +"`` Pyproject.toml`` உள்ளமைவுக்கான முழுமையான வழிகாட்டிக்கு `pyproject.toml " +"வழிகாட்டி <எழுதுதல்-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 "" +"இறுதி பயனரின் பைதான் சூழலில் மூலத்திலிருந்து தொகுப்பை நிறுவ ஒரு மூல விநியோகத்தில் " +"போதுமானது. எனவே, இதற்கு தொகுப்பு சான்று தேவை, மேலும் சோதனைகள் மற்றும் ஆவணங்களும் " +"இருக்கலாம். உங்கள் ஆதாரங்களை உருவாக்க விரும்பும் இறுதி பயனர்களுக்கும், சில உள்ளக தொகுப்பு " +"படி தேவைப்படும் இறுதி பயனர் அமைப்புகளுக்கும் இவை பயனுள்ளதாக இருக்கும் (சி நீட்டிப்பு " +"போன்றவை)." + +#: ../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 "" +"The: ref: `பில்ட்` தொகுப்புக்கு இவற்றில் ஒன்றை உருவாக்க உங்கள் உருவாக்க கருவியை எவ்வாறு " +"செயல்படுத்துவது என்பது தெரியும்:" + +#: ../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 "கட்டப்பட்ட விநியோகங்கள் (சக்கரங்கள்)" + +#: ../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 "" +"ஒரு கட்டமைக்கப்பட்ட விநியோகத்தில் இறுதி பயனரின் பைதான் சூழலுக்குத் தேவையான கோப்புகள் " +"மட்டுமே உள்ளன. நிறுவலின் போது தொகுப்பு படிகள் எதுவும் தேவையில்லை, மேலும் சக்கரக் கோப்பை " +"`` தள-பேக்கேச்கள்`` கோப்பகத்தில் திறக்கலாம். இது இறுதி பயனர்களுக்கு நிறுவலை விரைவாகவும் " +"வசதியாகவும் செய்கிறது." + +#: ../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 "" +"ஒரு தூய பைதான் தொகுப்புக்கு பொதுவாக ஒரே \"பொதுவான\" சக்கரம் மட்டுமே தேவை. " +"தொகுக்கப்பட்ட பைனரி நீட்டிப்புகளைக் கொண்ட ஒரு தொகுப்புக்கு பைதான் மொழிபெயர்ப்பாளர், இயக்க " +"முறைமை மற்றும் சிபியு கட்டமைப்பு ஆகியவற்றின் ஒவ்வொரு ஆதரிக்கப்பட்ட கலவைக்கும் ஒரு சக்கரம் " +"தேவை. பொருத்தமான சக்கர கோப்பு கிடைக்கவில்லை என்றால், போன்ற கருவிகள்: குறிப்பு: `பிப்` " +"மூல விநியோகத்தை நிறுவுவதற்கு மீண்டும் விழும்." + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" +"அல்லது, உங்கள் உருவாக்க கருவி ஒரு சக்கரத்தை உருவாக்குவதற்கான அதன் சொந்த இடைமுகத்தை " +"வழங்கக்கூடும்." + +#: ../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: `` பில்ட்` என்பது தற்போதைய கோப்பகத்தில் மூலத்திலிருந்து ஒரு " +"SDIST மற்றும் சக்கரம் இரண்டையும் உருவாக்குவதாகும்; மேலே உள்ள எடுத்துக்காட்டுகள் " +"வேண்டுமென்றே குறிப்பிட்டவை." + +#: ../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 "" +"தி: ரெஃப்: `ட்வைன்` கருவி விநியோகத்திற்காக பைபிக்கு உருவாக்க கலைப்பொருட்களை " +"பதிவேற்றலாம், இது போன்ற கட்டளையைப் பயன்படுத்துகிறது:" + +#: ../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 "" +"இப்போது தொகுப்பு வெளியிடப்பட்டுள்ளதால், இறுதி பயனர்கள் தங்கள் பைதான் சூழலில் தொகுப்பை " +"பதிவிறக்கம் செய்து நிறுவலாம். பொதுவாக இது செய்யப்படுகிறது: ref: `பிப்`, போன்ற " +"கட்டளையைப் பயன்படுத்துதல்:" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" +"இறுதி பயனர்கள் போன்ற பிற கருவிகளையும் பயன்படுத்தலாம்: ref: `pipenv`,: ref:` கவிதை`, " +"அல்லது: ref: `PDM`." + +#: ../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 +#, fuzzy +#| msgid "" +#| "A library that takes a source tree and builds a :term:`source " +#| "distribution ` or :term:`built " +#| "distribution ` from it. The build is delegated to the " +#| "backend by a :term:`frontend `. All backends offer a " +#| "standardized interface." +msgid "" +"A library that takes a :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" +"ஒரு மூல மரத்தை எடுத்து ஒரு நூலகம் ஒரு: காலத்தை உருவாக்குகிறது: `மூல வழங்கல் <மூல " +"வழங்கல் (அல்லது\" SDIST \")>` அல்லது: கால: `கட்டப்பட்ட வழங்கல் <கட்டப்பட்ட விநியோகம்>` " +"அதிலிருந்து. கட்டமைப்பானது பின்தளத்தில் வழங்கப்படுகிறது: கால: `ஃபிரான்டென்ட் <பில்ட் " +"ஃபிரான்டெண்ட்>`. அனைத்து பின்தளத்தில் ஒரு தரப்படுத்தப்பட்ட இடைமுகத்தை வழங்குகிறது." + +#: ../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: `அட்ச் " +"அட்ச் அட்ச்லிங் <அட்ச்>`,: குறிப்பு: `மேட்டூரின்`,: குறிப்பு:` மீசன்-பைதான்`,: `ச்கிகிட் " +"-பில்ட்-கோர்`, மற்றும்: குறிப்பு: `செட்ப்டூல்ச்`." + +#: ../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 "" +"தன்னிச்சையான மூல மரங்களை எடுக்கும் பயனர்கள் இயக்கக்கூடிய ஒரு கருவி அல்லது: கால: `மூல " +"வழங்கல் <மூல வழங்கல் (அல்லது\" SDIST \")>` மற்றும் மூல விநியோகங்களை உருவாக்குகிறது " +"அல்லது: கால: `சக்கரங்கள் ` அவர்களிடமிருந்து. உண்மையான கட்டிடம் ஒவ்வொரு மூல " +"மரத்திற்கும் வழங்கப்படுகிறது: சொல்: `பின்தளத்தில் உருவாக்கு <பின்தளத்தில் உருவாக்கு>`." + +#: ../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 :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 +msgid "Built Metadata" +msgstr "மேனிலை தரவு கட்டப்பட்டது" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" +"கான்கிரீட் படிவம்: கால: `கோர் மெட்டாடேட்டா` ஒரு நிறுவப்பட்ட: கால:` திட்டம்` (`` " +"மெட்டாடேட்டா`` கோப்பு) அல்லது ஒரு: கால: கால: `விநியோக காப்பகம்` (` `பி.கே.சி-" +"இன்ஃபோ`` ஒரு: கால: `Sdist <மூல வழங்கல் (அல்லது\" Sdist \")>` மற்றும் `` " +"மெட்டாடேட்டா`` ஒரு: கால: `சக்கரம்`)." + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "கோர் மேனிலை தரவு" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" +"தி: ரெஃப்: `விவரக்குறிப்பு <கோர்-மெட்டாடேட்டா>` மற்றும் தொகுப்பு: கால: `கோர் மேனிலை " +"தரவு புலம்` \\ எச் இது ஒரு: காலத்தின் முக்கிய நிலையான பண்புகளை விவரிக்கும் " +"வரையறுக்கிறது:` விநியோக தொகுப்பு` அல்லது: கால: `நிறுவப்பட்ட திட்டம்` ." + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "கோர் மேனிலை தரவு புலம்" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" +"ஒற்றை விசை-மதிப்பு இணை (அல்லது ஒரே பெயருடன், பல பயன்பாட்டு புலங்களுக்கு) " +"வரையறுக்கப்பட்டுள்ளது: கால: `கோர் மெட்டாடேட்டா` ச்பெக் மற்றும் இல் சேமிக்கப்படுகிறது: " +"கால:` கட்டப்பட்ட மெட்டாடேட்டா`. குறிப்பிடத்தக்க வகையில், A இலிருந்து வேறுபட்டது: கால: " +"`பைபிரெக்ட் மேனிலை தரவு கீ`." + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "விநியோக காப்பகம்" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" +"ஒரு: கால: `விநியோக தொகுப்பு` க்கான இயற்பியல் விநியோக கலைப்பொருள் (அதாவது வட்டில் ஒரு " +"கோப்பு)." + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "விநியோக தொகுப்பு" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" +"பைதான்: கால: `தொகுப்புகள் <இறக்குமதி தொகுப்பு>`,: கால: `தொகுதிகள் <தொகுதி>`, மற்றும் " +"பிற ஆதாரக் கோப்புகள் ஆகியவற்றைக் கொண்ட பதிப்புக் காப்பக கோப்பு, ஒரு: கால: `வெளியீடு` " +"விநியோகிக்கப் பயன்படும் பிற வள கோப்புகள். காப்பகக் கோப்பு என்பது ஒரு இறுதி பயனர் " +"இணையத்திலிருந்து பதிவிறக்கம் செய்து நிறுவும்." + +#: ../source/glossary.rst:97 +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 "" +"ஒரு விநியோக தொகுப்பு பொதுவாக \"தொகுப்பு\" அல்லது \"வழங்கல்\" என்ற ஒற்றை சொற்களுடன் " +"குறிப்பிடப்படுகிறது, ஆனால் குழப்பத்தைத் தடுக்க கூடுதல் தெளிவு தேவைப்படும்போது இந்த " +"வழிகாட்டி விரிவாக்கப்பட்ட காலத்தைப் பயன்படுத்தலாம்: `இறக்குமதி தொகுப்பு` (இது " +"பொதுவாகவும் பொதுவாகவும் \"தொகுப்பு\" என்று அழைக்கப்படுகிறது) அல்லது மற்றொரு வகையான " +"வழங்கல் (எ.கா. ஒரு லினக்ச் வழங்கல் அல்லது பைதான் மொழி விநியோகம்), அவை பெரும்பாலும் " +"\"வழங்கல்\" என்ற ஒற்றை வார்த்தையுடன் குறிப்பிடப்படுகின்றன. காண்க: குறிப்பு: வேறுபாடுகளின் " +"முறிவுக்கு `விநியோக-பேக்கேச்-விஎச்-பிரசங்க-பேக்கேச்`." + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "முட்டை" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" +"ப: கால: `கட்டப்பட்ட விநியோகம்` வடிவம் அறிமுகப்படுத்தியவர்: குறிப்பு:` செட்டப்டூல்ச்`, இது " +"மாற்றப்பட்டது: கால: `சக்கரம்`. விவரங்களுக்கு, காண்க: ref: `முட்டை வடிவம்`." + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "நீட்டிப்பு தொகுதி" + +#: ../source/glossary.rst:114 +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 "" +"ப: கால: `தொகுதி` பைதான் அமலாக்கத்தின் குறைந்த அளவிலான மொழியில் எழுதப்பட்டது: " +"பைத்தானுக்கு சி/சி ++, சிதானுக்கு சாவா. பொதுவாக ஒற்றை மாறும் ஏற்றக்கூடிய முன்-" +"தொகுக்கப்பட்ட கோப்பில் உள்ளது, எ.கா. யுனிக்ச் இல் பைதான் நீட்டிப்புகளுக்கான பகிரப்பட்ட பொருள் " +"(.SO) கோப்பு, சாளரங்களில் பைத்தான் நீட்டிப்புகளுக்கான டி.எல்.எல் (.பிடி நீட்டிப்பு " +"கொடுக்கப்பட்டுள்ளது) அல்லது சைத்தான் நீட்டிப்புகளுக்கான சாவா வகுப்பு கோப்பு." + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "இறக்குமதி தொகுப்பு" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" +"ஒரு பைதான் தொகுதி மற்ற தொகுதிகள் அல்லது மீண்டும் மீண்டும், பிற தொகுப்புகளைக் " +"கொண்டிருக்கலாம்." + +#: ../source/glossary.rst:127 +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 "" +"ஒரு இறக்குமதி தொகுப்பு பொதுவாக \"தொகுப்பு\" என்ற ஒற்றை வார்த்தையுடன் " +"குறிப்பிடப்படுகிறது, ஆனால் குழப்பத்தைத் தடுக்க கூடுதல் தெளிவு தேவைப்படும்போது இந்த " +"வழிகாட்டி விரிவாக்கப்பட்ட காலத்தைப் பயன்படுத்தும்: ஒரு: கால: `விநியோக தொகுப்பு` இது " +"பொதுவாக\" தொகுப்பு \"என்றும் அழைக்கப்படுகிறது . காண்க: குறிப்பு: வேறுபாடுகளின் " +"முறிவுக்கு `விநியோக-பேக்கேச்-விஎச்-பிரசங்க-பேக்கேச்`." + +#: ../source/glossary.rst:133 +msgid "Installed Project" +msgstr "நிறுவப்பட்ட திட்டம்" + +#: ../source/glossary.rst:136 +#, fuzzy +#| msgid "" +#| "A :term:`Project` that is installed for use with a Python interpreter " +#| "or :term:`Virtual Environment`, as described in the " +#| "specicifcation :ref:`recording-installed-packages`." +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" +"ஒரு: கால: `திட்டம்` இது ஒரு பைதான் மொழிபெயர்ப்பாளருடன் பயன்படுத்த நிறுவப்பட்டுள்ளது " +"அல்லது: கால:` மெய்நிகர் சூழல்`, விவரக்குறிப்பில் விவரிக்கப்பட்டுள்ளபடி: குறிப்பு: `பதிவு-" +"நிறுவப்பட்ட-தொகுப்புகள்`." + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "அறியப்பட்ட நல்ல தொகுப்பு (கிலோ)" + +#: ../source/glossary.rst:143 +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 "" +"ஒருவருக்கொருவர் இணக்கமான குறிப்பிட்ட பதிப்புகளில் விநியோகங்களின் தொகுப்பு. பொதுவாக ஒரு " +"சோதனை தொகுப்பு இயக்கப்படும், இது ஒரு குறிப்பிட்ட தொகுப்புகள் அறியப்பட்ட நல்ல தொகுப்பாக " +"அறிவிக்கப்படுவதற்கு முன்பு அனைத்து சோதனைகளையும் கடந்து செல்லும். இந்த சொல் பொதுவாக பல " +"தனிப்பட்ட விநியோகங்களைக் கொண்ட கட்டமைப்புகள் மற்றும் கருவித்தொகுப்புகளால் " +"பயன்படுத்தப்படுகிறது." + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "உரிம வகைப்படுத்தி" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" +"ஒரு பைபி ட்ரோவ் வகைப்படுத்தி (AS: Ref: `விவரிக்கப்பட்ட <கோர்-மெட்டாடேட்டா-" +"கிளாசிஃபையர்>` இல்: கால: `கோர் மெட்டாடேட்டா` விவரக்குறிப்பு)` `உரிமம் ::` `உடன் " +"தொடங்குகிறது." + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "உரிம வெளிப்பாடு" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "SPDX வெளிப்பாடு" + +#: ../source/glossary.rst:161 +#, fuzzy +#| msgid "" +#| "A string with valid SPDX license expression syntax, including one or more " +#| "SPDX :term:`License Identifier`\\(s), which describes a :term:`Project`'s " +#| "license(s) and how they inter-relate. Examples: ``GPL-3.0-or-later``, " +#| "``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" +"ஒன்று அல்லது அதற்கு மேற்பட்ட SPDX உள்ளிட்ட செல்லுபடியாகும் SPDX உரிம வெளிப்பாடு " +"தொடரியல் கொண்ட ஒரு சரம்: சொல்: `உரிம அடையாளங்காட்டி` \\ (கள்), இது ஒரு: காலத்தை " +"விவரிக்கிறது:` திட்டத்தின் உரிமம் (கள்) மற்றும் அவை எவ்வாறு தொடர்புபடுத்தப்படுகின்றன. " +"எடுத்துக்காட்டுகள்: `` gpl-3.0 அல்லது-later``, `` MIT மற்றும் (APACHE-2.0 அல்லது " +"BSD-2-confase) ``" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "உரிம அடையாளங்காட்டி" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "SPDX அடையாளம் காணவும்" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" +"செல்லுபடியாகும் SPDX குறுகிய வடிவ உரிம அடையாளங்காட்டி, முதலில் குறிப்பிடப்பட்டுள்ளது: " +"PEP: `639`. இதில் அனைத்து செல்லுபடியாகும் SPDX அடையாளங்காட்டிகள் மற்றும் தனிப்பயன் `` " +"LicuenSeref- [idstring] `` SPDX விவரக்குறிப்புக்கு இணங்க சரங்கள் ஆகியவை அடங்கும். " +"எடுத்துக்காட்டுகள்: `` mit``, `` gpl -3.0-lonly``, `` licenseref-my-custom-" +"license``" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "தொகுதி" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "தொகுப்பு அட்டவணை" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" +"தானியங்குபடுத்த ஒரு வலை இடைமுகத்துடன் விநியோகங்களின் களஞ்சியம்: சொல்: `தொகுப்பு " +"<விநியோக தொகுப்பு>` கண்டுபிடிப்பு மற்றும் நுகர்வு." + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "திட்டக் குறியீட்டிற்கு" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "திட்டம்" + +#: ../source/glossary.rst:205 +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 "" +"ஒரு நூலகம், கட்டமைப்பு, ச்கிரிப்ட், சொருகி, பயன்பாடு அல்லது தரவு அல்லது பிற வளங்களின் " +"சேகரிப்பு அல்லது அதன் சில கலவையானது A: கால: `விநியோக <விநியோக தொகுப்பு>` இல் " +"தொகுக்கப்பட வேண்டும்." + +#: ../source/glossary.rst:209 +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`` `` பில்ட்-சிச்டம்``,: குறிப்பு: `தொலைதூரங்கள்` அல்லது: " +"ref:` setuptools`, திட்டங்களை வரையறுக்க மற்றொரு நடைமுறை வழி தற்போது ஒரு: கால: " +"`pyproject.toml`,: கால:` setup.py`, அல்லது: கால: `setup.cfg` கோப்பு திட்ட மூல " +"கோப்பகத்தில் உள்ள ஒன்று." + +#: ../source/glossary.rst:215 +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 "" +"பைதான் திட்டங்களில் தனித்துவமான பெயர்கள் இருக்க வேண்டும், அவை பதிவு செய்யப்பட்டுள்ளன: கால: " +"`பைபி <பைதான் தொகுப்பு குறியீட்டு (பைபி)>`. ஒவ்வொரு திட்டத்திலும் ஒன்று அல்லது அதற்கு " +"மேற்பட்டவை இருக்கும்: கால: `வெளியீடுகள் <வெளியீடு>`, மேலும் ஒவ்வொரு வெளியீட்டிலும் ஒன்று " +"அல்லது அதற்கு மேற்பட்டவை இருக்கலாம்: சொல்: `விநியோகம் <விநியோக தொகுப்பு>`." + +#: ../source/glossary.rst:220 +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:226 +msgid "Project Root Directory" +msgstr "திட்ட ரூட் அடைவு" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" +"கோப்பு முறைமை அடைவு இதில் A: கால: `திட்டம்` கள்: கால:` மூல மரம் <திட்ட மூல மரம்> " +"`அமைந்துள்ளது." + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "திட்ட மூல மரம்" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" +"A இன் ஆன்-வட்டு வடிவம்: கால: `திட்டம்` அபிவிருத்திக்குப் பயன்படுத்தப்படுகிறது, அதன் மூல " +"மூலக் குறியீட்டைக் கொண்டிருப்பதற்கு முன்பு அதன் மூல மூலக் குறியீட்டைக் கொண்டுள்ளது: கால:` " +"மூல வழங்கல் <மூல வழங்கல் (அல்லது \"SDIST\")> `அல்லது: கால:` கட்டப்பட்டது விநியோகம்`." + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "திட்ட மூல மேனிலை தரவு" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" +"ஒரு: கால: `திட்டம்` கள்: கால:` மூல மரம் <திட்ட மூல மரம்> `, மாற்றப்பட வேண்டும்: கால: " +"கால:` கோர் மேனிலை தரவு புலம்` \\ கள்: `கட்டப்பட்டவை திட்டத்தின் மூலம் மெட்டாடேட்டா: கால: " +"`பின்தளத்தில் உருவாக்கு <பின்தளத்தில் உருவாக்கு>`. இவ்வாறு எழுதலாம்: கால: `பைபிரெக்ட் " +"மெட்டாடேட்டா`, அல்லது கருவி-குறிப்பிட்ட வடிவத்தில் (` `[கருவி]` `` pyproject.toml`` " +"அல்லது ஒரு கருவியின் சொந்த உள்ளமைவு கோப்பில்) `` அட்டவணையின் கீழ்)." + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "தூய தொகுதி" + +#: ../source/glossary.rst:257 +msgid "" +"A :term:`Module` written in Python and contained in a single ``.py`` file " +"(and possibly associated ``.pyc`` and/or ``.pyo`` files)." +msgstr "" +"ஒரு: கால: `தொகுதி` பைத்தானில் எழுதப்பட்டு ஒற்றை` .py`` கோப்பில் (மற்றும் தொடர்புடைய " +"`` .பிசி`` மற்றும்/அல்லது `` .பியோ` கோப்புகள்) உள்ளன." + +#: ../source/glossary.rst:260 +msgid "Pyproject Metadata" +msgstr "Pyproject மேனிலை தரவு" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" +"தி: கால: `திட்ட மூல மெட்டாடேட்டா` வடிவம் வரையறுக்கப்பட்டுள்ளது: ref:` அறிவித்தல்-திட்ட-" +"மெட்டாடேட்டா` விவரக்குறிப்பை அறிவித்தல் மற்றும் முதலில் அறிமுகப்படுத்தப்பட்டது: PEP: " +"`621`, இவ்வாறு சேமிக்கப்படுகிறது:` பைபிரெக்ட் மேனிலை தரவு கீ` \\ கள் `கீழ் `[திட்டம்]` " +"`ஒரு அட்டவணை: கால:` pyproject.toml` கோப்பு. குறிப்பிடத்தக்க வகையில், `` " +"pyproject.toml`` இல் `` [கருவி] `` அட்டவணையின் கீழ் ஒரு கருவி-குறிப்பிட்ட மூல " +"மேனிலை தரவு வடிவமைப்பை * அல்ல." + +#: ../source/glossary.rst:271 +msgid "Pyproject Metadata Key" +msgstr "Pyproject Metadata key" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" +"`` திட்ட] `` `` pyproject.toml`` இல் ஒரு உயர்மட்ட டாம்ல் விசை; இதன் ஒரு பகுதி: கால: " +"`பைபிரொசெக்ட் மெட்டாடேட்டா`. குறிப்பிடத்தக்க வகையில், A இலிருந்து வேறுபட்டது: கால: " +"`கோர் மேனிலை தரவு புலம்`." + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "Pyproject மேனிலை தரவு சப்ச்கி" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" +"அட்டவணை மதிப்பீட்டின் கீழ் இரண்டாவது நிலை டாம்ல் விசை: கால: `பைபிரெக்ட் மேனிலை தரவு கீ`." + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "பைதான் பேக்கேசிங் ஆணையம் (பைபா)" + +#: ../source/glossary.rst:287 +#, fuzzy +#| 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 `__." +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" +"பைபா என்பது பைதான் பேக்கேசிங்கில் தொடர்புடைய பல திட்டங்களை பராமரிக்கும் ஒரு பணிக்குழு " +"ஆகும். அவர்கள் ஒரு தளத்தை பராமரிக்கின்றனர்: doc: `pypa.io `, `github " +"` _ மற்றும் `பிட்பக்கெட் " +"`_, மற்றும்` டிச்டிடில்ச்-சிக் அஞ்சல் பட்டியலில் உள்ள சிக்கல்களைப் பற்றி விவாதிக்கவும் //" +"discuss.python.org/c/packaging>`__." + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "பைதான் தொகுப்பு அட்டவணை (PYPI)" + +#: ../source/glossary.rst:298 +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 ` _ என்பது இயல்புநிலை: சொல்: பைதான் சமூகத்திற்கான `தொகுப்பு " +"குறியீடு`. அனைத்து பைதான் டெவலப்பர்களுக்கும் அவர்களின் விநியோகங்களை உட்கொள்வதற்கும் " +"விநியோகிப்பதற்கும் இது திறந்திருக்கும்." + +#: ../source/glossary.rst:301 +msgid "pypi.org" +msgstr "pypi.org" + +#: ../source/glossary.rst:304 +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 ` _ என்பது டொமைன் பெயர்: கால: `பைதான் தொகுப்பு அட்டவணை " +"(PYPI)`. இது 2017 ஆம் ஆண்டில் மரபு குறியீட்டு டொமைன் பெயரை மாற்றியது, `` " +"pypi.python.org``. இது இயக்கப்படுகிறது: ref: `கிடங்கு`." + +#: ../source/glossary.rst:308 +msgid "pyproject.toml" +msgstr "pyproject.toml" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" +"கருவி-அம்போச்டிக்: கால: `திட்டம்` விவரக்குறிப்பு கோப்பு. வரையறுக்கப்பட்டுள்ளது: PEP: " +"`518`." + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "வெளியீடு" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" +"A இன் ச்னாப்சாட்: கால: `திட்டம்` ஒரு குறிப்பிட்ட கட்டத்தில், பதிப்பு அடையாளங்காட்டியால் " +"குறிக்கப்படுகிறது." + +#: ../source/glossary.rst:319 +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 "" +"வெளியீட்டை உருவாக்குவது பல: கால: `விநியோகம் <விநியோக தொகுப்பு>` வெளியீட்டைக் " +"கொண்டிருக்கலாம். எடுத்துக்காட்டாக, ஒரு திட்டத்தின் பதிப்பு 1.0 வெளியிடப்பட்டால், அது ஒரு " +"மூல விநியோக வடிவம் மற்றும் சாளரங்கள் நிறுவி விநியோக வடிவத்தில் கிடைக்கக்கூடும்." + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "தேவை" + +#: ../source/glossary.rst:327 +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 "" +"ஒரு விவரக்குறிப்பு ஒரு: கால: `தொகுப்பு <விநியோக தொகுப்பு>` நிறுவப்பட வேண்டும். . " +"மேலும் தகவலுக்கு, பார்க்க: ref: `PIP: PIP INSTALL` குறிப்பு." + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "தேவை விவரக்குறிப்பு" + +#: ../source/glossary.rst:336 +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 "" +"பயன்படுத்திய ஒரு வடிவம்: ref: `பிப்` ஒரு: கால:` தொகுப்பு குறியீட்டு` இலிருந்து " +"தொகுப்புகளை நிறுவ. வடிவமைப்பின் ஈபிஎன்எஃப் வரைபடத்திற்கு, காண்க: குறிப்பு: `சார்பு-" +"விவரக்குறிப்புகள்`. எடுத்துக்காட்டாக, \"FOO> = 1.3\" என்பது ஒரு தேவை " +"விவரக்குறிப்பாகும், அங்கு \"FOO\" என்பது திட்ட பெயர், மற்றும் \"> = 1.3\" பகுதி: கால: " +"`பதிப்பு விவரக்குறிப்பு`" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "தேவைகள் கோப்பு" + +#: ../source/glossary.rst:344 +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: `பிப்` டாக்ச் ஆன்: குறிப்பு:` பிப்: " +"தேவைகள் கோப்புகள்`." + +#: ../source/glossary.rst:348 +msgid "Root License Directory" +msgstr "ரூட் உரிம அடைவு" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "உரிம அடைவு" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" +"எந்த உரிமக் கோப்புகள் ஒரு: கால: `திட்ட மூல மரம்`,: கால:` விநியோக காப்பகம்` அல்லது: " +"கால: `நிறுவப்பட்ட திட்டம்` என்ற கோப்பகத்தின் கீழ் உள்ள அடைவு. ஒரு: கால: `திட்ட மூல மரம்` " +"அல்லது: கால:` மூல வழங்கல் (அல்லது \"SDIST\") `, இது: கால:` திட்ட ரூட் அடைவு`. ஒரு: " +"காலத்திற்கு: `கட்டப்பட்ட விநியோகம்` அல்லது: கால:` நிறுவப்பட்ட திட்டம்`, இது: கோப்பு: " +"`.டிச்ட்-இன்ஃபோ/உரிமங்கள்/முறையே சக்கர காப்பகம் அல்லது திட்ட கோப்புறையின் அடைவு. மேலும், " +"`` உரிம-கோப்பு``: கால: `கோர் மேனிலை தரவு புலம்` இல் பதிவு செய்யப்பட்ட பாதைகள் " +"தொடர்புடையவை." + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "setup.py" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "setup.cfg" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" +"இதற்கான திட்ட விவரக்குறிப்பு கோப்புகள்: ref: `distutils` மற்றும்: ref:` setuptools`. " +"மேலும் காண்க: கால: `pyproject.toml`." + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "மூல காப்பகம்" + +#: ../source/glossary.rst:375 +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 "" +"A: காலத்திற்கான மூல மூலக் குறியீட்டைக் கொண்ட ஒரு காப்பகம்: `வெளியீடு`, ஒரு " +"உருவாக்குவதற்கு முன்: கால:` மூல வழங்கல் <மூல வழங்கல் (அல்லது \"SDIST\")> `அல்லது: " +"கால:` கட்டப்பட்ட விநியோகம்`." + +#: ../source/glossary.rst:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "மூல வழங்கல் (அல்லது \"SDIST\")" + +#: ../source/glossary.rst:382 +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." +msgstr "" +"ப: கால: `விநியோகம் <விநியோக காப்பகம்>` வடிவம் (வழக்கமாக `` பைதான் -எம் பில்ட் - " +"-ச்டிச்ட்`` ஐப் பயன்படுத்தி உருவாக்கப்படுகிறது) இது மெட்டாடேட்டாவையும் ஒரு கருவியால் " +"நிறுவ தேவையான அத்தியாவசிய மூல கோப்புகளையும் வழங்குகிறது: re: `பிப்`, அல்லது " +"உருவாக்க ஒரு: கால: `கட்டப்பட்ட விநியோகம்`. காண்க: குறிப்பு: மேலும் தகவலுக்கு `தொகுப்பு " +"வடிவங்கள்." + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "கணினி தொகுப்பு" + +#: ../source/glossary.rst:391 +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:394 +msgid "Version Specifier" +msgstr "பதிப்பு விவரக்குறிப்பு" + +#: ../source/glossary.rst:397 +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 "" +"A இன் பதிப்பு கூறு: கால: `தேவை விவரக்குறிப்பு`. எடுத்துக்காட்டாக, \"FOO> = 1.3\" இன் " +"\"> = 1.3\" பகுதி. படிக்கவும்: ref: `பதிப்பு விவரக்குறிப்பு விவரக்குறிப்பு <பதிப்பு-" +"விவரக்குறிப்புகள்>` பைதான் பேக்கேசிங் தற்போது ஆதரிக்கும் குறிப்பிட்ட விவரக்குறிப்பாளர்களின் " +"முழு விளக்கத்திற்கு. இந்த விவரக்குறிப்பிற்கான உதவி இதில் செயல்படுத்தப்பட்டது: குறிப்பு: " +"`setuptools` v8.0 மற்றும்: Ref:` Pip` v6.0." + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "மெய்நிகர் சூழல்" + +#: ../source/glossary.rst:405 +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 "" +"கணினி அகலமாக நிறுவப்படுவதை விட, ஒரு குறிப்பிட்ட பயன்பாட்டால் பயன்படுத்த தொகுப்புகளை " +"நிறுவ அனுமதிக்கும் ஒரு தனிமைப்படுத்தப்பட்ட பைதான் சூழல். மேலும் தகவலுக்கு, பகுதியைப் " +"பார்க்கவும்: ref: `மெய்நிகர் சூழல்களை உருவாக்குதல் மற்றும் பயன்படுத்துதல்`." + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "சக்கர வடிவம்" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "சக்கரம்" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" +"தரநிலை: சொல்: `கட்டப்பட்ட விநியோகம்` வடிவம் முதலில் அறிமுகப்படுத்தப்பட்டது: PEP:` 427` " +"மற்றும் வரையறுக்கப்பட்டுள்ளது: ref: `பைனரி-விநியோக வடிவ விவரங்கள்` விவரக்குறிப்பு. " +"காண்க: குறிப்பு: மேலும் தகவலுக்கு `தொகுப்பு வடிவங்கள். அதன் குறிப்பு செயல்படுத்தலுடன் " +"குழப்பமடையக்கூடாது, தி: கால: `சக்கர திட்டம்`." + +#: ../source/glossary.rst:421 +msgid "Wheel Project" +msgstr "சக்கர திட்டம்" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" +"பைபா குறிப்பு செயல்படுத்தல்: கால: `சக்கர வடிவமைப்பு`; காண்க: குறிப்பு: `சக்கரம்`." + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "வேலை தொகுப்பு" + +#: ../source/glossary.rst:429 +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 "" +"ஒரு தொகுப்பு: கால: `விநியோகம் <விநியோக தொகுப்பு>` இறக்குமதி செய்ய கிடைக்கிறது. " +"`Sys.path` மாறியில் இருக்கும் விநியோகங்கள் இவை. அதிகபட்சம், ஒன்று: சொல்: `விநியோக " +"<விநியோக தொகுப்பு>` ஒரு திட்டத்திற்கு வேலை செய்யும் தொகுப்பில் சாத்தியமாகும்." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "PYPI தொகுப்பு பதிவிறக்கங்களை பகுப்பாய்வு செய்தல்" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 பதிவிறக்க புள்ளிவிவர தரவுத்தொகுப்பை எவ்வாறு பயன்படுத்துவது " +"என்பதை இந்த பிரிவு உள்ளடக்கியது. எடுத்துக்காட்டாக, ஒரு தொகுப்பைப் பதிவிறக்குவதற்குப் " +"பயன்படுத்தப்படும் பைதான் பதிப்புகளின் விநியோகத்தைக் கண்டறிய இதைப் பயன்படுத்தலாம்." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "பின்னணி" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "பல காரணங்களுக்காக பதிவிறக்க புள்ளிவிவரங்களை PYPI காட்டாது: [#] _" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" +"** உள்ளடக்க விநியோக நெட்வொர்க்குடன் (சி.டி.என்) வேலை செய்ய திறமையற்றது: ** " +"புள்ளிவிவரங்களைப் பதிவிறக்குங்கள் தொடர்ந்து மாறுகிறது. திட்ட பக்கங்களில் அவற்றைச் சேர்ப்பது, " +"பெரிதும் தற்காலிக சேமிப்பில் உள்ளது, தற்காலிக சேமிப்பை அடிக்கடி செல்லாததாக்க வேண்டும், " +"மேலும் தற்காலிக சேமிப்பின் ஒட்டுமொத்த செயல்திறனைக் குறைக்கும்." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "`` பிஐபி பதிவிறக்கம் கேச் (பதிவிறக்க எண்ணிக்கையை குறைக்கிறது)" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" +"உள் அல்லது அதிகாரப்பூர்வமற்ற கண்ணாடிகள் (பதிவிறக்க எண்ணிக்கையை உயர்த்தலாம் அல்லது " +"குறைக்கலாம்)" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "PYPI இல் புரவலன் செய்யப்படாத தொகுப்புகள் (ஒப்பீடுகளுக்காக)" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" +"அதிகாரப்பூர்வமற்ற ச்கிரிப்ட்கள் அல்லது பதிவிறக்க எண்ணிக்கையிலான பணவீக்கத்திற்கான முயற்சிகள் " +"(பதிவிறக்க எண்ணிக்கையை உயர்த்தும்)" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "அறியப்பட்ட வரலாற்று தரவு தர சிக்கல்கள் (பதிவிறக்க எண்ணிக்கையை குறைக்கிறது)" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "பொது தரவுத்தொகுப்பு" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" +"மாற்றாக, `லைன்ஆல் திட்டம் ` __ " +"ச்ட்ரீம்கள் பைபியிலிருந்து `கூகிள் பிக்குவரி`_ [#] _ க்கு பதிவுகள் பதிவிறக்குகின்றன பொது " +"தரவுத்தொகுப்பு." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "அமைக்கப்படுகிறது" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" +"`பொது PYPI பதிவிறக்க புள்ளிவிவரங்கள் தரவுத்தொகுப்பு`_ ஐ வினவ` Google bigquery`_ ஐப் " +"பயன்படுத்த, உங்களுக்கு Google கணக்கு தேவை மற்றும் Google முகில் இயங்குதள திட்டத்தில் " +"பெரிய பநிஇ ஐ இயக்க வேண்டும். கடன் அட்டை இல்லாமல் பிக்வரி இலவச அடுக்கைப் பயன்படுத்தி " +"மாதத்திற்கு 1TB வினவல்கள் வரை இயக்கலாம் `__" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "`பெரிய வலை UI`_ க்கு செல்லவும்." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "புதிய திட்டத்தை உருவாக்கவும்." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" +"`BigQuery பநிஇ __." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" +"பிக்வெரியுடன் எவ்வாறு தொடங்குவது என்பது குறித்த விரிவான வழிமுறைகளுக்கு, `பிக்வெரி " +"குயிக்ச்டார்ட் வழிகாட்டி ____." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "தரவுத் திட்டம்" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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`` " +"அட்டவணையில் ஒரு பதிவை லைன்ஆல் எழுதுகிறார். எந்த கோப்பு பதிவிறக்கம் செய்யப்பட்டது, அது " +"எவ்வாறு பதிவிறக்கம் செய்யப்பட்டது என்பது பற்றிய தகவல்கள் அட்டவணையில் உள்ளன. `அட்டவணை ச்கீமா " +" __ இல் இருந்து சில பயனுள்ள " +"நெடுவரிசைகள்:` __" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "நெடுவரிசை" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "விவரம்" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "எடுத்துக்காட்டுகள்" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "தேதி மற்றும் நேரம்" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "திட்ட பெயர்" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "தொகுப்பு பதிப்பு" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "நிறுவி" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "பிப்,: ref: `bandersnatch`" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "பைதான் பதிப்பு" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "பயனுள்ள வினவல்கள்" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" +"\"வினவல்\" பொத்தானைக் சொடுக்கு செய்வதன் மூலம் `பிக்வெரி வலை UI`_ இல் வினவல்களை இயக்கவும்." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" +"வரிசைகள் ஒரு பகிர்வு செய்யப்பட்ட அட்டவணையில் சேமிக்கப்படுகின்றன என்பதை நினைவில் கொள்க, " +"இது வினவல்களின் விலையை கட்டுப்படுத்த உதவுகிறது. இந்த எடுத்துக்காட்டு வினவல்கள் `` நேர " +"முத்திரை` நெடுவரிசையில் வடிகட்டுவதன் மூலம் அண்மைக் கால வரலாற்றிலிருந்து பதிவிறக்கங்களை " +"பகுப்பாய்வு செய்கின்றன." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "தொகுப்பு பதிவிறக்கங்களை எண்ணுதல்" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" +"பின்வரும் வினவல் \"பைடெச்ட்\" திட்டத்திற்கான மொத்த பதிவிறக்கங்களின் எண்ணிக்கையைக் " +"கணக்கிடுகிறது." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" +"PIP இலிருந்து பதிவிறக்கங்களை மட்டும் எண்ணுவதற்கு, `` விவரங்கள்.இன்ச்டாலர்.நாம்`` " +"நெடுவரிசையில் வடிகட்டவும்." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "தொகுப்பு காலப்போக்கில் பதிவிறக்குகிறது" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" +"மாதாந்திர பதிவிறக்கங்கள் மூலம் குழுவாக, `` TimeStamp_Trunc`` செயல்பாட்டைப் " +"பயன்படுத்தவும். இந்த நெடுவரிசை மூலம் வடிகட்டுவது தொடர்புடைய செலவுகளைக் குறைக்கிறது." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "1956741" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "2344692" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "2017-12-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "1730398" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "2017-11-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "2047310" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "2017-10-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "1744443" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "2017-09-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "1916952" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "2017-08-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "காலப்போக்கில் பைதான் பதிப்புகள்" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" +"`` விவரங்கள் .பிதான்` நெடுவரிசையில் இருந்து பைதான் பதிப்பை பிரித்தெடுக்கவும். " +"எச்சரிக்கை: இந்த வினவல் 500 சிபி தரவை செயலாக்குகிறது." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "பைதான்" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "3.7" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "18051328726" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "3.6" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "9635067203" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "3.8" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "7781904681" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "2.7" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "6381252241" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "2026630299" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "3.5" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "1894153540" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "கலைப்பொருட்களுக்கு முழுமையான இணைப்புகளைப் பெறுதல்" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 இலிருந்து நீக்கப்பட்டிருந்தால். மேனிலை தரவு " +"அட்டவணையில் `` பாதை`` நெடுவரிசையை உள்ளடக்கியது, இதில் ஆச் மற்றும் கலைப்பொருள் கோப்பு " +"பெயர் அடங்கும்." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" +"இங்கே உருவாக்கப்படும் முகவரி நிலையானது என்று பொறுப்பு அளிக்கப்படவில்லை, ஆனால் தற்போது " +"PYPI கலைப்பொருட்கள் புரவலன் செய்யப்படும் முகவரி உடன் ஒத்துப்போகிறது." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "முகவரி" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +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/analyzing-pypi-package-downloads.rst:246 +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/analyzing-pypi-package-downloads.rst:248 +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/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "எச்சரிக்கைகள்" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" +"மேலே உள்ள பின்னணியில் பட்டியலிடப்பட்ட எச்சரிக்கைகளுக்கு மேலதிகமாக, லைன்ஆல் ஒரு பிழையால் " +"பாதிக்கப்பட்டார், இது சூலை 26, 2018 க்கு முன்னர் பதிவிறக்க புள்ளிவிவரங்களை கணிசமாகக் " +"கூறியது. இந்த தேதிக்கு முந்தைய பதிவிறக்கங்கள் விகிதாசாரமாக துல்லியமானவை (எ.கா. " +"பைதான் 2 வெர்சச் பைத்தானின் விழுக்காடு 3 பதிவிறக்கங்கள்) ஆனால் மொத்த எண்கள் அளவின் " +"வரிசையால் உண்மையானதை விட குறைவாக உள்ளன." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "கூடுதல் கருவிகள்" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" +"பிக்வெரி கன்சோலைப் பயன்படுத்துவதைத் தவிர, பதிவிறக்க புள்ளிவிவரங்களை பகுப்பாய்வு செய்யும் " +"போது பயனுள்ளதாக இருக்கும் சில கூடுதல் கருவிகள் உள்ளன." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "`` Google-Cloud-bigquery``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" +"பிக்வெரி பநிஇ மற்றும் பிக்வரிக்கான அதிகாரப்பூர்வ பைதான் கிளையன்ட் நூலகமான `கூகிள்-" +"கிளவுட்-பிக்வரி`_ திட்டத்தின் வழியாக பொது PYPI பதிவிறக்க புள்ளிவிவர தரவுத்தொகுப்பை " +"நிரல் முறையில் அணுகலாம்." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "`` பைபின்ஃபோ``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" +"`பைபின்ஃபோ`_ என்பது ஒரு கட்டளை-வரி கருவியாகும், இது தரவுத்தொகுப்பிற்கான அணுகலை " +"வழங்குகிறது மற்றும் பல பயனுள்ள வினவல்களை உருவாக்க முடியும். எடுத்துக்காட்டாக, `` " +"பைபின்ஃபோ தொகுப்பு_நாம்`` கட்டளையுடன் ஒரு தொகுப்புக்கான மொத்த பதிவிறக்கத்தின் எண்ணிக்கையை " +"வினவலாம்." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "PIP ஐப் பயன்படுத்தி `pypinfo`_ ஐ நிறுவவும்." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "பயன்பாடு:" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "`Panak-gbq``." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" +"`பாண்டாச்-GBQ`_ திட்டம்` பாண்டாச்`_ வழியாக வினவல் முடிவுகளை அணுக அனுமதிக்கிறது." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "குறிப்புகள்" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" +"`Pypi பதிவிறக்கம் எண்ணிக்கைகள் தேய்மான மின்னஞ்சல் ____ __ __" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" +"`Pypi bigquery தரவுத்தொகுப்பு அறிவிப்பு மின்னஞ்சல் ` __ __ __" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "செருகுநிரல்களை உருவாக்கி கண்டுபிடிப்பது" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" +"பெரும்பாலும் பைதான் பயன்பாடு அல்லது நூலகத்தை உருவாக்கும் போது ** செருகுநிரல்கள் ** " +"வழியாக தனிப்பயனாக்கங்கள் அல்லது கூடுதல் அம்சங்களை வழங்கும் திறனை நீங்கள் விரும்புவீர்கள். " +"பைதான் தொகுப்புகளை தனித்தனியாக விநியோகிக்க முடியும் என்பதால், உங்கள் பயன்பாடு அல்லது " +"நூலகம் தானாகவே ** கண்டுபிடிக்க விரும்பலாம் ** கிடைக்கும் அனைத்து செருகுநிரல்களும்." + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "தானியங்கி சொருகி கண்டுபிடிப்பை செய்வதற்கு மூன்று முக்கிய அணுகுமுறைகள் உள்ளன:" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "`பெயரிடும் மாநாட்டைப் பயன்படுத்துதல்`_." + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "`பெயர்வெளி தொகுப்புகளைப் பயன்படுத்துதல்`_." + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "`தொகுப்பு மெட்டாடேட்டா`_ ஐப் பயன்படுத்துதல்." + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "பெயரிடும் மாநாட்டைப் பயன்படுத்துதல்" + +#: ../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 "" +"உங்கள் பயன்பாட்டிற்கான அனைத்து செருகுநிரல்களும் ஒரே பெயரிடும் மாநாட்டைப் பின்பற்றினால், " +"நீங்கள் பயன்படுத்தலாம்: func: `pkgutil.iter_modules` பெயரிடும் மாநாட்டுடன் " +"பொருந்தக்கூடிய அனைத்து உயர்மட்ட தொகுதிகள் அனைத்தையும் கண்டறிய. எடுத்துக்காட்டாக, " +"`பிளாச்க்`_ பெயரிடும் மாநாட்டை` `பிளாச்க்_ {plugin_name}` `பயன்படுத்துகிறது. " +"நிறுவப்பட்ட அனைத்து பிளாச்க் செருகுநிரல்களையும் தானாகவே கண்டுபிடிக்க விரும்பினால்:" + +#: ../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 "" +"உங்களிடம் `பிளாச்க்-சதுரச்செமி`_ மற்றும்` பிளாச்க்-டலிசான்`_ செருகுநிரல்கள் இரண்டையும் " +"நிறுவியிருந்தால், `` கண்டுபிடிக்கப்பட்ட_பிளகின்ச்`` இருக்கும்:" + +#: ../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 "" +"செருகுநிரல்களுக்கான பெயரிடும் மாநாட்டைப் பயன்படுத்துவது பைதான் தொகுப்பு குறியீட்டின் " +"வினவலையும் அனுமதிக்கிறது: குறிப்பு: `எளிய களஞ்சிய பநிஇ <எளிய-ரோபோசிட்டரி-ஏபிஐ>` " +"உங்கள் பெயரிடும் மாநாட்டிற்கு இணங்கும் அனைத்து தொகுப்புகளுக்கும்." + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "பெயர்வெளி தொகுப்புகளைப் பயன்படுத்துதல்" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" +". எடுத்துக்காட்டாக, நீங்கள் `` myapp.plugins`` ஒரு பெயர்வெளி தொகுப்பை உருவாக்கினால், " +"பிற: கால: `விநியோகம் <விநியோக தொகுப்பு>` அந்த பெயர்வெளியில் தொகுதிகள் மற்றும் " +"தொகுப்புகளை வழங்க முடியும். நிறுவியதும், நீங்கள் பயன்படுத்தலாம்: func: " +"`pkgutil.iter_modules` அந்த பெயர்வெளியின் கீழ் நிறுவப்பட்ட அனைத்து தொகுதிகள் மற்றும் " +"தொகுப்புகளைக் கண்டறிய:" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" +"`` Myapp.plugins .__ பாதை__`` க்கு: func: `~ pkgutil.iter_modules` இது அந்த " +"பெயர்வெளியின் கீழ் நேரடியாக தொகுதிகளை மட்டுமே தேடுகிறது. எடுத்துக்காட்டாக, `` " +"myapp.plugins.a`` மற்றும் `` myapp.plugins.b`` தொகுதிகளை வழங்கும் விநியோகங்களை " +"நீங்கள் நிறுவியிருந்தால், இந்த விசயத்தில் `` கண்டுபிடிக்கப்பட்ட_பிலுசின்ச்`` இருக்கும்:" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" +"இந்த மாதிரி ஒரு துணை தொகுப்பாக பெயர்வெளி தொகுப்பாக (`` myapp.plugins``) " +"பயன்படுத்துகிறது, ஆனால் இந்த நோக்கத்திற்காக ஒரு உயர்மட்ட தொகுப்பைப் பயன்படுத்தவும் முடியும் " +"(`` MyApp_plugins` போன்றவை). பயன்படுத்த பெயர்வெளியை எவ்வாறு தேர்ந்தெடுப்பது என்பது " +"விருப்பமான சேதி, ஆனால் உங்கள் திட்டத்தின் முக்கிய உயர்மட்ட-நிலை தொகுப்பை (`` MyApp`` " +"`இந்த விசயத்தில்) செருகுநிரல்களின் நோக்கத்திற்காக ஒரு பெயர்வெளி தொகுப்பு செய்ய " +"பரிந்துரைக்கப்படவில்லை, ஒரு மோசமான சொருகி முடியும் முழு பெயர்வெளிகளையும் உடைக்கச் " +"செய்யுங்கள், இது உங்கள் திட்டத்தை இறக்காதது. வேலை செய்வதற்கான \"பெயர்வெளி துணை-பேக்கேச்\" " +"அணுகுமுறைக்கு, சொருகி தொகுப்புகள் பின்வாங்க வேண்டும்: கோப்பு: `__init __. உங்கள் " +"உயர்மட்ட தொகுப்பு கோப்பகத்திற்கு (இந்த விசயத்தில்` `MyApp``) . செருகுநிரல்கள் " +"தொகுப்புகளின் பட்டியலை வெளிப்படையாக அனுப்ப வேண்டும் என்பதும் இதன் பொருள்: func: `setup` " +"இன்` `தொகுப்புகள்`` பயன்படுத்துவதற்கு பதிலாக: func:` setuptools.find_packages`." + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" +"பெயர்வெளி தொகுப்புகள் ஒரு சிக்கலான அம்சமாகும், அவற்றை உருவாக்க பல்வேறு வழிகள் உள்ளன. " +"உங்கள் திட்டத்திற்கு செருகுநிரல்களுக்கு எந்த அணுகுமுறை விரும்பப்படுகிறது என்பதை தெளிவாக " +"ஆவணப்படுத்த: DOC: `பேக்கேசிங்-பெயர்ச்பேச்-பேக்கேச்கள்` ஆவணங்கள் மற்றும் தெளிவாக ஆவணப்படுத்த " +"இது மிகவும் பரிந்துரைக்கப்படுகிறது." + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "தொகுப்பு மெட்டாடேட்டாவைப் பயன்படுத்துதல்" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" +"தொகுப்புகள்: ref: `நுழைவு புள்ளிகள்` இல் விவரிக்கப்பட்டுள்ள செருகுநிரல்களுக்கான " +"மெட்டாடேட்டாவைக் கொண்டிருக்கலாம். அவற்றைக் குறிப்பிடுவதன் மூலம், ஒரு தொகுப்பு ஒரு " +"குறிப்பிட்ட வகையான சொருகி இருப்பதாக அறிவிக்கிறது. இந்த வகையான சொருகி ஆதரிக்கும் " +"மற்றொரு தொகுப்பு அந்த சொருகி கண்டுபிடிக்க மெட்டாடேட்டாவைப் பயன்படுத்தலாம்." + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" +"எடுத்துக்காட்டாக, உங்களிடம் `` myApp-plugin-a`` என்ற தொகுப்பு இருந்தால், அதன் `` " +"pyproject.toml`` இல் பின்வருவனவற்றை உள்ளடக்கியது:" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +msgid "" +"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 "" +"பயன்படுத்துவதன் மூலம் பதிவுசெய்யப்பட்ட அனைத்து நுழைவு புள்ளிகளையும் கண்டுபிடித்து " +"ஏற்றலாம்: func: `இறக்குமதி." + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" +"இந்த எடுத்துக்காட்டில், `` கண்டுபிடிக்கப்பட்ட_பிளகின்ச்`` வகை வகையின் தொகுப்பாக இருக்கும்: " +"வகுப்பு: `இறக்குமதி." + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" +"இப்போது உங்கள் விருப்பத்தின் தொகுதியை `` கண்டுபிடிக்கப்பட்ட_ப்ளூசின்களை ['அ'] " +"செயல்படுத்துவதன் மூலம் இறக்குமதி செய்யலாம். ஏற்றவும் () ``." + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" +"`` Entry_point`` விவரக்குறிப்பு: கோப்பு: `setup.py` மிகவும் நெகிழ்வானது மற்றும் " +"நிறைய விருப்பங்களைக் கொண்டுள்ளது. இதில் முழு பகுதியையும் படிக்க பரிந்துரைக்கப்படுகிறது: " +"DOC: `நுழைவு புள்ளிகள் `." + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" +"இந்த விவரக்குறிப்பு: டாக்: `நிலையான நூலகம் <பைதான்: நூலகம்/இறக்குமதி " +"லிப்.மெட்டாடேட்டா>` `, செட்டுப்டூல்கள் தவிர பிற பெரும்பாலான பேக்கேசிங் கருவிகள் நுழைவு " +"புள்ளிகளை வரையறுப்பதற்கான ஆதரவை வழங்குகின்றன." + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "கட்டளை-வரி கருவிகளை உருவாக்கி பேக்கேசிங் செய்யுங்கள்" + +#: ../source/guides/creating-command-line-tools.rst:7 +#, fuzzy +#| msgid "" +#| "This guide will walk you through creating and packaging a standalone " +#| "command-line application that can be installed with :ref:`pipx`, a tool " +#| "creating and managing :term:`Python Virtual Environments ` and exposing the executable scripts of packages (and " +#| "available manual pages) for use on the command-line." +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" +"இந்த வழிகாட்டி நிறுவக்கூடிய ஒரு முழுமையான கட்டளை-வரி பயன்பாட்டை உருவாக்கி பேக்கேசிங் " +"செய்வதன் மூலம் உங்களை அழைத்துச் செல்லும்: குறிப்பு: `பிப்எக்ச்`, ஒரு கருவி உருவாக்கி " +"நிர்வகிக்கும் ஒரு கருவி: கால:` பைதான் மெய்நிகர் சூழல்கள் <மெய்நிகர் சூழல்> `மற்றும் " +"இயங்கக்கூடிய ச்கிரிப்ட்களை அம்பலப்படுத்துதல் கட்டளை வரியில் பயன்படுத்த தொகுப்புகள் (மற்றும் " +"கிடைக்கக்கூடிய கையேடு பக்கங்கள்)." + +#: ../source/guides/creating-command-line-tools.rst:12 +msgid "Creating the package" +msgstr "தொகுப்பை உருவாக்குதல்" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" +"முதலாவதாக, ஒரு மூல மரத்தை உருவாக்கவும்: கால: `திட்டம் <திட்டம்>`. ஒரு உதாரணத்தின் " +"பொருட்டு, கட்டளை வரியில் கொடுக்கப்பட்ட வாதங்களின் அடிப்படையில் ஒரு நபருக்கு வாழ்த்து (ஒரு " +"சரம்) வெளியிடுவதற்கான எளிய கருவியை உருவாக்குவோம்." + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "அனைத்தும்" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" +"மற்றொரு வழிகாட்டி அல்லது கலந்துரையாடலில் பைதான் தொகுப்பின் உகந்த கட்டமைப்பைப் பற்றி " +"அறிவுறுத்துங்கள், அதனுடன் இங்கே இணைக்கவும்." + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" +"இந்த திட்டம் இதைக் கடைப்பிடிக்கும்: குறிப்பு: `எச்.ஆர்.சி-லேஅவுட் <எச்.ஆர்.சி-லேஅவுட்-" +"வி.எச்-ஃப்ளாட்-லேஅவுட்>` மற்றும் இறுதியில் இந்த கோப்பு மரத்தில், உயர்மட்ட கோப்புறை மற்றும் " +"தொகுப்பு பெயர் `` வாழ்த்துக்கள்`` உடன் ஒரே மாதிரியாக இருக்கும்:" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" +"கருவியின் செயல்பாட்டிற்கு பொறுப்பான உண்மையான குறியீடு கோப்பில் சேமிக்கப்படும்: கோப்பு: " +"`வாழ்த்துக்கள்." + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" +"மேலே உள்ள செயல்பாடு பல முக்கிய வாதங்களைப் பெறுகிறது, இது வெளியீட்டிற்கான வாழ்த்து " +"எவ்வாறு கட்டமைக்கப்படுகிறது என்பதை தீர்மானிக்கிறது. இப்போது, கட்டளை-வரி இடைமுகத்தை அதை " +"வழங்குவதற்காக உருவாக்குங்கள், இது செய்யப்படுகிறது: கோப்பு: `cli.py`:" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" +"கட்டளை-வரி இடைமுகம் பைதான் வகை குறிப்புகளின் அடிப்படையில் பயன்படுத்த எளிதான கிளி " +"பாகுபடுத்தி TYPER_ உடன் கட்டப்பட்டுள்ளது. இது தானாக முடக்கம் மற்றும் பெட்டியின் " +"நேர்த்தியான பாணியில் கட்டளை-வரி உதவியை வழங்குகிறது. மற்றொரு விருப்பம்: PY: MOD: " +"`ArgParse`, ஒரு கட்டளை-வரி பாகுபடுத்தி, இது பைத்தானின் நிலையான நூலகத்தில் " +"சேர்க்கப்பட்டுள்ளது. இது பெரும்பாலான தேவைகளுக்கு போதுமானது, ஆனால் நிறைய குறியீடு " +"தேவைப்படுகிறது, பொதுவாக `` cli.py`` இல், சரியாக செயல்பட வேண்டும். மாற்றாக, " +"டாக்ச்டோப்_ டாக்ச்ட்ரிங்சை மட்டுமே அடிப்படையாகக் கொண்ட சி.எல்.ஐ இடைமுகங்களை உருவாக்குவதை " +"சாத்தியமாக்குகிறது; மேம்பட்ட பயனர்கள் கிளிக்_ ஐப் பயன்படுத்த ஊக்குவிக்கப்படுகிறார்கள் (இதில் " +"`` டைபர்`` அடிப்படையாகும்)." + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" +"இப்போது, ஒரு வெற்று: கோப்பு: `__init __. Py` கோப்பு, திட்டத்தை ஒரு வழக்கமானதாக " +"வரையறுக்க: கால:` இறக்குமதி தொகுப்பு <இறக்குமதி தொகுப்பு> `." + +#: ../source/guides/creating-command-line-tools.rst:88 +#, fuzzy +#| msgid "" +#| "The file :file:`__main__.py` marks the main entry point for the " +#| "application when running it via :mod:`runpy` (i.e. ``python -m " +#| "greetings``, which works immediately with flat layout, but requires " +#| "installation of the package with src layout), so initizalize the command-" +#| "line interface here:" +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" +"கோப்பு: கோப்பு: `__main __. Py` பயன்பாட்டிற்கான முக்கிய நுழைவு புள்ளியை இயக்கும் போது " +"குறிக்கிறது: MOD:` Runpy` (அதாவது `` பைதான் -M வாழ்த்துக்கள்``, இது உடனடியாக " +"தட்டையான தளவமைப்புடன் வேலை செய்கிறது, ஆனால் நிறுவல் தேவைப்படுகிறது எச்.ஆர்.சி " +"தளவமைப்புடன் கூடிய தொகுப்பு), எனவே கட்டளை-வரி இடைமுகத்தை இங்கேயே தொடங்கவும்:" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" +"கட்டளை-வரி இடைமுகத்தை நேரடியாக அழைப்பதை இயக்குவதற்கு: `மூல மரம் <திட்ட மூல மரம்>`, " +"அதாவது `` பைதான் எச்.ஆர்.சி/வாழ்த்துக்கள்``, இந்த கோப்பில் ஒரு குறிப்பிட்ட ஏக் " +"வைக்கப்படலாம்; மேலும் வாசிக்க: ref: `ரன்னிங்-கிளி-ஃபிரோம்-மூல-எச்.ஆர்.சி-லேஅவுட்`." + +#: ../source/guides/creating-command-line-tools.rst:106 +msgid "``pyproject.toml``" +msgstr "`` pyproject.toml``" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" +"திட்டத்தின்: கால: `மெட்டாடேட்டா <பைபிரோசெக்ட் மெட்டாடேட்டா>` வைக்கப்பட்டுள்ளது: கால: " +"`pyproject.toml`. தி: கால: `பைபிரொசெக்ட் மேனிலை தரவு விசைகள் <பைபிரோசெக்ட் மேனிலை " +"தரவு விசை>` மற்றும் `` [பில்ட்-சிச்டம்] `` அட்டவணை விவரிக்கப்பட்டுள்ளபடி நிரப்பப்படலாம்: " +"`` எழுதுதல்-பிப்ரோசெக்ட்-டோம்ல்`, `` `` டைபர்`` (இந்த பயிற்சி பதிப்பைப் பயன்படுத்துகிறது " +"*0.12.3 *)." + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" +"திட்டம் ஒரு கட்டளை-வரி கருவியாக அங்கீகரிக்கப்படுவதற்கு, கூடுதலாக ஒரு `` " +"கன்சோல்_ச்கிரிப்ட்ச்``: குறிப்பு: `நுழைவு புள்ளி <நுழைவு புள்ளிகள்>` (பார்க்க: குறிப்பு: " +"`கன்சோல்_ச்கிரிப்ட்ச்`) ஒரு: காலமாக சேர்க்கப்பட வேண்டும்: `சப்ச்கே <பைபிரோசெக்ட் மேனிலை " +"தரவு சப்ச்கி>`:" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" +"இப்போது, திட்டத்தின் மூல மரம் A: காலமாக மாற்ற தயாராக உள்ளது: `விநியோக தொகுப்பு " +"<விநியோக தொகுப்பு>`, இது நிறுவக்கூடியதாக அமைகிறது." + +#: ../source/guides/creating-command-line-tools.rst:123 +msgid "Installing the package with ``pipx``" +msgstr "`` பிப்எக்ச்`` உடன் தொகுப்பை நிறுவுதல்" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" +"இவ்வாறு விவரிக்கப்பட்டுள்ளபடி `` பிப்எக்ச்`` ஐ நிறுவிய பிறகு: குறிப்பு: `தனியாக-கட்டம்-" +"கட்டளை-கோல்களை நிறுவுதல், உங்கள் திட்டத்தை நிறுவவும்:" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" +"இது ஒரு நுழைவு புள்ளியாக நாங்கள் வரையறுத்துள்ள இயங்கக்கூடிய ச்கிரிப்டை அம்பலப்படுத்தும் " +"மற்றும் கட்டளையை `` வாழ்த்துக்கள்`` கிடைக்கச் செய்யும். அதை சோதிப்போம்:" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" +"இந்த எடுத்துக்காட்டு `` டைபர்`` ஐப் பயன்படுத்துவதால், நிரல் பயன்பாட்டின் ``--எல்ப்`` " +"விருப்பத்துடன் அழைப்பதன் மூலம் அல்லது ``-நிறுவல்-முடித்தல்`` விருப்பத்தின் மூலம் நிறைவுகளை " +"உள்ளமைக்கவும் இப்போது நிரலின் பயன்பாட்டின் கண்ணோட்டத்தையும் பெறலாம் ." + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" +"நிரலை நிரந்தரமாக நிறுவாமல் இயக்க, `` பிப்எக்ச் ரன்`` ஐப் பயன்படுத்தவும், இது ஒரு " +"தற்காலிக (ஆனால் தற்காலிக சேமிப்பு) மெய்நிகர் சூழலை உருவாக்கும்:" + +#: ../source/guides/creating-command-line-tools.rst:156 +#, fuzzy +#| msgid "" +#| "This syntax is a bit unpractical, however; as the name of the entry point " +#| "we defined above does not match the package name, we need to state " +#| "explicitly which executable script to run (even though there is only on " +#| "in existence)." +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" +"இருப்பினும், இந்த தொடரியல் சற்று நடைமுறைக்கு மாறானது; நாங்கள் மேலே வரையறுத்த நுழைவு " +"புள்ளியின் பெயர் தொகுப்பு பெயருடன் பொருந்தவில்லை என்பதால், எந்த இயங்கக்கூடிய ச்கிரிப்டை " +"இயக்க வேண்டும் என்பதை நாம் வெளிப்படையாகக் கூற வேண்டும் (இருப்பு மட்டுமே இருந்தாலும்)." + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" +"எவ்வாறாயினும், இந்த சிக்கலுக்கு மிகவும் நடைமுறை தீர்வு உள்ளது, `` பிப்எக்ச் ரன்`` க்கு " +"குறிப்பிட்ட நுழைவு புள்ளியின் வடிவத்தில். பின்வருமாறு இதை வரையறுக்கலாம்: கோப்பு: " +"`pyproject.toml`:" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" +"இந்த நுழைவு புள்ளிக்கு நன்றி (இது * தொகுப்பு பெயருடன் பொருந்த வேண்டும்), `` பிப்எக்ச்`` " +"இயங்கக்கூடிய ச்கிரிப்டை இயல்புநிலையாக எடுத்துக்கொண்டு இயக்கும், இது இந்த கட்டளையை " +"சாத்தியமாக்குகிறது:" + +#: ../source/guides/creating-command-line-tools.rst:176 +msgid "Conclusion" +msgstr "முடிவு" + +#: ../source/guides/creating-command-line-tools.rst:178 +#, fuzzy +#| msgid "" +#| "You know by now how to package a command-line application written in " +#| "Python. A further step could be to distribute you package, meaning " +#| "uploading it to a :term:`package index `, most " +#| "commonly :term:`PyPI `. To do that, follow " +#| "the instructions at :ref:`Packaging your project`. And once you're done, " +#| "don't forget to :ref:`do some research ` on how your package is received!" +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" +"பைத்தானில் எழுதப்பட்ட கட்டளை-வரி பயன்பாட்டை எவ்வாறு தொகுப்பது என்பது இப்போது உங்களுக்குத் " +"தெரியும். உங்கள் தொகுப்பை விநியோகிப்பதே மேலும் படி, அதாவது அதை A க்கு பதிவேற்றுவது: " +"சொல்: `தொகுப்பு அட்டவணை <தொகுப்பு குறியீட்டு>`, பொதுவாக: கால: `பைபி <பைதான் தொகுப்பு " +"குறியீட்டு (பைபி)>`. அதைச் செய்ய, வழிமுறைகளைப் பின்பற்றவும்: குறிப்பு: `உங்கள் திட்டத்தை " +"பேக்கேசிங் செய்தல்`. நீங்கள் முடித்ததும், மறந்துவிடாதீர்கள்: குறிப்பு: `சில ஆராய்ச்சி " +"செய்யுங்கள் <உங்கள் தொகுப்பு எவ்வாறு பெறப்படுகிறது என்பதைப் பற்றி பகுப்பாய்வு செய்தல்-பைபி-" +"பேக்கேச்-டவுன்லோடுகளை பகுப்பாய்வு செய்யுங்கள்!" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "திட்டங்களை பேக்கேசிங் மற்றும் விநியோகித்தல்" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "காலாவதியான" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "2023-12-14" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" +"இந்த பிரிவு பைதான் திட்டங்களை உள்ளமைத்தல், பேக்கேசிங் மற்றும் விநியோகித்தல் பற்றிய சில " +"கூடுதல் விவரங்களை `` செடிப்டூல்ச்`` உடன் அறிமுகம் டுடோரியலால் உள்ளடக்கியது: டாக்: `/" +"டுடோரியல்கள்/பேக்கேசிங்-திட்டங்கள்`. : டாக்: `/டுடோரியல்கள்/நிறுவுதல்-பேக்கேச்கள்` பக்கத்தின் " +"உள்ளடக்கங்களை நீங்கள் ஏற்கனவே அறிந்திருக்கிறீர்கள் என்று அது இன்னும் கருதுகிறது." + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" +"ஒட்டுமொத்தமாக பைதான் திட்ட மேம்பாட்டுக்கான சிறந்த நடைமுறைகளை ஈடுகட்ட இந்த பிரிவு * " +"இல்லை *. எடுத்துக்காட்டாக, இது பதிப்பு கட்டுப்பாடு, ஆவணங்கள் அல்லது சோதனைக்கான " +"வழிகாட்டுதல் அல்லது கருவி பரிந்துரைகளை வழங்காது." + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" +"மேலும் குறிப்புப் பொருளுக்கு, காண்க: எச்.டி.டி: டிஓசி: `தொகுப்புகளை உருவாக்குதல் " +"மற்றும் விநியோகித்தல் <செட்டப்டூல்ச்: யு.எச்.இ. மோதல்கள் ஏற்பட்டால், பைதான் பேக்கேசிங் பயனர் " +"வழிகாட்டியில் ஆலோசனையை விரும்புங்கள்." + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "பேக்கேசிங் மற்றும் விநியோகிப்பதற்கான தேவைகள்" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" +"முதலில், நீங்கள் ஏற்கனவே நிறைவு செய்துள்ளீர்கள் என்பதை உறுதிப்படுத்திக் கொள்ளுங்கள்: ref: " +"`தொகுப்புகளை நிறுவுவதற்கான தேவைகள் <நிறுவல்_ரொக்விரெமென்ட்ச்>`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "\"கயிறு\" நிறுவவும் [1] _:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" +"உங்கள் திட்டத்தை பதிவேற்ற உங்களுக்கு இது தேவைப்படும்: கால: `விநியோகங்கள் <விநியோக " +"தொகுப்பு>` க்கு: கால: `பைபி <பைதான் தொகுப்பு குறியீட்டு (பைபி)>` (பார்க்க: `கீழே <கீழே " +"<உங்கள் திட்டத்தை பைபி>` ." + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"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 "" +"மிக முக்கியமான கோப்பு: கோப்பு: உங்கள் திட்ட கோப்பகத்தின் மூலத்தில் இருக்கும் `setup.py`. " +"ஒரு எடுத்துக்காட்டுக்கு, `setup.py `_." + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr ": கோப்பு: `setup.py` இரண்டு முதன்மை செயல்பாடுகளுக்கு உதவுகிறது:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" +"உங்கள் திட்டத்தின் பல்வேறு நற்பொருத்தங்கள் கட்டமைக்கப்பட்ட கோப்பு இது. இதன் முதன்மை அம்சம்: " +"கோப்பு: `setup.py` என்னவென்றால், அதில் உலகளாவிய` `அமைவு ()` `செயல்பாடு உள்ளது. இந்த " +"செயல்பாட்டிற்கான முக்கிய வாதங்கள் உங்கள் திட்டத்தின் குறிப்பிட்ட விவரங்கள் எவ்வாறு " +"வரையறுக்கப்படுகின்றன என்பதுதான். மிகவும் பொருத்தமான வாதங்கள் இதில் விளக்கப்பட்டுள்ளன: ref: " +"`கீழே உள்ள பிரிவு <அமைவு () args>`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" +"பேக்கேசிங் பணிகளுடன் தொடர்புடைய பல்வேறு கட்டளைகளை இயக்குவதற்கான கட்டளை வரி இடைமுகம் " +"இது. கிடைக்கக்கூடிய கட்டளைகளின் பட்டியலைப் பெற, `` python3 setup.py--help-" +"commands`` ஐ இயக்கவும்." + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +". ஒரு எடுத்துக்காட்டுக்கு, `setup.cfg _` _ _ _ _ _ _ _ _ _ " +"மாதிரி தயாரிப்பு> `_." + +#: ../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 "" +"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 "" +"எல்லா திட்டங்களிலும் திட்டத்தின் இலக்கை உள்ளடக்கிய README கோப்பு இருக்க வேண்டும். மிகவும் " +"பொதுவான வடிவம் `மறுசீரமைக்கப்பட்ட டெக்ச்ட் ` _ ஒரு \"rst\" நீட்டிப்புடன், இது ஒரு தேவையில்லை என்றாலும்; `மார்க் பேரூர் " +" _ _ ஆகியவற்றின் பல வகைகளும் " +"ஆதரிக்கப்படுகின்றன (` `அமைவு ()` `கள்: ref:` long_description_content_type " +" `வாதம்)." + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" +"எடுத்துக்காட்டுக்கு, `Readme.md ` _ `pypa மாதிரி திட்டத்திலிருந்து `_." + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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: `setuptools` 0.6.27+ நிலையான README கோப்புகளைக் " +"கொண்டுள்ளன (: கோப்பு:` readme.rst`,: கோப்பு: `ReadMe.txt`, அல்லது: கோப்பு:` " +"README`) மூல விநியோகங்களில் இயல்பாகவே. உள்ளமைக்கப்பட்ட: ref: `தொலைதூரங்கள்` நூலகம் இந்த " +"நடத்தையை பைத்தான் 3.7 இல் தொடங்குகிறது. கூடுதலாக, குறிப்பு: `setuptools` 36.4.0+ " +"ஒரு: கோப்பு:` Readme.md` கிடைத்தால் அடங்கும். நீங்கள் செட்டுப்டூல்களைப் பயன்படுத்துகிறீர்கள் " +"என்றால், உங்கள் README கோப்பை அதில் பட்டியலிட தேவையில்லை: கோப்பு: `manifest.in`. " +"இல்லையெனில், அதை வெளிப்படையாகச் சேர்க்கவும்." + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "MANIFEST.in" + +#: ../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 "" +"ப: கோப்பு: மூல விநியோகத்தில் தானாக சேர்க்கப்படாத கூடுதல் கோப்புகளை நீங்கள் தொகுக்க " +"வேண்டியிருக்கும் போது `மேனிஃபெச்ட்.இன்` தேவை. ஒரு: கோப்பு: `manifest.in` கோப்பு, " +"இயல்புநிலையாக சேர்க்கப்பட்டவற்றின் பட்டியல் உட்பட,\": ref: `Manifest.in`\" ஐப் " +"பயன்படுத்துதல் \"ஐப் பார்க்கவும்." + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" +"இருப்பினும், நீங்கள் ஒரு: கோப்பு: `manifest.in` ஐப் பயன்படுத்த வேண்டியதில்லை. " +"எடுத்துக்காட்டுக்கு, `பைபா மாதிரி திட்டம் ` " +"_ அதன் வெளிப்படையான கோப்பை நீக்கிவிட்டது, ஏனெனில் தேவையான அனைத்து கோப்புகளும் இவற்றில் " +"சேர்க்கப்பட்டுள்ளன: ref: `setuptools` 43.0.0 மற்றும் புதியது ." + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr ": கோப்பு: `manifest.in` சக்கரங்கள் போன்ற பைனரி விநியோகங்களை பாதிக்காது." + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "உரிமம்" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" +"ஒவ்வொரு தொகுப்பிலும் விநியோக விதிமுறைகளை விவரிக்கும் உரிமக் கோப்பு இருக்க வேண்டும். பல " +"அதிகார வரம்புகளில், வெளிப்படையான உரிமம் இல்லாத தொகுப்புகளை பதிப்புரிமைதாரரைத் தவிர " +"வேறு யாராலும் சட்டப்பூர்வமாக பயன்படுத்தவோ அல்லது விநியோகிக்கவோ முடியாது. எந்த உரிமத்தை " +"தேர்வு செய்வது என்று உங்களுக்குத் தெரியாவிட்டால், `கிட்அப் போன்ற ஆதாரங்களை நீங்கள் " +"பயன்படுத்தலாம் _ _ அல்லது ஒரு வழக்கறிஞரை அணுகவும்." + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" +"எடுத்துக்காட்டுக்கு, `பைபா மாதிரி திட்டத்திலிருந்து `_." + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "<உங்கள் தொகுப்பு>" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" +"இது தேவையில்லை என்றாலும், உங்கள் பைதான் தொகுதிகள் மற்றும் தொகுப்புகளை ஒரே ஒரு உயர் மட்ட " +"தொகுப்பின் கீழ் சேர்ப்பது மிகவும் பொதுவான நடைமுறை: ref: `பெயர் <அமைவு () பெயர்>` உங்கள் " +"திட்டமாக அல்லது மிக நெருக்கமான ஒன்று." + +#: ../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 "" +"எடுத்துக்காட்டுக்கு, `மாதிரி ` _ PYPA மாதிரி திட்டத்தில் சேர்க்கப்பட்டுள்ள தொகுப்பு `_." + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "அமைவு () ஆர்க்ச்" + +#: ../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 "" +"மேலே குறிப்பிட்டுள்ளபடி, இதன் முதன்மை அம்சம்: கோப்பு: `setup.py` என்னவென்றால், அதில் " +"உலகளாவிய` `அமைவு ()` `செயல்பாடு உள்ளது. இந்த செயல்பாட்டிற்கான முக்கிய வாதங்கள் உங்கள் " +"திட்டத்தின் குறிப்பிட்ட விவரங்கள் எவ்வாறு வரையறுக்கப்படுகின்றன என்பதுதான்." + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" +"சிலர் தங்கள் தகவல்கள் வேறு இடத்திற்கு நகர்த்தப்படும் வரை தற்காலிகமாக கீழே " +"விளக்கப்படுகிறார்கள். முழு பட்டியலையும் காணலாம்: டிஓசி: `செட்டுப்டூல்ச் ஆவணத்தில் " +"<செட்டுப்டூல்ச்: குறிப்புகள்/முக்கிய வார்த்தைகள்>`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" +"கொடுக்கப்பட்ட பெரும்பாலான துணுக்குகள் `setup.py _ " +"_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ com/pypa/salemProject> `_." + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" +"காண்க: குறிப்பு: `ஒரு பதிப்பு திட்டத்தைத் தேர்ந்தெடுப்பது` உங்கள் பயனர்களுக்கு " +"பொருந்தக்கூடிய தகவல்களை தெரிவிக்க பதிப்புகளைப் பயன்படுத்துவதற்கான வழிகள் பற்றிய கூடுதல் " +"தகவலுக்கு." + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "`` தொகுப்புகள்``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" +"எல்லாவற்றின் பட்டியலுக்கும் `` தொகுப்புகள்`` அமைக்கவும்: கால: `தொகுப்புகள் <இறக்குமதி " +"தொகுப்பு>`, உங்கள் திட்டத்தில், அவற்றின் துணைப் பேக்குகள், துணை துணைப்பிரிவுகள் போன்றவை " +"உட்பட. தொகுப்புகளை கைமுறையாக பட்டியலிட முடியும் என்றாலும், `` " +"setuptools.find_packages () `` அவற்றை தானாகவே கண்டுபிடிக்கும். கொடுக்கப்பட்ட " +"தொகுப்புகளை மட்டுமே கண்டுபிடிக்க `` `` முக்கிய வாதத்தை சேர்க்கவும். விடுவிக்கப்பட்டு " +"நிறுவப்பட விரும்பாத தொகுப்புகளைத் தவிர்க்க `` விலக்கு `முக்கிய வாதத்தைப் பயன்படுத்தவும்." + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +msgstr "`` py_modules``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:198 +msgid "" +"If your project contains any single-file Python modules that aren't part of " +"a package, set ``py_modules`` to a list of the names of the modules (minus " +"the ``.py`` extension) in order to make :ref:`setuptools` aware of them." +msgstr "" +"உங்கள் திட்டத்தில் ஏதேனும் ஒற்றை கோப்பு பைதான் தொகுதிகள் இருந்தால், ஒரு தொகுப்பின் " +"பகுதியாக இல்லாத ஏதேனும் ஒரு பைதான் தொகுதிகள் இருந்தால், `` py_modules`` ஐ " +"தொகுதிகளின் பெயர்களின் பட்டியலுக்கு அமைக்கவும் (`` .py`` நீட்டிப்பு) செய்ய: குறிப்பு: " +"`செட்ப்டூல்ச்` அவர்களைப் பற்றி அறிந்திருக்கிறார்." + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" +"ஒரு திட்டம் குறைந்தபட்சமாக இயங்க வேண்டிய சார்புகளைக் குறிப்பிட \"Install_requires\" " +"பயன்படுத்தப்பட வேண்டும். திட்டத்தை நிறுவும் போது: ref: `பிப்`, இது அதன் சார்புகளை நிறுவ " +"பயன்படும் விவரக்குறிப்பு." + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" +"\"Install_requires\" ஐப் பயன்படுத்துவது பற்றி மேலும் அறிய: ref: `install_requires " +"vs தேவைகள் கோப்புகள்`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "`` தொகுப்பு_டேட்டா``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" +"பெரும்பாலும், கூடுதல் கோப்புகள் ஒரு: கால: `தொகுப்பு <இறக்குமதி தொகுப்பு> இல் நிறுவப்பட " +"வேண்டும். இந்த கோப்புகள் பெரும்பாலும் தொகுப்பின் செயல்படுத்தலுடன் நெருக்கமாக தொடர்புடைய " +"தரவு அல்லது தொகுப்பைப் பயன்படுத்தி புரோகிராமர்களுக்கு ஆர்வமாக இருக்கும் ஆவணங்களைக் கொண்ட " +"உரை கோப்புகள். இந்த கோப்புகள் \"தொகுப்பு தரவு\" என்று அழைக்கப்படுகின்றன." + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" +"மதிப்பு தொகுப்பில் நகலெடுக்கப்பட வேண்டிய ஒப்பீட்டு பாதை பெயர்களின் பட்டியலுக்கு தொகுப்பு " +"பெயரிலிருந்து மேப்பிங் செய்ய வேண்டும். பாதைகள் தொகுப்பைக் கொண்ட கோப்பகத்துடன் " +"தொடர்புடையதாக விளக்கப்படுகின்றன." + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" +"மேலும் தகவலுக்கு, காண்க: எச்.டி.டி: டிஓசி: `தரவுக் கோப்புகள் <செட்டப்டூல்ச்: யு.எச்.இ." + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "`` data_files``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" +"உள்ளமைவு: ref: `தொகுப்பு தரவு` பெரும்பாலான தேவைகளுக்கு போதுமானது, சில " +"சந்தர்ப்பங்களில் நீங்கள் தரவுக் கோப்புகளை * வெளியே * வைக்க வேண்டியிருக்கலாம்: உங்கள்: கால:` " +"தொகுப்புகள் <இறக்குமதி தொகுப்பு> `. `` Data_files`` கட்டளை அதைச் செய்ய உங்களை " +"அனுமதிக்கிறது. பிற நிரல்களால் பயன்படுத்தப்படும் கோப்புகளை நீங்கள் நிறுவ வேண்டுமானால் இது " +"பெரும்பாலும் பயனுள்ளதாக இருக்கும், அவை பைதான் தொகுப்புகளைப் பற்றி அறியாமல் இருக்கலாம்." + +#: ../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 "" +"ஒவ்வொரு `` (அடைவு, கோப்புகள்) `` வரிசையில் உள்ள இணை நிறுவல் அடைவு மற்றும் அங்கு நிறுவ " +"வேண்டிய கோப்புகளைக் குறிப்பிடுகிறது. `` அடைவு`` ஒரு உறவினர் பாதையாக இருக்க வேண்டும் " +"(இது எதிர்காலத்தில் மாறக்கூடும் என்றாலும், `சக்கர சிக்கல் #92 _ _) ஐப் பார்க்கவும் நிறுவல் முன்னொட்டுடன் தொடர்புடையது (இயல்புநிலை " +"நிறுவலுக்காக பைதனின் `` sys.prefix``; `` site.user_base`` ஒரு பயனர் " +"நிறுவலுக்கு). `` கோப்புகள்`` இல் உள்ள ஒவ்வொரு கோப்பின் பெயரும் திட்ட மூல விநியோகத்தின் " +"மேலே: `setup.py` ச்கிரிப்டுடன் தொடர்புடையது." + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" +"மேலும் தகவலுக்கு, தொலைதூரப் பகுதியைப் பார்க்கவும்: ref: `கூடுதல் கோப்புகளை நிறுவுதல் " +"<செட்டப்டூல்ச்: டிச்டிடில்ச்-அட்ரிசனல்-ஃபைல்கள்>`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:274 +msgid "" +"When installing packages as egg, ``data_files`` is not supported. So, if " +"your project uses :ref:`setuptools`, you must use ``pip`` to install it. " +"Alternatively, if you must use ``python setup.py``, then you need to pass " +"the ``--old-and-unmanageable`` option." +msgstr "" +"தொகுப்புகளை முட்டையாக நிறுவும் போது, `` data_files`` ஆதரிக்கப்படவில்லை. எனவே, உங்கள் " +"திட்டம் பயன்படுத்தினால்: Ref: `setuptools`, அதை நிறுவ` `பிப்`` ஐப் பயன்படுத்த வேண்டும். " +"மாற்றாக, நீங்கள் `` பைதான் setup.py`` ஐப் பயன்படுத்த வேண்டும் என்றால், நீங்கள் `` --old-and-" +"unmanageable` விருப்பத்தை அனுப்ப வேண்டும்." + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" +"`` Setup () `` ஆதரிக்கிறது ஒரு: குறிப்பு: `ச்கிரிப்டுகள் <செட்டுப்லூல்கள்: டிச்ட்டில்ச்-" +"இன்ச்டாலிங்-ச்கிரிப்டுகள்>` நிறுவுவதற்கு முன்பே தயாரிக்கப்பட்ட ச்கிரிப்ட்களை " +"சுட்டிக்காட்டுவதற்கான முக்கிய சொல், குறுக்கு-தளம் பொருந்தக்கூடிய தன்மையை அடைய " +"பரிந்துரைக்கப்பட்ட அணுகுமுறை: புதுப்பிப்பு: புதுப்பிப்பு : `Console_scripts` நுழைவு " +"புள்ளிகள் (கீழே காண்க)." + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "பதிப்பு திட்டத்தைத் தேர்ந்தெடுப்பது" + +#: ../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 "" +"காண்க: குறிப்பு: பொதுவான பதிப்பு திட்டங்கள் மற்றும் அவற்றுக்கிடையே எவ்வாறு தேர்வு செய்வது " +"என்பது பற்றிய தகவல்களுக்கு `பதிப்பு." + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "\"மேம்பாட்டு பயன்முறையில்\" பணிபுரிதல்" + +#: ../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 "" +"நீங்கள் பணிபுரியும் போது ஒரு திட்டத்தை \"திருத்தக்கூடிய\" அல்லது \"உருவாக்கு\" " +"பயன்முறையில் நிறுவலாம். திருத்தக்கூடியதாக நிறுவப்பட்டால், ஒரு திட்டத்தை மீண்டும் நிறுவாமல் " +"இடத்திலேயே திருத்தலாம்: திருத்தக்கூடியதாக நிறுவப்பட்ட திட்டங்களில் பைதான் மூல கோப்புகளில் " +"மாற்றங்கள் அடுத்த முறை ஒரு மொழிபெயர்ப்பாளர் செயல்முறை தொடங்கப்படும் போது பிரதிபலிக்கும்." + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" +"ஒரு பைதான் தொகுப்பை \"திருத்தக்கூடிய\"/\"மேம்பாட்டு\" பயன்முறையில் திட்ட கோப்பகத்தின் " +"வேருக்கு கோப்பகத்தை மாற்றவும் இயக்கவும்:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" +"பிஐபி கட்டளை-வரி கொடி `` -e`` ``-பொருத்தமற்ற`` க்கு குறுகியது, மற்றும் " +"`` .` .` .`` இது தற்போதைய பணி கோப்பகத்தைக் குறிக்கிறது, எனவே ஒன்றாக, தற்போதைய " +"கோப்பகத்தை நிறுவுவதாகும் (அதாவது உங்கள் திட்டத்தை ) திருத்தக்கூடிய பயன்முறையில். இது `` " +"Install_requires`` உடன் அறிவிக்கப்பட்ட எந்தவொரு சார்புகளையும் நிறுவும் மற்றும் `` " +"கன்சோல்_ச்கிரிப்ட்ச்`` உடன் அறிவிக்கப்பட்ட எந்த ச்கிரிப்டுகளையும் நிறுவும். சார்புநிலைகள் " +"வழக்கமான, திருத்தப்படாத பயன்முறையில் நிறுவப்படும்." + +#: ../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::" +msgstr "" +"உங்கள் சார்புகளில் சிலவற்றை திருத்தக்கூடிய பயன்முறையிலும் நிறுவ விரும்பலாம். " +"எடுத்துக்காட்டாக, உங்கள் திட்டத்திற்கு \"ஃபூ\" மற்றும் \"பார்\" தேவை என்று கருதுகிறது, " +"ஆனால் பகஅ இலிருந்து திருத்தக்கூடிய பயன்முறையில் நிறுவப்பட்ட \"பார்\" வேண்டும் என்று நீங்கள் " +"விரும்புகிறீர்கள், பின்னர் நீங்கள் ஒரு தேவைகள் கோப்பை உருவாக்கலாம் ::" + +#: ../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 "" +"உங்கள் திட்டத்தையும் எந்தவொரு சார்புகளையும் நிறுவ முதல் வரி கூறுகிறது. இரண்டாவது வரி " +"\"பார்\" சார்புநிலையை மீறுகிறது, இது வி.சி.க்களிலிருந்து நிறைவேறும், இது பைபி அல்ல." + +#: ../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 "" +"எவ்வாறாயினும், திருத்தக்கூடிய பயன்முறையில் ஒரு உள்ளக கோப்பகத்திலிருந்து நிறுவப்பட்ட " +"\"பார்\" விரும்பினால், தேவைகள் கோப்பு இப்படி இருக்க வேண்டும், கோப்பின் மேலே உள்ள உள்ளக " +"பாதைகள் ::" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" +"இல்லையெனில், தேவைகள் கோப்பின் நிறுவல் வரிசை காரணமாக, சார்பு பைபியிலிருந்து " +"நிறைவேற்றப்படும். தேவைகள் கோப்புகளைப் பற்றி மேலும் அறிய, பார்க்க: ref: `தேவைகள் கோப்பு " +"` PIP டாக்சில் பிரிவு. வி.சி.எச் நிறுவல்களைப் பற்றி மேலும் " +"அறிய, இதைக் காண்க: குறிப்பு: `வி.சி.எச் உதவி <பிஐபி: வி.சி.எச் ஆதரவு>` பிஐபி " +"டாக்சின் பிரிவு." + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "கடைசியாக, நீங்கள் எந்த சார்புகளையும் நிறுவ விரும்பவில்லை என்றால், நீங்கள் இயக்கலாம்:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" +"மேலும் தகவலுக்கு,: DOC: `மேம்பாட்டு முறை <செட்டப்டூல்ச்: userguide/" +"development_mode>` பிரிவு: ref: `setuptools` டாக்சைப் பார்க்கவும்." + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "உங்கள் திட்டத்தை பேக்கேசிங் செய்தல்" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" +"உங்கள் திட்டத்தை ஒரு: கால: `தொகுப்பு குறியீட்டு` போன்றவற்றிலிருந்து நிறுவ முடியும்: " +"கால:` பைபி <பைதான் தொகுப்பு குறியீட்டு (பைபி)> `, நீங்கள் ஒரு: காலத்தை உருவாக்க " +"வேண்டும்:` விநியோக <விநியோக தொகுப்பு> `(அக்கா\" : கால: `தொகுப்பு <விநியோக " +"தொகுப்பு>` \") உங்கள் திட்டத்திற்கு." + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" +"உங்கள் திட்டத்திற்காக சக்கரங்கள் மற்றும் SDIST களை உருவாக்குவதற்கு முன், நீங்கள் `` பில்ட்`` " +"தொகுப்பை நிறுவ வேண்டும்:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "மூல வழங்கல்" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" +"குறைந்தபட்சமாக, நீங்கள் ஒரு: காலத்தை உருவாக்க வேண்டும்: `மூல வழங்கல் <மூல வழங்கல் " +"(அல்லது\" SDIST \")>`:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" +"ஒரு \"மூல வழங்கல்\" கட்டமைக்கப்படாதது (அதாவது இது ஒரு: கால: `கட்டப்பட்ட விநியோகம்`), " +"மேலும் பிஐபி நிறுவும் போது ஒரு கட்டம் படி தேவைப்படுகிறது. வழங்கல் தூய பைத்தான் " +"என்றாலும் (அதாவது நீட்டிப்புகள் எதுவும் இல்லை), நிறுவல் மெட்டாடேட்டாவை உருவாக்குவதற்கான " +"கட்டமைப்பை இது இன்னும் உள்ளடக்கியது: கோப்பு: `setup.py` மற்றும்/அல்லது: கோப்பு:` " +"setup.cfg`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "சக்கரங்கள்" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" +"உங்கள் திட்டத்திற்கு ஒரு சக்கரத்தையும் உருவாக்க வேண்டும். ஒரு சக்கரம் ஒரு: சொல்: `கட்டப்பட்ட " +"தொகுப்பு <கட்டப்பட்ட விநியோகம்>` இது \"உருவாக்க\" செயல்முறையின் வழியாக செல்ல வேண்டிய " +"அவசியமின்றி நிறுவப்படலாம். மூல விநியோகத்திலிருந்து நிறுவுவதை விட சக்கரங்களை " +"நிறுவுவது இறுதி பயனருக்கு கணிசமாக வேகமாக இருக்கும்." + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" +"உங்கள் திட்டம் தூய பைதான் என்றால், நீங்கள் ஒரு: ref: `\" தூய பைதான் சக்கரம் \"(கீழே உள்ள " +"பகுதியைக் காண்க) <தூய பைதான் சக்கரங்கள்>` உருவாக்குவீர்கள்." + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" +"உங்கள் திட்டத்தில் தொகுக்கப்பட்ட நீட்டிப்புகள் இருந்தால், நீங்கள் A: ref: `* இயங்குதள சக்கரம்* " +"(கீழே உள்ள பகுதியைப் பார்க்கவும்) <இயங்குதள சக்கரங்கள்>` என்று அழைக்கப்படுவதை " +"உருவாக்குவீர்கள்." + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" +"உங்கள் திட்டம் பைதான் 2 * ஐ ஆதரிக்கிறது மற்றும் * சி நீட்டிப்புகளைக் கொண்டிருக்கவில்லை " +"என்றால், உங்கள்: கோப்பு: `setup.cfg` கோப்பு: பின்வருவனவற்றைச் சேர்ப்பதன் மூலம் * யுனிவர்சல் " +"வீல் * என்று அழைக்கப்படுவதை உருவாக்க வேண்டும்:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" +"உங்கள் திட்டத்திற்கு சி நீட்டிப்புகள் இல்லை என்றால் மட்டுமே இந்த அமைப்பைப் பயன்படுத்தவும் * " +"மற்றும் * பைதான் 2 மற்றும் 3 ஐ ஆதரிக்கிறது." + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "தூய பைதான் சக்கரங்கள்" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" +"* தூய பைதான் சக்கரங்கள்* தொகுக்கப்பட்ட நீட்டிப்புகளைக் கொண்டிருக்கவில்லை, எனவே ஒரு பைதான் " +"சக்கரம் மட்டுமே தேவைப்படுகிறது." + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "சக்கரத்தை உருவாக்க:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" +"`` சக்கரம்`` தொகுப்பு குறியீடு தூய பைதான் என்பதைக் கண்டறிந்து, எந்த பைதான் 3 நிறுவலிலும் " +"பயன்படுத்தக்கூடியதாக பெயரிடப்பட்ட ஒரு சக்கரத்தை உருவாக்குகிறது. சக்கர கோப்புகளின் " +"பெயரிடுதல் குறித்த விவரங்களுக்கு, காண்க: PEP: `425`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" +"``-வீல்` அல்லது ``--ச்டிச்ட்` இல்லாமல் `` பில்ட்`` ஐ இயக்கினால், அது உங்களுக்காக இரண்டு " +"கோப்புகளையும் உருவாக்கும்; உங்களுக்கு பல சக்கரங்கள் தேவையில்லை போது இது பயனுள்ளதாக " +"இருக்கும்." + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "இயங்குதள சக்கரங்கள்" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" +"* இயங்குதள சக்கரங்கள்* என்பது லினக்ச், மேகோச் அல்லது சாளரங்கள் போன்ற ஒரு குறிப்பிட்ட " +"தளத்திற்கு குறிப்பிட்ட சக்கரங்கள், பொதுவாக தொகுக்கப்பட்ட நீட்டிப்புகளைக் கொண்டிருப்பதால்." + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" +"`` சக்கரம்`` தொகுப்பு குறியீடு தூய பைதான் அல்ல என்பதைக் கண்டறிந்து, அது கட்டப்பட்ட " +"மேடையில் மட்டுமே பயன்படுத்தக்கூடியது என்று பெயரிடப்பட்ட ஒரு சக்கரத்தை உருவாக்குங்கள். " +"சக்கர கோப்புகளின் பெயரிடுதல் குறித்த விவரங்களுக்கு, காண்க: PEP: `425`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr ". பிந்தைய விவரங்கள் வரையறுக்கப்பட்டுள்ளன: PEP: `513`." + +#: ../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 "" +"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 "" +"உங்கள் விநியோகத்தை உருவாக்க நீங்கள் கட்டளையை இயக்கும்போது, உங்கள் திட்டத்தின் ரூட் கோப்பகத்தின் " +"கீழ் `` DIST/`` ஒரு புதிய அடைவு உருவாக்கப்பட்டது. பதிவேற்ற உங்கள் விநியோக கோப்பு " +"(களை) காண்பீர்கள்." + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" +"உங்கள் விநியோகத்தை உருவாக்க கட்டளையை இயக்கும்போது மட்டுமே இந்த கோப்புகள் " +"உருவாக்கப்படுகின்றன. இதன் பொருள் என்னவென்றால், உங்கள் திட்டத்தின் மூலத்தையோ அல்லது உங்கள்: " +"கோப்பு: `setup.py` கோப்பிலோ எந்த நேரத்திலும் நீங்கள் மாற்றும்போது, நீங்கள் பைபிக்கு " +"மாற்றங்களை விநியோகிப்பதற்கு முன்பு இந்த கோப்புகளை மீண்டும் கட்டியெழுப்ப வேண்டும்." + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" +"மெயின் பைபி ரெப்போவில் வெளியிடுவதற்கு முன், நீங்கள் `PYPI சோதனை தளத்துடன் பயிற்சியை " +"விரும்பலாம் ` _ இது அரை வழக்கமான அடிப்படையில் தூய்மை " +"செய்யப்படுகிறது. காண்க: குறிப்பு: `உங்கள் உள்ளமைவைப் பயன்படுத்துவதற்காக அதை எவ்வாறு " +"அமைப்பது என்பது குறித்து-டெச்ட்-பைபியைப் பயன்படுத்துதல்." + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" +"பிற ஆதாரங்களில் `` பைதான் செட்அப். ஒரு தொகுப்பை பதிவுசெய்தல் மற்றும் பதிவேற்றுவதற்கான " +"இந்த முறைகள் ** சில பைதான் பதிப்புகளில் ஒரு எளிய உரை HTTP அல்லது சரிபார்க்கப்படாத " +"HTTPS இணைப்பைப் பயன்படுத்துவதால், உங்கள் பயனர்பெயர் மற்றும் கடவுச்சொல்லை பரிமாற்றத்தின் போது " +"தடுத்து நிறுத்த அனுமதிக்கிறது." + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" +"PYPI இல் பயன்படுத்தப்படும் மறுசீரமைப்பு டெக்ச்ட் பாகுபடுத்தி ** அல்ல ** sphinx! மேலும், " +"அனைத்து பயனர்களின் பாதுகாப்பையும் உறுதிப்படுத்த, சில வகையான முகவரி கள் மற்றும் " +"வழிமுறைகள் தடைசெய்யப்பட்டுள்ளன அல்லது அகற்றப்படுகின்றன (எ.கா., `` .. மூல :: `` " +"உத்தரவு). ** முன் ** உங்கள் விநியோகத்தை பதிவேற்ற முயற்சிக்கும் முன், உங்கள் சுருக்கமான / " +"நீண்ட விளக்கங்கள் வழங்கப்பட்டதா என்பதை நீங்கள் சரிபார்க்க வேண்டும்: கோப்பு: `setup.py` " +"செல்லுபடியாகும். இயங்குவதன் மூலம் இதைச் செய்யலாம்: எச்.டி.டி: டிஓசி: `உங்கள் தொகுப்பு " +"கோப்புகளில்` ட்வைன் செக் <குறியீட்டு> `:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "ஒரு கணக்கை உருவாக்கவும்" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" +"முதலில், உங்களுக்கு ஒரு: சொல் தேவை: `பைபி <பைதான் தொகுப்பு அட்டவணை (பைபி)>` பயனர் " +"கணக்கு. PYPI வலைத்தளமான _ _ இல் படிவத்தைப் " +"பயன்படுத்தி ஒரு கணக்கை உருவாக்கலாம்." + +#: ../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 "" +"இப்போது நீங்கள் ஒரு பைபி `ஏபிஐ டோக்கன்`_ ஐ உருவாக்குவீர்கள், எனவே உங்கள் திட்டத்தை " +"பாதுகாப்பாக பதிவேற்ற முடியும்." + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" +"Https://pypi.org/manage/account/#api-tokens க்குச் சென்று புதிய `API டோக்கன்`_ ஐ " +"உருவாக்கவும்; நீங்கள் ஒரு புதிய திட்டத்தை உருவாக்குவதால், ஒரு குறிப்பிட்ட திட்டத்திற்கு " +"அதன் நோக்கத்தை மட்டுப்படுத்த வேண்டாம்." + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" +"** நீங்கள் கிள்ளாக்கை நகலெடுத்து சேமிக்கும் வரை பக்கத்தை மூட வேண்டாம் - அந்த கிள்ளாக்கை " +"நீங்கள் மீண்டும் பார்க்க மாட்டீர்கள். **" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" +"நீங்கள் பதிவேற்றும் ஒவ்வொரு முறையும் கிள்ளாக்கை நகலெடுத்து ஒட்ட வேண்டும் என்பதைத் தவிர்க்க, " +"நீங்கள் ஒரு: கோப்பு: `$ home/.pypirc` கோப்பு:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" +"மேலும் விவரங்களுக்கு, இதைக் காண்க: ref: `விவரக்குறிப்பு ` க்கு: கோப்பு: " +"`.பைர்க்`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "உங்கள் விநியோகங்களை பதிவேற்றவும்" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" +"உங்களிடம் ஒரு கணக்கு கிடைத்ததும் உங்கள் விநியோகங்களை பதிவேற்றலாம்: கால: `பைபி <பைதான் " +"தொகுப்பு குறியீட்டு (பைபி)>` பயன்படுத்துதல்: குறிப்பு: `ட்வைன்`." + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" +"ஒரு வெளியீட்டைப் பதிவேற்றுவதற்கான செயல்முறை PYPI இல் ஏற்கனவே உள்ளதா இல்லையா என்பதைப் " +"பொருட்படுத்தாமல் - அது இன்னும் இல்லை என்றால், முதல் வெளியீடு பதிவேற்றப்படும்போது அது " +"தானாகவே உருவாக்கப்படும்." + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" +"இரண்டாவது மற்றும் அடுத்தடுத்த வெளியீடுகளுக்கு, புதிய வெளியீட்டின் பதிப்பு எண் முந்தைய " +"வெளியீடுகளிலிருந்து வேறுபட வேண்டும் என்று PYPI தேவைப்படுகிறது." + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" +"`` Https://pypi.org/project/ `` `` `shampeproject`` என்பது " +"நீங்கள் பதிவேற்றிய உங்கள் திட்டத்தின் பெயர். உங்கள் திட்டம் தளத்தில் தோன்றுவதற்கு ஒரு மணித்துளி " +"அல்லது இரண்டு நேரம் ஆகலாம்." + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "உங்கள் தளத்தைப் பொறுத்து, இதற்கு ரூட் அல்லது நிர்வாகி அணுகல் தேவைப்படலாம். ." + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "பழைய பைதான் பதிப்புகளுக்கான ஆதரவை கைவிடுதல்" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" +"பழைய பைதான் பதிப்புகளுக்கான ஆதரவை கைவிடுவதற்கான திறன் தரநிலையால் இயக்கப்பட்டது: " +"குறிப்பு: `கோர்-மெட்டாடேட்டா` 1.2 விவரக்குறிப்பு வழியாக: ref:` \"-பைதான் தேவை\" " +"<கோர்-மெட்டாடேட்டா-வேண்டுகோள்-பைதான்> `பண்புக்கூறு." + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 போன்ற மேனிலை தரவு 1.2+ நிறுவிகள், தற்போதைய பைதான் இயக்க நேரத்துடன் பொருந்துவதன் " +"மூலமும், தொகுப்பு மெட்டாடேட்டாவில் தேவையான பதிப்போடு ஒப்பிடுவதன் மூலமும் இந்த " +"விவரக்குறிப்பைக் கடைப்பிடிக்கும். அவை பொருந்தவில்லை என்றால், அந்த பைதான் இயக்க நேரத்தை " +"ஆதரிக்கும் கடைசி தொகுப்பு விநியோகத்தை நிறுவ முயற்சிக்கும்." + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" +"பழைய பைதான் பதிப்புகளுக்கான ஆதரவை கைவிட இந்த வழிமுறை பயன்படுத்தப்படலாம், தொகுப்பு " +"மெட்டாடேட்டாவில் ``-பைதான் `பண்புக்கூறு தேவைகள்." + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "தேவைகள்" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" +"தொகுப்பை நிறுவும் பயனர் பிஐபி [#] _ அல்லது மேனிலை தரவு 1.2 விவரக்குறிப்பை ஆதரிக்கும் " +"மற்றொரு நிறுவியைப் பயன்படுத்த வேண்டும்." + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "உலகளாவிய சக்கரங்களுடன் கையாள்வது" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" +"பாரம்பரியமாக, குறிப்பு: பைதான் 2 மற்றும் பைதான் 3 ஆகிய இரண்டிலும் சொற்பொருளாக இணக்கமான " +"பைதான் குறியீட்டை வழங்கும் `செட்ப்டூல்ச்` திட்டங்கள், உற்பத்தி: கால: `சக்கரங்கள் <சக்கர>` " +"அவற்றின் பெயர்களில் `` py2.py3`` குறிச்சொல்லைக் கொண்டுள்ளன. பைதான் 2 க்கான ஆதரவை " +"கைவிடும்போது, இந்த குறிச்சொல்லை `` py3`` ஆக மாற்ற மறக்காமல் இருப்பது முதன்மை. இது " +"பெரும்பாலும் உள்ளே கட்டமைக்கப்பட்டுள்ளது: கோப்பு: `` [bdist_wheel] `` பிரிவின் கீழ் `` " +"`யுனிவர்சல் = 1``." + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" +"இந்த முறையைப் பயன்படுத்தினால், இந்த விருப்பம் அல்லது பகுதியை அகற்று, அல்லது வெளிப்படையாக " +"`` யுனிவர்சல்`` ஐ `0`` என அமைக்கவும்:" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" +"தொடர்புடையது: குறிப்பு: `நீக்கப்பட்ட ` நேரடி `` setup.py`` " +"அழைப்பிதழ்கள், கட்டளை வரியில் `` --niversal`` கொடியைக் கடந்து செல்வது இந்த அமைப்பை " +"மீறக்கூடும்." + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "தேவையான பைதான் பதிப்பை வரையறுத்தல்" + +#: ../source/guides/dropping-older-python-versions.rst:48 +msgid "1. Install twine" +msgstr "1. கயிறு நிறுவவும்" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" +"அதன் அண்மைக் கால பதிப்பில் உங்களிடம் கயிறு கிடைக்கிறது என்பதை உறுதிப்படுத்தவும். படிகள்:" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "2. ஆதரிக்கப்பட்ட பைதான் விநியோகங்களுக்கான பதிப்பு வரம்புகளைக் குறிப்பிடவும்" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" +"உங்கள் திட்டத்திற்குள் எந்த பைதான் விநியோகங்கள் ஆதரிக்கப்படுகின்றன என்பதை அறிவிக்கும் பதிப்பு " +"வரம்புகளை அமைக்கவும்: கோப்பு: `pyproject.toml`. தி: ரெஃப்: `-பைதான் தேவை. உள்ளமைவு " +"புலம் இதற்கு ஒத்திருக்கிறது: ref:`-பைதான் தேவை <கோர்-மெட்டாடேட்டா-வேண்டுகோள்-பைதான்> " +"`கோர் மேனிலை தரவு புலம்:" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" +"குறைந்தபட்சம் பைதான் 3.9 போன்ற பதிப்பு வரம்புகள் மற்றும் விலக்கு விதிகளை நீங்கள் " +"குறிப்பிடலாம் (குறிப்பு: re: `பதிப்பு-விவரிப்பாளர்கள்` விவரக்குறிப்பு). அல்லது, " +"குறைந்தபட்சம் பைதான் 3.7 மற்றும் அதற்கு அப்பால், 3.7.0 மற்றும் 3.7.1 புள்ளி வெளியீடுகளைத் " +"தவிர்த்து:" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" +"பயன்படுத்தினால்: ref: `setuptools` பின்தளத்தில் உருவாக்குங்கள், மேலும் விருப்பங்களுக்கு` " +"சார்பு-மேலாண்மை`_ ஆவணங்களை அணுகவும்." + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" +"பதிப்பு வரம்புகளுக்கு மேல் எல்லையைச் சேர்ப்பதைத் தவிர்க்கவும், இ. g. `` \"> = 3.8, " +"<3.10\" ``. அவ்வாறு செய்வது வெவ்வேறு பிழைகள் மற்றும் பதிப்பு மோதல்களை ஏற்படுத்தும். " +"மேலும் தகவலுக்கு `சொற்பொழிவு-விவாதத்தை`_ ஐப் பார்க்கவும்." + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "3. வெளியீட்டிற்கு முன் மெட்டாடேட்டாவை சரிபார்க்கிறது" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" +"பைதான் மூல தொகுப்புக்குள் (நீங்கள் பதிவிறக்கும் சிப் அல்லது தார்-சிஇசட் கோப்பு) என்பது " +"பி.கே.சி-இன்ஃபோ எனப்படும் உரை கோப்பு." + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` 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 "" +"இந்த கோப்பு உருவாக்கப்படுகிறது: கால: `பின்தளத்தில் உருவாக்கு <பின்தளத்தில் உருவாக்கு>` " +"இது மூல தொகுப்பை உருவாக்கும் போது. கோப்பில் விசைகள் மற்றும் மதிப்புகள் உள்ளன, விசைகளின் " +"பட்டியல் PYPA நிலையான மேனிலை தரவு வடிவமைப்பின் ஒரு பகுதியாகும்." + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "இது போன்ற உருவாக்கப்பட்ட கோப்பின் உள்ளடக்கங்களை நீங்கள் காணலாம்:" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "தொகுப்பை வெளியிடுவதற்கு முன்பு பின்வருபவை உள்ளன என்பதை சரிபார்க்கவும்:" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" +"நீங்கள் சரியாக மேம்படுத்தப்பட்டிருந்தால், `` மெட்டாடேட்டா-பதிப்பு`` மதிப்பு 1.2 அல்லது " +"அதற்கு மேற்பட்டதாக இருக்க வேண்டும்." + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" +"`` தேவைப்படுகிறது-பைதான்` `புலம் அமைக்கப்பட்டு, உங்கள் விவரக்குறிப்பை உள்ளமைவு கோப்பில் " +"பொருத்துகிறது." + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "4. தொகுப்பை வெளியிடுதல்" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "பரிந்துரைத்தபடி தொடரவும்: ref: `உங்கள் திட்டத்தை பைபிக்கு பதிவேற்றுதல்`." + +#: ../source/guides/dropping-older-python-versions.rst:120 +msgid "Dropping a Python version" +msgstr "பைதான் பதிப்பை கைவிடுதல்" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" +"கொள்கையளவில், பைதான் பதிப்புகளுக்கான குறைந்தபட்சம் மேனிலை தரவு ஆதரவை முடிந்தவரை வைக்க " +"வேண்டும், ஏனென்றால் அது கைவிடப்பட்டவுடன், ஒரு பதிப்பைப் பொறுத்து மக்கள் இன்னும் தரமிறக்க " +"வேண்டிய கட்டாயத்தில் இருப்பார்கள். இருப்பினும் ஒரு குறிப்பிட்ட பதிப்பை ஆதரிப்பது ஒரு " +"புதிய அம்சத்திற்கான தடுப்பாளராக மாறினால் அல்லது பிற சிக்கல்கள் ஏற்பட்டால், மேனிலை தரவு " +"`` தேவைப்படுகிறது-பைதான்` `திருத்தம் செய்யப்பட வேண்டும். நிச்சயமாக இது ஒரு பரந்த " +"அளவிலான பயனர்களுக்கு இந்த திட்டம் நிலையானதாகவும் நன்கு மூடப்பட்டதாகவும் இருக்க வேண்டுமா " +"என்பதையும் பொறுத்தது." + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" +"ஒவ்வொரு பதிப்பு பொருந்தக்கூடிய மாற்றமும் அதன் சொந்த வெளியீட்டைக் கொண்டிருக்க வேண்டும்." + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" +"பைதான் பதிப்பைக் கைவிடும்போது, புலப்படும் இடங்களில் (சோதனைச் சூழல் போன்றவை) " +"பயன்படுத்தப்படும் பதிப்புகளைப் புதுப்பிப்பதைத் தவிர, திட்டத்தின் குறியீடு தொடரியல் பொதுவாக " +"மேம்படுத்தவும் இது பலனளிக்கும். Pyupgrade_ அல்லது `Ruff _ _ இந்த வேலைகளில் சிலவற்றை தானியக்கமாக்கலாம்." + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "மேனிலை தரவு 1.2 விவரக்குறிப்புக்கான உதவி PIP 9.0 இல் சேர்க்கப்பட்டுள்ளது." + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "உங்கள் சொந்த எளிய களஞ்சியத்தை புரவலன் செய்தல்" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" +"உங்கள் சொந்த எளிய களஞ்சியத்தை புரவலன் செய்ய விரும்பினால் [1] _, நீங்கள் போன்ற ஒரு " +"மென்பொருள் தொகுப்பைப் பயன்படுத்தலாம்: டாக்: `டெவிபி <டெவிபிஐ: குறியீட்டு>` அல்லது " +"சரியான அடைவு கட்டமைப்பை உருவாக்கி பணி செய்யக்கூடிய எந்த வலை சேவையகத்தையும் " +"பயன்படுத்தலாம் நிலையான கோப்புகள் மற்றும் ஒரு ஆட்டோஇண்டெக்சை உருவாக்குகின்றன." + +#: ../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:" +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." +msgstr "" +"கூடுதலாக, செல்லுபடியாகும் HTTPS உடன் உங்கள் களஞ்சியத்தை வழங்க நீங்கள் ** மிகவும் ** " +"பரிந்துரைக்கப்படுகிறது. இந்த நேரத்தில், உங்கள் பயனரின் நிறுவல்களின் பாதுகாப்பு " +"செல்லுபடியாகும் HTTPS அமைப்பைப் பயன்படுத்தி அனைத்து களஞ்சியங்களையும் சார்ந்துள்ளது." + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "\"கையேடு\" களஞ்சியம்" + +#: ../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: " +"`இயல்பாக்கப்பட்ட பெயர் <பெயர்-இயல்பாக்கம்>` திட்டத்தின். இந்த ஒவ்வொரு கோப்பகத்திலும் தரவிறக்கம் " +"செய்யக்கூடிய ஒவ்வொரு கோப்புகளையும் வைக்கவும். உங்களிடம் \"ஃபூ\" (பதிப்புகள் 1.0 மற்றும் " +"2.0) மற்றும் \"பார்\" (பதிப்பு 0.1 உடன்) திட்டங்கள் இருந்தால், நீங்கள் ஒரு கட்டமைப்போடு " +"முடிவடையும் ::" + +#: ../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 "" +"இந்த தளவமைப்பை நீங்கள் பெற்றவுடன், ஆட்டோஇண்டெக்ச் இயக்கப்பட்ட ரூட் கோப்பகத்தை வழங்க உங்கள் " +"வெப்சர்வரை உள்ளமைக்கவும். `ட்விச்டட்`_ இல் உள்ள கட்டமைக்கப்பட்ட வலை சேவையகத்தைப் " +"பயன்படுத்துவதற்கு, நீங்கள்` `ட்விச்ட்ட் -என் வலை -பாதையை இயக்குவீர்கள் .`` பின்னர் பயனர்கள் " +"தங்கள் நிறுவியின் உள்ளமைவில் முகவரி ஐ சேர்க்க அறிவுறுத்துங்கள்." + +#: ../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 "பைபி வீழ்ச்சி-த்ரூ [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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "பரம்பரை கொண்ட பல குறியீடுகள், ஒத்திசைவு, பிரதி, தோல்வி; பிரதிபலிப்பு" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr ": Ref: `SimpleIndex`" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr ": குறிப்பு: `பைபிசெவர்`" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr ": ref: `pypiprivate`" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr ": Ref: `Pypicloud`" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "மதிப்பிடப்படாதது; தற்காலிகமாக தற்காலிகமாக சேமிக்கப்பட்டது; ஏற்பு, ஏற்பு" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr ": ref: `pywharf`" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "மதிப்பிடப்படாதது; கிதுபில் கோப்புகளை பரிமாறவும்" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr ": சிவப்பு: `கூழ் பைதான்`" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "பிரதிபலிக்கும், ப்ராக்சிங்; கூழ் சொருகி" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr ": ref: `Pip2pi`" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "மேலும் பிரதிபலிக்கும்; கையேடு ஒத்திசைவு" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr ": குறிப்பு: `டம்ப்-பைபி`" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "ஒரு சேவையகம் அல்ல, ஆனால் நிலையான கோப்பு தள செனரேட்டர்" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr ": குறிப்பு: `httpserver`" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "நிலையான-நூலகம்" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "`அப்பாச்சி ` _" + +#: ../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 "" +"using `mod_rewrite `_ and `mod_cache_disk `_, அப்பாச்சி சேவையகம் மூலம் குறியீடுகளை தொகுப்பு " +"குறியீடுகளுக்கு கேச் செய்யலாம்" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" +"எளிய களஞ்சிய நெறிமுறையின் முழுமையான ஆவணங்களுக்கு, காண்க: குறிப்பு: `எளிய களஞ்சிய " +"பநிஇ <எளிய-ரோபோசிட்டரி-ஏபிஐ>`." + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" +"கோரப்பட்ட தொகுப்பு காணவில்லை எனில், PYPI (அல்லது மற்றொரு தொகுப்பு குறியீட்டு) க்கு " +"திரும்புவதற்கு கட்டமைக்க முடியும்." + +#: ../source/guides/index.rst:4 +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`." +msgstr "" +"** வழிகாட்டிகள் ** ஒரு குறிப்பிட்ட பணியை நிறைவேற்றுவதில் கவனம் செலுத்துகின்றன, மேலும் " +"பைதான் பேக்கேசிங்கின் அடிப்படைகளை நீங்கள் ஏற்கனவே அறிந்திருக்கிறீர்கள் என்று கருதுகிறீர்கள். " +"நீங்கள் பேக்கேசிங்கிற்கான அறிமுகத்தைத் தேடுகிறீர்களானால், காண்க: டாக்: `/டுடோரியல்கள்/" +"குறியீட்டு`." + +#: ../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-08" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" +"PYPI இன் பிரதிபலிப்பு அல்லது தற்காலிக சேமிப்பு (மற்றும் பிற: கால: `தொகுப்பு " +"குறியீடுகள் <தொகுப்பு குறியீட்டு>`) உள்ளக தொகுப்பு நிறுவலை விரைவுபடுத்தவும், " +"இணைப்பில்லாத வேலையை அனுமதிக்கவும், கார்ப்பரேட் ஃபயர்வால்களைக் கையாளவும் அல்லது வெற்று " +"இணையத் துடிப்பு ஆகியவற்றைப் பயன்படுத்தவும் பயன்படுத்தப்படலாம்." + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "இந்த பகுதியில் பல வகை விருப்பங்கள் உள்ளன:" + +#: ../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 "" +"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/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 "பிப் உடன் தேக்ககிருத்தல்" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" +"உள்ளக தற்காலிக சேமிப்பு நகல்களைப் பயன்படுத்துவதன் மூலம் நிறுவலை விரைவுபடுத்துவதற்கு " +"பிஐபி பல வசதிகளை வழங்குகிறது: கால: `தொகுப்புகள் <விநியோக தொகுப்பு>`:" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" +":ref:`Fast & local installs ` by " +"downloading அனைத்தும் the requirements க்கு a திட்டம் and then pointing pip at " +"those downloaded கோப்புகள் instead of going பெறுநர் PyPI." + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" +"பயன்படுத்தும் தேவைகளுக்காக நிறுவல் கோப்புகளை முன்பே கட்டியெழுப்பும் மேலே உள்ள மாறுபாடு: " +"குறிப்பு: `பைதான் 3 -எம் பிப் வீல் <பிப்: பிப் வீல்>`:" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "கேச்" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "பரம்பரை கொண்ட பல குறியீடுகள்; ஒத்திசைவு, பிரதி, தோல்வி; தொகுப்பு பதிவேற்றம்" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr ": ref: `bandersnatch`" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" +"தனிப்பயன் சொருகி தற்காலிக சேமிப்பை செயல்படுத்துகிறது; பிற தொகுப்பு குறியீடுகளுக்கு " +"மீண்டும் திசை திருப்புதல்" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "மதிப்பிடப்படாதது; ஏற்பு, ஏற்பு" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "கூழ் சொருகி; பல ப்ராக்சிட் குறியீடுகள்; தொகுப்பு பதிவேற்றம்" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr ": குறிப்பு: `ப்ராக்ச்பி`" + +#: ../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 ": குறிப்பு: `nginx_pypi_cache`" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr ": குறிப்பு: `பிளாச்க்பிபிப்ராக்சி`" + +#: ../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 "" +"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 "" +"விஞ்ஞான மென்பொருள் பெரும்பாலானவற்றை விட மிகவும் சிக்கலான சார்புகளைக் கொண்டிருக்கிறது, " +"மேலும் இது பல்வேறு வகையான வன்பொருள்களைப் பயன்படுத்த பல கட்டுமான விருப்பங்களைக் " +"கொண்டிருக்கும், அல்லது வெளிப்புற மென்பொருளின் வெவ்வேறு துண்டுகளுடன் செயல்படுகிறது." + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" +"குறிப்பாக, `numpy ` __, இது `அறிவியல் பைதான் அடுக்கில் " +" _ _ _ வெவ்வேறு ஃபோர்டிரான் நூலகங்களுடன் " +"ஒன்றிணைந்து, நவீன சிபியு களில் கிடைக்கும் வெவ்வேறு நிலைகளில் திசையன் வழிமுறைகளைப் " +"பயன்படுத்திக் கொள்ளலாம்." + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" +"`` வீல்`` வடிவத்தில் முன்பே கட்டப்பட்ட 32-பிட் மற்றும் 64-பிட் பைனரிகள் அனைத்து முக்கிய " +"இயக்க முறைமைகளுக்கும் (விண்டோச், மேகோச் மற்றும் லினக்ச்) கிடைக்கின்றன பைபியில். " +"இருப்பினும், சாளரங்களில், நம்பி பைனரிகள் `அட்லச் __ __ பிளாச்/லேபாக் நூலகம், எச்எச்இ 2 வழிமுறைகளுக்கு கட்டுப்படுத்தப்பட்டுள்ளன, எனவே " +"அவை உகந்த நேரியல் இயற்கணிதத்தை வழங்காது செயல்திறன்." + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" +"விஞ்ஞான பைதான் நூலகங்களைப் பெறுவதற்கு பல மாற்று விருப்பங்கள் உள்ளன (அல்லது " +"மூலத்திலிருந்து நிறுவ ஒரு தொகுப்பு சூழல் தேவைப்படும் மற்றும் பைபியில் முன்பே கட்டப்பட்ட " +"சக்கர கோப்புகளை வழங்காத வேறு எந்த பைதான் நூலகங்களும்)." + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "மூலத்திலிருந்து கட்டிடம்" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" +"சக்கரக் கோப்புகள் என நம்பியை (மற்றும் அதைச் சார்ந்து இருக்கும் பல திட்டங்களை) விநியோகிப்பது " +"கடினமாக்கும் அதே சிக்கலானது, மூலத்திலிருந்து உங்களை உருவாக்குவது கடினம். " +"எவ்வாறாயினும், சி மற்றும் ஃபோர்ட்ரான் ஆகிய இரண்டிற்கும் கம்பைலர்கள் மற்றும் இணைப்பாளர்களை " +"சண்டையிடும் நேரத்தை செலவிடத் தயாராக இருக்கும் துணிச்சலான அனைவருக்கும், மூலத்திலிருந்து " +"கட்டுவது எப்போதும் ஒரு விருப்பமாகும்." + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" +"லினக்ச் பயனர்களைப் பொறுத்தவரை, கணினி தொகுப்பு மேலாளர் பெரும்பாலும் எண் மற்றும் விஞ்ஞான " +"பைதான் அடுக்கின் பிற பகுதிகள் உட்பட பல்வேறு அறிவியல் மென்பொருள்களின் முன் தொகுக்கப்பட்ட " +"பதிப்புகளைக் கொண்டிருப்பார்." + +#: ../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 "" +"பல மாதங்கள் பழமையான பதிப்புகளைப் பயன்படுத்துவது ஏற்றுக்கொள்ளத்தக்கது என்றால், இது ஒரு நல்ல " +"தேர்வாக இருக்கக்கூடும் (மெய்நிகர் சூழல்களைப் பயன்படுத்தும் போது கணினி பைத்தானில் " +"நிறுவப்பட்ட விநியோகங்களை அணுக அனுமதிப்பதை உறுதிசெய்க)." + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "சாளரங்கள் நிறுவிகள்" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" +"இல்லாத பல பைதான் திட்டங்கள் தற்போது சக்கரக் கோப்புகளை வெளியிடுகின்றன, குறைந்தது சாளரங்கள் " +"நிறுவிகளை பைபி அல்லது அவற்றின் திட்ட பதிவிறக்க பக்கத்தில் வெளியிடுகின்றன. இந்த " +"நிறுவிகளைப் பயன்படுத்துவது பயனர்கள் உள்நாட்டில் நீட்டிப்புகளை உருவாக்க பொருத்தமான சூழலை " +"அமைக்க வேண்டிய அவசியத்தைத் தவிர்க்க அனுமதிக்கிறது." + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" +"இந்த நிறுவிகளில் வழங்கப்பட்ட நீட்டிப்புகள் பொதுவாக python.org இல் வெளியிடப்பட்ட CPyThon " +"சாளரங்கள் நிறுவிகளுடன் இணக்கமாக இருக்கும்." + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" +"லினக்ச் கணினி தொகுப்புகளைப் போலவே, சாளரங்கள் நிறுவிகள் கணினி பைதான் நிறுவலில் மட்டுமே " +"நிறுவப்படும் - அவை மெய்நிகர் சூழல்களில் நிறுவலை ஆதரிக்காது. மெய்நிகர் சூழல்களைப் " +"பயன்படுத்தும் போது கணினி பைத்தானில் நிறுவப்பட்ட விநியோகங்களை அணுக அனுமதிப்பது இந்த " +"வரம்பைச் சுற்றி செயல்படுவதற்கான பொதுவான அணுகுமுறையாகும்." + +#: ../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 "" +"தி: கால: `வீல்` திட்டம் ஒரு விண்டோசை மாற்றக்கூடிய ஒரு: கட்டளை:` சக்கர மாற்றுதல் துணைக் " +"கட்டளை: கட்டளை: `bdist_wininst` நிறுவி ஒரு சக்கரத்திற்கு." + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" +"விண்டோசின் நிலைமையைப் போலவே, பல திட்டங்கள் (NUMPY உட்பட) MACOS நிறுவிகளை " +"வெளியிடுகின்றன, அவை பைதான்.ஆர்சில் வெளியிடப்பட்ட மேகோச் சிபிதான் பைனரிகளுடன் இணக்கமாக " +"உள்ளன." + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" +"மேகோச் பயனர்கள் `` ஓம் ப்ரூ`` போன்ற லினக்ச் விநியோக பாணி தொகுப்பு மேலாளர்களுக்கும் " +"அணுகலைக் கொண்டுள்ளனர். மேகோச் `_ இல் SCIPY ஐ " +"நிறுவ ஓம் ப்ரூவைப் பயன்படுத்துவது பற்றிய கூடுதல் விவரங்கள் SCIPY தளத்தில் உள்ளன." + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "சுறுசுறுப்பான வழங்கல்" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" +"SCIPY தளம் `பல விநியோகங்களை பட்டியலிடுகிறது ` _ இது " +"பயனர்களை எளிதாகப் பயன்படுத்தவும் புதுப்பிக்கவும் முழு ச்கிப்பி அடுக்கை வழங்குகிறது." + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" +"இந்த விநியோகங்களில் சில நிலையான `` பிஐபி`` மற்றும் `` மெய்நிகர்என்.வி`` அடிப்படையிலான " +"கருவித்தொகுப்புடன் பொருந்தாது." + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "ச்பேர்ட்" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" +"`ச்பேக் ` _ என்பது பல பதிப்புகள், உள்ளமைவுகள், " +"தளங்கள் மற்றும் கம்பைலர்களை ஆதரிக்க வடிவமைக்கப்பட்ட ஒரு நெகிழ்வான தொகுப்பு மேலாளராகும். " +"பெரிய சூப்பர் கம்ப்யூட்டிங் மையங்கள் மற்றும் அறிவியல் பயன்பாட்டுக் குழுக்களின் தேவைகளை " +"ஆதரிப்பதற்காக இது கட்டப்பட்டது, அவர்கள் பெரும்பாலும் மென்பொருளை பல வழிகளில் உருவாக்க " +"வேண்டும். ச்பேக் பைத்தானுக்கு மட்டுப்படுத்தப்படவில்லை; இது `` c``, `` c ++ ``, `` " +"ஃபோர்ட்ரான்``, `` r`` மற்றும் பிற மொழிகளுக்கான தொகுப்புகளை நிறுவ முடியும். இது " +"அழிவில்லாதது; ஒரு தொகுப்பின் புதிய பதிப்பை நிறுவுவது ஏற்கனவே உள்ள நிறுவல்களை " +"உடைக்காது, எனவே பல உள்ளமைவுகள் ஒரே கணினியில் இணைந்து வாழ முடியும்." + +#: ../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 "" +"ச்பாக் ஒரு எளிய ஆனால் சக்திவாய்ந்த தொடரியல் வழங்குகிறது, இது பயனர்களை பதிப்புகள் மற்றும் " +"உள்ளமைவு விருப்பங்களை சுருக்கமாகக் குறிப்பிட அனுமதிக்கிறது. தொகுப்பு கோப்புகள் தூய " +"பைத்தானில் எழுதப்பட்டுள்ளன, மேலும் அவை வார்ப்புருக்கள், இதனால் கம்பைலர்கள், சார்பு " +"செயலாக்கங்கள் (எம்.பி.ஐ போன்றவை), பதிப்புகள் மற்றும் ஒற்றை தொகுப்பு கோப்புடன் விருப்பங்களை " +"உருவாக்குவது எளிது. ச்பேக் * தொகுதி * கோப்புகளையும் உருவாக்குகிறது, இதனால் பயனரின் " +"சூழலில் இருந்து தொகுப்புகளை ஏற்றவும் இறக்கவும் முடியும்." + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "காண்டா குறுக்கு-தளம் தொகுப்பு மேலாளர்" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" +"`` காண்டா`` என்பது ஒரு திறந்த மூல (பி.எச்.டி உரிமம் பெற்ற) தொகுப்பு மேலாண்மை அமைப்பு " +"மற்றும் சுற்றுச்சூழல் மேலாண்மை அமைப்பு, இது பைனரி மென்பொருள் தொகுப்புகளின் பல " +"பதிப்புகளையும் அவற்றின் சார்புகளையும் நிறுவ பயனர்களை அனுமதிக்கிறது, மேலும் அவற்றுக்கு " +"இடையில் எளிதாக மாறுகிறது. இது சாளரங்கள், மேகோச் மற்றும் லினக்சில் பணிபுரியும் குறுக்கு-" +"தளம் கருவியாகும். அனைத்து வகையான தொகுப்புகளையும் தொகுத்து விநியோகிக்க கான்டாவைப் " +"பயன்படுத்தலாம், இது பைதான் தொகுப்புகளுக்கு மட்டுப்படுத்தப்படவில்லை. இது சொந்த மெய்நிகர் " +"சூழல்களுக்கு முழு ஆதரவைக் கொண்டுள்ளது. காண்டா சூழல்களை முதல் தர குடிமக்களை " +"உருவாக்குகிறது, இது சி நூலகங்களுக்கு கூட சுயாதீனமான சூழல்களை உருவாக்குவதை " +"எளிதாக்குகிறது. இது பைத்தானில் எழுதப்பட்டுள்ளது, ஆனால் பைதான்-அஞ்ஞானியாகும். காண்டா " +"பைத்தானை ஒரு தொகுப்பாக நிர்வகிக்கிறார், அதனால்: கட்டளை: `காண்டா புதுப்பிப்பு பைதான்` " +"சாத்தியமாகும், இது PITHON தொகுப்புகளை மட்டுமே நிர்வகிக்கிறது." + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" +"அனகோண்டா `அனகோண்டா ` _ என்பது அனகோண்டா, " +"இன்க். கான்டா சூழல்களை நிர்வகிப்பதற்கான இடைமுக பயன்பாடுகள்." + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" +"அனகோண்டா வழங்கிய முழு விநியோகத்திற்கு கூடுதலாக, காண்டா தொகுப்பு மேலாளர் `மினிகொண்டா " +"` _, `மினிஃபார்ச் `_, மற்றும்` பிக்சி `_." + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" +"அனகோண்டா.ஆர்சில் பல சேனல்களில் காண்டா தொகுப்புகள் கிடைக்கின்றன, இதில் அனகோண்டா, இன்க் " +"ஆதரிக்கப்படும் இயல்புநிலை சேனல், சமூகம் ஆதரவளித்த கான்டா-ஃபார்ச் சேனலை உள்ளடக்கியது, இது " +"பலவிதமான முன் கட்டப்பட்ட தொகுப்புகளை வழங்குகிறது மற்றும் சில டொமைன்-குறிப்பிட்ட தொகுப்பு " +"தொகுப்புகளை வழங்குகிறது." + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "ச்டாண்ட் தனியாக கட்டளை வரி கருவிகளை நிறுவுதல்" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" +"பல தொகுப்புகள் கட்டளை வரி பயன்பாடுகளை வழங்குகின்றன. அத்தகைய தொகுப்புகளின் " +"எடுத்துக்காட்டுகள் `mypy ` _, `flake8 ` _, `கருப்பு `_, " +"மற்றும்: ref:` pipenv`." + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" +"வழக்கமாக நீங்கள் இந்த பயன்பாடுகளை உங்கள் கணினியில் எங்கிருந்தும் அணுக முடியும், ஆனால் " +"தொகுப்புகளையும் அவற்றின் சார்புகளையும் அதே உலகளாவிய சூழலுக்கு நிறுவுவது பதிப்பு " +"மோதல்களை ஏற்படுத்தும் மற்றும் பைதான் தொகுப்புகளில் இயக்க முறைமை வைத்திருக்கும் சார்புகளை " +"உடைக்கலாம்." + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" +". இது ஒவ்வொரு தொகுப்பையும் மற்ற தொகுப்புகளுடன் மோதல்களை ஏற்படுத்தாமல் மேம்படுத்த அல்லது " +"நிறுவல் நீக்க அனுமதிக்கிறது, மேலும் பயன்பாடுகளை எங்கிருந்தும் பாதுகாப்பாக இயக்க " +"அனுமதிக்கிறது." + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "பிஐபிஎக்ச் பைதான் 3.6+ உடன் மட்டுமே வேலை செய்கிறது." + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "PIPX PIP உடன் நிறுவப்பட்டுள்ளது:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" +"`` உறுதிப்படுத்தவும் `` பயன்பாட்டு அடைவு உங்கள் `` $ பாதை`` ஐ உறுதி செய்கிறது. இந்த " +"புதுப்பிப்பு நடைமுறைக்கு வர உங்கள் முனையத்தை மறுதொடக்கம் செய்ய வேண்டியிருக்கலாம்." + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" +"இப்போது நீங்கள் `` பிஐபிஎக்ச் நிறுவல்` உடன் தொகுப்புகளை நிறுவலாம் மற்றும் எங்கிருந்தும் " +"தொகுப்பின் பயன்பாடுகளை (களை) இயக்கலாம்." + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "உதாரணமாக:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" +"PIPX உடன் நிறுவப்பட்ட தொகுப்புகளின் பட்டியலைக் காண மற்றும் எந்த பயன்பாடுகள் கிடைக்கின்றன " +"என்பதைக் காண, `` PIPX பட்டியல்`` ஐப் பயன்படுத்தவும்:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "ஒரு தொகுப்பை மேம்படுத்த அல்லது நிறுவல் நீக்க:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "PIPX ஐ மேம்படுத்தலாம் அல்லது PIP உடன் நிறுவல் நீக்கலாம்:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" +"ஒரு பயன்பாட்டின் அண்மைக் கால பதிப்பை தற்காலிக, இடைக்கால சூழலில் நிறுவவும் இயக்கவும் PIPX " +"உங்களை அனுமதிக்கிறது. உதாரணமாக:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "பிப்எக்ச் வழங்கும் கட்டளைகளின் முழு பட்டியலையும் காண, இயக்கவும்:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +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 "லினக்ச் தொகுப்பு மேலாளர்களுடன் PIP/Setuptools/whle ஐ நிறுவுதல்" + +#: ../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 section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" +"இந்த பிரிவு எவ்வாறு நிறுவுவது என்பதை உள்ளடக்கியது: குறிப்பு: `பிப்`,: ref:` " +"setuptools`, மற்றும்: Ref: `whel` லினக்ச் தொகுப்பு மேலாளர்களைப் பயன்படுத்துதல்." + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" +"`Python.org _ _ இலிருந்து பதிவிறக்கம் செய்யப்பட்ட பைதானைப் " +"பயன்படுத்துகிறீர்கள் என்றால், இந்த பிரிவு பொருந்தாது. இதைக் காண்க: ref: " +"`நிறுவுதல்_ரொக்விரெமென்ட்ச்` பிரிவு." + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +msgstr "" +"இதன் பதிப்புகளுக்கு இது பொதுவானது: ref: `பிப்`,: ref:` setuptools`, மற்றும்: ref: " +"`சக்கரம்` ஒரு குறிப்பிட்ட லினக்ச் விநியோகத்தால் ஆதரிக்கப்படுகிறது, அது பொதுமக்களுக்கு " +"வெளியிடப்பட்ட நேரத்தில் காலாவதியானது, பொதுவாக புதுப்பிப்புகள் பாதுகாப்பு " +"காரணங்களுக்காக மட்டுமே நிகழ்கிறது, அம்ச புதுப்பிப்புகளுக்கு அல்ல. சில விநியோகங்களுக்கு, " +"புதிய பதிப்புகளை வழங்க கூடுதல் களஞ்சியங்கள் இயக்கப்படலாம். எங்களுக்குத் தெரிந்த களஞ்சியங்கள் " +"கீழே விளக்கப்பட்டுள்ளன." + +#: ../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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "ஃபெடோரா" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" +"ஃபெடோராவில் பைதான் பற்றி மேலும் அறிய, தயவுசெய்து `அதிகாரப்பூர்வ ஃபெடோரா டாக்ச்`_,` " +"பைதான் வகுப்பறை`_ அல்லது `ஃபெடோரா பைதான்`_ ஐ நேசிக்கவும்." + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "சென்டோச்/ரெல்" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" +"சென்டோச் மற்றும் ரெல் வழங்கவில்லை: குறிப்பு: `பிப்` அல்லது: Ref:` வீல்` அவர்களின் முக்கிய " +"களஞ்சியங்களில், இருப்பினும்: Ref: `setuptools` இயல்பாக நிறுவப்பட்டுள்ளது." + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "கணினி பைத்தானுக்கு பிஐபி மற்றும் சக்கரத்தை நிறுவ, இரண்டு விருப்பங்கள் உள்ளன:" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" +"`எபல் களஞ்சியத்தை ` _ இந்த வழிமுறைகளைப் " +"பயன்படுத்தி __. " +"எபல் 7 இல், நீங்கள் பிப் மற்றும் வீலை நிறுவலாம்:" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" +"எபல் கூடுதல், மோதல் அல்லாத தொகுப்புகளை மட்டுமே வழங்குவதால், எபல் செட்டுப்லூல்களை " +"வழங்காது, ஏனெனில் இது முக்கிய களஞ்சியத்தில் உள்ளது." + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" +"`பைபா கோப்ர் ரெப்போ ` _ " +"`இந்த வழிமுறைகளைப் பயன்படுத்துதல் `_ and install one of the " +"`parallel-installable `_ " +"Pythons, along with pip, setuptools, and wheel, which are kept fairly up to " +"date." +msgstr "" +"`Ius களஞ்சியத்தை _ _ _` இணையாக-உள்ள-நிறுவல் `_ பைதான்ச் ஆகியவற்றில் ஒன்றை " +"நிறுவவும் பிப், செடுப்டூல்கள் மற்றும் சக்கரம், அவை மிகவும் புதுப்பித்த நிலையில் உள்ளன." + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "எடுத்துக்காட்டாக, centos7/Rhel7 இல் பைதான் 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 "டெபியன்/உபுண்டு மற்றும் வழித்தோன்றல்கள்" + +#: ../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 "" +"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 "" +"அண்மைக் கால டெபியன்/உபுண்டு பதிப்புகள் `\" பயனர் திட்டத்தை \"` _ இயல்பாக மாற்றியமைத்த பிஐபி மாற்றியமைத்துள்ளன, " +"இது முன்னிருப்பாக, இது ஒரு குறிப்பிடத்தக்க நடத்தை மாற்றமாகும் சில பயனர்களுக்கு " +"ஆச்சரியமாக இருக்கும்." + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "ஆர்ச் லினக்ச்" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" +"தற்போது, சென்டோச்/ஆர்.எச்.இ.எல் -க்கு \"கோப்ஆர்\" யூம் சொருகி கிடைக்கவில்லை, எனவே " +"விவரிக்கப்பட்டுள்ளபடி ரெப்போ கோப்புகளை கைமுறையாக வைப்பதே ஒரே வழி." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +msgid "Install packages in a virtual environment using pip and venv" +msgstr "PIP மற்றும் WENV ஐப் பயன்படுத்தி மெய்நிகர் சூழலில் தொகுப்புகளை நிறுவவும்" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" +"இந்த வழிகாட்டி நிலையான நூலகத்தின் மெய்நிகர் சூழல் கருவியைப் பயன்படுத்தி ஒரு மெய்நிகர் " +"சூழலை எவ்வாறு உருவாக்குவது மற்றும் செயல்படுத்துவது என்பதை விவாதிக்கிறது: ref: `VEV` " +"மற்றும் தொகுப்புகளை நிறுவுதல். வழிகாட்டி எப்படி என்பதை உள்ளடக்கியது:" + +#: ../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 "பிப் தயாரிக்கவும்" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "`` பிப்`` கட்டளையைப் பயன்படுத்தி மெய்நிகர் சூழலில் தொகுப்புகளை நிறுவவும்" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "தேவைகள் கோப்பைப் பயன்படுத்தவும் உருவாக்கவும்" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" +"இந்த வழிகாட்டி தற்போது 3.8 மற்றும் அதற்கு மேற்பட்ட பைத்தானின் ஆதரிக்கப்பட்ட பதிப்புகளுக்கு " +"பொருந்தும்." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" +"இந்த வழிகாட்டி ஒரு: கால: `விநியோக தொகுப்பு` ஐக் குறிக்க ** தொகுப்பு ** என்ற " +"வார்த்தையைப் பயன்படுத்துகிறது, இது பொதுவாக வெளிப்புற ஓச்டிலிருந்து நிறுவப்படுகிறது. " +"இது வார்த்தையிலிருந்து வேறுபடுகிறது: சொல்: `இறக்குமதி தொகுப்பு` இது உங்கள் பைதான் " +"மூலக் குறியீட்டில் தொகுதிகளை இறக்குமதி செய்வதைக் குறிக்கிறது." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" +"இந்த வழிகாட்டியில் இலிருந்து பெறப்பட்ட " +"அதிகாரப்பூர்வ பைதான் பதிப்பைப் பயன்படுத்துகிறீர்கள் என்ற முன்நிபந்தனை உள்ளது. பைத்தானை " +"நிறுவ உங்கள் இயக்க முறைமையின் தொகுப்பு மேலாளரைப் பயன்படுத்துகிறீர்கள் என்றால், இந்த " +"படிகளைத் தொடர முன் பைதான் நிறுவப்பட்டிருப்பதை உறுதிப்படுத்தவும்." + +#: ../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 "" +":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 "" +". இது ஒரு \"மெய்நிகர்\" தனிமைப்படுத்தப்பட்ட பைதான் நிறுவலை உருவாக்குகிறது. நீங்கள் " +"திட்டங்களை மாற்றும்போது, பிற மெய்நிகர் சூழல்களிலிருந்து தனிமைப்படுத்தப்பட்ட புதிய " +"மெய்நிகர் சூழலை உருவாக்கலாம். மெய்நிகர் சூழலில் இருந்து நீங்கள் பயனடைகிறீர்கள், ஏனெனில் " +"தொகுப்புகள் நம்பிக்கையுடன் நிறுவப்படலாம், மேலும் மற்றொரு திட்டத்தின் சூழலில் தலையிடாது." + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" +"மெய்நிகர் சூழலை உருவாக்க, உங்கள் திட்டத்தின் கோப்பகத்திற்குச் சென்று பின்வரும் கட்டளையை " +"இயக்கவும். இது `` .venv`` என்ற உள்ளக கோப்புறையில் புதிய மெய்நிகர் சூழலை உருவாக்கும்:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" +"இரண்டாவது உரையாடல் மெய்நிகர் சூழலை உருவாக்குவதற்கான இடம். பொதுவாக, இதை உங்கள் " +"திட்டத்தில் உருவாக்கி `` .venv`` என்று அழைக்கலாம்." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "`` .venv`` கோப்புறையில் ஒரு மெய்நிகர் பைதான் நிறுவலை உருவாக்கும் `` vev``." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" +"உங்கள் மெய்நிகர் சுற்றுச்சூழல் கோப்பகத்தை உங்கள் பதிப்பு கட்டுப்பாட்டு அமைப்பிலிருந்து " +"`` .gitignore`` அல்லது அதற்கு ஒத்ததாக விலக்க வேண்டும்." + +#: ../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 "" +"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 "" +"உங்கள் மெய்நிகர் சூழலில் தொகுப்புகளை நிறுவவோ பயன்படுத்தவோ தொடங்குவதற்கு முன், நீங்கள் அதை " +"`` செயல்படுத்த வேண்டும்`. ஒரு மெய்நிகர் சூழலைச் செயல்படுத்துவது மெய்நிகர் சூழல் சார்ந்த `` " +"பைதான்`` மற்றும் `பிப்`` இயங்கக்கூடியவை உங்கள் செல்லின்` `பாதை`` செய்யும்." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" +"மெய்நிகர் சூழல் செயல்படுத்தப்பட்டதை உறுதிப்படுத்த, உங்கள் பைதான் மொழிபெயர்ப்பாளரின் " +"இருப்பிடத்தை சரிபார்க்கவும்:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" +"மெய்நிகர் சூழல் செயலில் இருக்கும்போது, மேற்கண்ட கட்டளை பின்வருவனவற்றுடன் முடிவடைவதன் மூலம் " +"`` .venv`` கோப்பகத்தை உள்ளடக்கிய ஒரு கோப்பு இடத்தை வெளியிடும்:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" +"ஒரு மெய்நிகர் சூழல் செயல்படுத்தப்படும் போது, பிஐபி அந்த குறிப்பிட்ட சூழலில் தொகுப்புகளை " +"நிறுவும். இது உங்கள் பைதான் பயன்பாட்டில் தொகுப்புகளை இறக்குமதி செய்து பயன்படுத்த " +"உதவுகிறது." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "மெய்நிகர் சூழலை செயலிழக்கச் செய்யுங்கள்" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" +"நீங்கள் திட்டங்களை மாற்ற விரும்பினால் அல்லது உங்கள் மெய்நிகர் சூழலை விட்டு வெளியேற " +"விரும்பினால், `` செயலிழக்கச் செய்யுங்கள்` சூழலை:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" +"உங்கள் செல்லை மூடுவது மெய்நிகர் சூழலை செயலிழக்கச் செய்யும். நீங்கள் ஒரு புதிய செல் " +"சாளரத்தைத் திறந்து மெய்நிகர் சூழலைப் பயன்படுத்த விரும்பினால், அதை மீண்டும் செயல்படுத்தவும்." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "மெய்நிகர் சூழலை மீண்டும் செயல்படுத்தவும்" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" +"ஏற்கனவே உள்ள மெய்நிகர் சூழலை மீண்டும் செயல்படுத்த விரும்பினால், மெய்நிகர் சூழலை " +"செயல்படுத்துவது குறித்த அதே வழிமுறைகளைப் பின்பற்றவும். புதிய மெய்நிகர் சூழலை உருவாக்க " +"வேண்டிய அவசியமில்லை." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" +": குறிப்பு: `பிப்` என்பது குறிப்பு பைதான் தொகுப்பு மேலாளர். தொகுப்புகளை மெய்நிகர் " +"சூழலில் நிறுவவும் புதுப்பிக்கவும் இது பயன்படுகிறது." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst: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 க்கான பைதான் நிறுவிகளில் PIP அடங்கும். லினக்சில், `` பைதான் 3-பிப்`` போன்ற " +"கூடுதல் தொகுப்பை நீங்கள் நிறுவ வேண்டியிருக்கும். இயங்குவதன் மூலம் பிஐபி புதுப்பித்த " +"நிலையில் இருப்பதை நீங்கள் உறுதிப்படுத்திக் கொள்ளலாம்:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "பின்னர், உங்கள் பயனர் தளத்தில் PIP இன் அண்மைக் கால பதிப்பை நிறுவ வேண்டும்:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" +"விண்டோசிற்கான பைதான் நிறுவிகளில் பிஐபி அடங்கும். இயங்குவதன் மூலம் பிஐபி புதுப்பித்த " +"நிலையில் இருப்பதை நீங்கள் உறுதிப்படுத்திக் கொள்ளலாம்:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst: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 ஐப் பயன்படுத்தி தொகுப்புகளை நிறுவவும்" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" +"உங்கள் மெய்நிகர் சூழல் செயல்படுத்தப்படும்போது, நீங்கள் தொகுப்புகளை நிறுவலாம். தொகுப்புகளை " +"நிறுவ `` பிஐபி நிறுவல்` கட்டளையைப் பயன்படுத்தவும்." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "ஒரு தொகுப்பை நிறுவவும்" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +#, fuzzy +#| msgid "" +#| "For example,let's install the `Requests`_ library from the :term:`Python " +#| "Package Index (PyPI)`:" +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" +"எடுத்துக்காட்டாக, `கோரிக்கைகள்`_ நூலகத்தை நிறுவுவோம்: கால:` பைதான் தொகுப்பு குறியீட்டு " +"(PYPI) `:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" +"பிஐபி கோரிக்கைகள் மற்றும் அதன் அனைத்து சார்புகளையும் பதிவிறக்கம் செய்து அவற்றை நிறுவ " +"வேண்டும்:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "ஒரு குறிப்பிட்ட தொகுப்பு பதிப்பை நிறுவவும்" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" +"ஒரு தொகுப்பின் எந்த பதிப்பை நிறுவ வேண்டும் என்பதைக் குறிப்பிட PIP உங்களை அனுமதிக்கிறது: " +"கால: `பதிப்பு விவரக்குறிப்புகள் <பதிப்பு விவரக்குறிப்பு>`. எடுத்துக்காட்டாக, `` " +"கோரிக்கைகள்`` இன் குறிப்பிட்ட பதிப்பை நிறுவ:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "கோரிக்கைகளின் அண்மைக் கால `` 2.x`` வெளியீட்டை நிறுவ:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" +"தொகுப்புகளின் முன் வெளியீட்டு பதிப்புகளை நிறுவ, `` --pre`` கொடியைப் பயன்படுத்தவும்:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +msgid "Install extras" +msgstr "கூடுதல் நிறுவவும்" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" +"சில தொகுப்புகளில் விருப்பமான `எக்ச்ட்ராச்`_ உள்ளது. அடைப்புக்குறிக்குள் கூடுதல் குறிப்பைக் " +"குறிப்பிடுவதன் மூலம் இவற்றை நிறுவ பிப் சொல்லலாம்:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "மூலத்திலிருந்து ஒரு தொகுப்பை நிறுவவும்" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" +"பிஐபி அதன் மூலக் குறியீட்டிலிருந்து நேரடியாக ஒரு தொகுப்பை நிறுவ முடியும். " +"எடுத்துக்காட்டாக, மூலக் குறியீட்டை `` Google-auth`` கோப்பகத்தில் நிறுவ:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +msgid "" +"Additionally, pip can install packages from source in :doc:`development mode " +"`, meaning that changes to the source " +"directory will immediately affect the installed package without needing to " +"re-install:" +msgstr "" +"கூடுதலாக, பிஐபி மூலத்திலிருந்து தொகுப்புகளை நிறுவலாம்: டிஓசி: `மேம்பாட்டு முறை " +"<செட்டப்டூல்ச்: யூசர்சூட்/டெவலப்மென்ட்_மோட்>`, அதாவது மூல கோப்பகத்தில் மாற்றங்கள் மீண்டும் " +"நிறுவத் தேவையில்லாமல் நிறுவப்பட்ட தொகுப்பை உடனடியாக பாதிக்கும்:" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" +"பிஐபி அவற்றின் பதிப்பு கட்டுப்பாட்டு அமைப்பிலிருந்து நேரடியாக தொகுப்புகளை நிறுவ " +"முடியும். எடுத்துக்காட்டாக, நீங்கள் ஒரு அறிவிலி களஞ்சியத்திலிருந்து நேரடியாக நிறுவலாம்:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" +"ஆதரிக்கப்பட்ட பதிப்பு கட்டுப்பாட்டு அமைப்புகள் மற்றும் தொடரியல் பற்றிய கூடுதல் தகவலுக்கு, " +"பைப்பின் ஆவணங்களைப் பார்க்கவும்: குறிப்பு: `வி.சி.எச் உதவி <பிஐபி: வி.சி.எச் ஆதரவு>`." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "உள்ளக காப்பகங்களிலிருந்து நிறுவவும்" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" +"உங்களிடம் ஒரு உள்ளக நகல் இருந்தால்: கால: `விநியோக தொகுப்பின் காப்பகம் (ஒரு சிப், சக்கரம் " +"அல்லது தார் கோப்பு) அதை நேரடியாக PIP உடன் நிறுவலாம்:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" +"பல தொகுப்புகளின் காப்பகங்களைக் கொண்ட ஒரு அடைவு உங்களிடம் இருந்தால், நீங்கள் அங்கு " +"தொகுப்புகளைத் தேடும்படி பைப்பிடம் சொல்லலாம், மேலும் பயன்படுத்த வேண்டாம்: கால: `பைதான் " +"தொகுப்பு குறியீட்டு (PYPI)`." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" +"வரையறுக்கப்பட்ட இணைப்பு கொண்ட கணினியில் நீங்கள் தொகுப்புகளை நிறுவினால் அல்லது விநியோக " +"தொகுப்புகளின் தோற்றத்தை கண்டிப்பாக கட்டுப்படுத்த விரும்பினால் இது பயனுள்ளதாக இருக்கும்." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "பிற தொகுப்பு குறியீடுகளிலிருந்து நிறுவவும்" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" +"இதை விட வேறு குறியீட்டிலிருந்து தொகுப்புகளை பதிவிறக்கம் செய்ய விரும்பினால்: கால: " +"`பைதான் தொகுப்பு குறியீட்டு (PYPI)`, நீங்கள் `` --index-url`` கொடியைப் பயன்படுத்தலாம்:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" +"இரண்டிலிருந்தும் தொகுப்புகளை அனுமதிக்க விரும்பினால்: சொல்: `பைதான் தொகுப்பு குறியீட்டு " +"(PYPI)` மற்றும் ஒரு தனி குறியீட்டை, அதற்கு பதிலாக `` --extra-index-url`` கொடியைப் " +"பயன்படுத்தலாம்:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "தொகுப்புகளை மேம்படுத்துதல்" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" +"பிஐபி `` --upgrade`` கொடியைப் பயன்படுத்தி தொகுப்புகளை மேம்படுத்தலாம். " +"எடுத்துக்காட்டாக, `` கோரிக்கைகள்`` மற்றும் அதன் அனைத்து சார்புகளின் அண்மைக் கால பதிப்பையும் " +"நிறுவ:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "தேவைகள் கோப்பைப் பயன்படுத்துதல்" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" +"தொகுப்புகளை தனித்தனியாக நிறுவுவதற்கு பதிலாக, அனைத்து சார்புகளையும் A: Ref: `தேவைகள் " +"கோப்பு ` இல் அறிவிக்க PIP உங்களை அனுமதிக்கிறது. " +"எடுத்துக்காட்டாக, நீங்கள் ஒரு: கோப்பு: `தேவைகள். TXT` கோப்பு:" + +#: ../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 "" +"`` -R`` கொடியைப் பயன்படுத்தி இந்த கோப்பில் உள்ள அனைத்து தொகுப்புகளையும் நிறுவ பைப்பிடம் " +"சொல்லுங்கள்:" + +#: ../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 "" +"Pip can export a list of all installed packages and their versions using the " +"``freeze`` command:" +msgstr "" +"`` ஃப்ரீச்`` கட்டளையைப் பயன்படுத்தி நிறுவப்பட்ட அனைத்து தொகுப்புகளின் பட்டியலையும் அவற்றின் " +"பதிப்புகளையும் பிஐபி ஏற்றுமதி செய்யலாம்:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 +msgid "Which will output a list of package specifiers such as:" +msgstr "இது போன்ற தொகுப்பு குறிப்பான்களின் பட்டியலை வெளியிடும்:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" +"`` பிஐபி ஃப்ரீச்`` கட்டளை உருவாக்க பயனுள்ளதாக இருக்கும்: குறிப்பு: `பிஐபி: தேவைகள் " +"கோப்புகள்` இது சூழலில் நிறுவப்பட்ட அனைத்து தொகுப்புகளின் சரியான பதிப்புகளை மீண்டும் " +"உருவாக்க முடியும்." + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "மெய்நிகர் ஈன்வி பயன்படுத்தி தொகுப்புகளை நிறுவுதல்" + +#: ../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` மற்றும்: Ref:` Virtualenv`, தனிமைப்படுத்தப்பட்ட பைதான் சூழல்களை உருவாக்குவதற்கான " +"ஒரு கருவி." + +#: ../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: " +"`மெய்நிகர்என்வ்` ஆவணங்களை தயவுசெய்து பார்க்கவும்." + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" +"இந்த ஆவணம் ** தொகுப்பு ** என்ற வார்த்தையைப் பயன்படுத்துகிறது: கால: `விநியோக தொகுப்பு` " +"இது ஒரு: கால:` இறக்குமதி தொகுப்பு` உங்கள் பைதான் மூலக் குறியீட்டில் தொகுதிகளை " +"இறக்குமதி செய்யப் பயன்படுகிறது." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "உரிமம் அளிக்கும் எடுத்துக்காட்டுகள் மற்றும் பயனர் காட்சிகள்" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +#, fuzzy +#| msgid "" +#| ":pep:`639` has specified the way to declare a project's license and paths " +#| "to license files and other legally required information. This document " +#| "aims to provide clear guidance how to migrate from the legacy to the " +#| "standardized way of declaring licenses." +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" +". இந்த ஆவணம் உரிமைகளை அறிவிக்கும் தரப்படுத்தப்பட்ட வழிக்கு மரபுரிமையிலிருந்து எவ்வாறு " +"குடிபெயர்வது என்பதை தெளிவான வழிகாட்டுதலை வழங்குவதை நோக்கமாகக் கொண்டுள்ளது." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "உரிம எடுத்துக்காட்டுகள்" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "அடிப்படை எடுத்துக்காட்டு" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" +"`பதிப்பு 75.6.0 __ __, அதன் சொந்த திட்ட மூல மெட்டாடேட்டாவில்` " +"`உரிமம்`` புலத்தைப் பயன்படுத்தாது. மேலும், இது முன்னர் செய்ததைப் போலவே `` உரிமம்_பீல்``/" +"`உரிமம்_பில்கள்`` ஐ இனி வெளிப்படையாகக் குறிப்பிடவில்லை, ஏனெனில் செடுப்டூல்ச் அதன் சொந்த " +"உரிமம் தொடர்பான கோப்புகளை தானாகவே சேர்ப்பதை நம்பியுள்ளது:` உரிமம்` கோப்பு போன்ற " +"பொதுவான வடிவங்களுடன் பொருந்துகிறது இது பயன்படுத்துகிறது." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" +"இது அதன் பின்வரும் உரிமம் தொடர்பான மெட்டாடேட்டாவை உள்ளடக்கியது: கோப்பு: " +"`pyproject.toml`:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" +"PEP 639 க்கு எளிமையான இடம்பெயர்வு இதற்கு பதிலாக இதைப் பயன்படுத்துவதைக் கொண்டிருக்கும்:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" +"அல்லது, திட்டம் பயன்படுத்தப்பட்டால்: கோப்பு: `setup.cfg`, அதன்` `[மெட்டாடேட்டா]` `அட்டவணை:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +#, fuzzy +#| msgid "" +#| "The output Core Metadata for the distribution packages would then be:" +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "விநியோக தொகுப்புகளுக்கான வெளியீட்டு கோர் மேனிலை தரவு பின்னர்:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" +"The: கோப்பு: `உரிமம்` கோப்பு இங்கே சேமிக்கப்படும்: கோப்பு:`/setuptools- {VERSION}/" +"உரிமம்` SDIST இல் மற்றும்: கோப்பு: `/setuptools- {VERSION} .dist-info/உரிமங்கள்/" +"உரிமம்` இல் சக்கரம், மற்றும் அங்கிருந்து தள கோப்பகத்தில் (எ.கா.: கோப்பு: `தள-பேக்கேச்கள்/`) " +"நிறுவலில் திறக்கப்படவில்லை; ." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "மேம்பட்ட எடுத்துக்காட்டு" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" +"செடிப்டூல்ச் மூன்றாம் தரப்பு திட்டங்களின் உரிமங்களை உள்ளடக்கியது என்று வைத்துக்கொள்வோம்: " +"கோப்பு: `setuptools/_vendor/` மற்றும்: கோப்பு: `pkg_resources/_vendor/` " +"கோப்பகங்கள்; குறிப்பாக:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +#, fuzzy +#| msgid "Some additional examples of valid ``License-Expression`` values:" +msgid "The appropriate license expressions are:" +msgstr "" +"செல்லுபடியாகும் `` உரிம-வெளிப்பாடு`` மதிப்புகளின் சில கூடுதல் எடுத்துக்காட்டுகள்:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" +"செட்ப்டூல்கள் இரண்டையும் உள்ளடக்கிய ஒரு விரிவான உரிம வெளிப்பாடு மற்றும் அதன் விற்பனையான " +"சார்புநிலைகள் இந்த மெட்டாடேட்டாவைக் கொண்டிருக்கும், இது அனைத்து உரிம வெளிப்பாடுகளையும் " +"ஒன்றாக இணைக்கிறது. அத்தகைய வெளிப்பாடு இருக்கலாம்:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" +"கூடுதலாக, உரிமங்களின் தேவைகளின்படி, தொடர்புடைய உரிமக் கோப்புகள் தொகுப்பில் சேர்க்கப்பட " +"வேண்டும். : கோப்பு: `உரிமம்` கோப்பில் எம்ஐடி உரிமத்தின் உரை மற்றும் செடுப்டூல்ச் " +"பயன்படுத்தும் பதிப்புரிமை,` `பைபார்சிங்``,` `மோர்_ஐடெர்டூல்ச்`` மற்றும்` `ஆர்டர் செய்யப்பட்ட-" +"செட்`; மற்றும் கோப்பு: `உரிமம்*` கோப்புகள்: கோப்பில்: `setuptools/_vendor/பேக்கேசிங்/` " +"கோப்பகத்தில் அப்பாச்சி 2.0 மற்றும் 2-உட்பிரிவு பி.எச்.டி உரிம உரை உள்ளது, மற்றும் " +"பேக்கேசிங் பதிப்புரிமை அறிக்கை மற்றும் `உரிமம் தேர்வு அறிவிப்பு <பேக்கேசிங் லிசன்ச்_>` __." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" +"குறிப்பாக, உரிமக் கோப்புகள் திட்ட மூல மரத்தில் பின்வரும் பாதைகளில் அமைந்துள்ளன என்று " +"கருதுகிறோம் (திட்ட மூலத்துடன் தொடர்புடையது: கோப்பு: `pyproject.toml`):" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "அனைத்தையும் ஒன்றாக இணைத்து, எங்கள்: கோப்பு: `pyproject.toml` இருக்கும்:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" +"அல்லது மாற்றாக, உரிமக் கோப்புகளை வெளிப்படையாக குறிப்பிடலாம் (பாதைகள் குளோப் வடிவங்கள் " +"என விளக்கப்படும்):" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "எங்கள் திட்டம் பயன்படுத்தப்பட்டால்: கோப்பு: `setup.cfg`, இதை நாங்கள் வரையறுக்கலாம்:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "எந்தவொரு அணுகுமுறையிலும், விநியோகத்தில் வெளியீட்டு கோர் மெட்டாடேட்டா:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" +"இதன் விளைவாக வரும் SDIST இல், உடன்: கோப்பு: `/` காப்பகத்தின் மூலமாகவும், `{{VERSION}` " +"`கோர் மெட்டாடேட்டாவில் குறிப்பிடப்பட்டுள்ள செடிப்டூல்ச் வெளியீட்டின் பதிப்பாகவும், உரிமக் " +"கோப்புகள் பாதைகளில் அமைந்திருக்கும்:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" +"கட்டப்பட்ட சக்கரத்தில், உடன்: கோப்பு: `/` காப்பகத்தின் வேர் மற்றும் `` {VERSION} `` " +"முந்தையதைப் போல, உரிமக் கோப்புகள் சேமிக்கப்படும்:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" +"இறுதியாக, நிறுவப்பட்ட திட்டத்தில், உடன்: கோப்பு: `தள-பேக்கேச்கள்/` தள அடைவு மற்றும் `` " +"{VERSION} `` முந்தையதைப் போல, உரிமக் கோப்புகள் நிறுவப்படும்:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "வெளிப்பாடு எடுத்துக்காட்டுகள்" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" +"செல்லுபடியாகும் `` உரிம-வெளிப்பாடு`` மதிப்புகளின் சில கூடுதல் எடுத்துக்காட்டுகள்:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "பயனர் காட்சிகள்" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" +"பின்வருபவை பயனர் கண்ணோட்டத்தில் பொதுவான பயன்பாட்டு நிகழ்வுகளின் வரம்பை உள்ளடக்கியது, " +"ஒவ்வொன்றிற்கும் வழிகாட்டுதலை வழங்குகிறது. பின்வருபவை சட்ட ஆலோசனையாக கருதப்படக்கூடாது " +"என்பதை நினைவில் கொள்க, மேலும் வாசகர்கள் தங்கள் நிலைமைக்கான பிரத்தியேகங்களைப் பற்றி " +"உறுதியாக தெரியாவிட்டால், உரிமம் பெற்ற சட்ட பயிற்சியாளரை தங்கள் அதிகார வரம்பில் அணுக " +"வேண்டும்." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "என்னிடம் ஒரு தனியார் தொகுப்பு உள்ளது, அது விநியோகிக்கப்படாது" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" +"உங்கள் தொகுப்பு பகிரங்கமாக பகிரப்படாவிட்டால், அதாவது உங்கள் நிறுவனம், அமைப்பு அல்லது " +"வீட்டுக்கு வெளியே, இது * வழக்கமாக * முறையான உரிமத்தை சேர்க்க கண்டிப்பாக அவசியமில்லை, " +"எனவே நீங்கள் இங்கே கூடுதல் எதையும் செய்ய வேண்டிய அவசியமில்லை." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" +"எவ்வாறாயினும், உங்கள் தொகுப்பு உள்ளமைவில் உரிம வெளிப்பாடாக `` உரிமம் பெறுதல்-" +"தனியுரிமைக்குறி`, மற்றும்/அல்லது பதிப்புரிமை அறிக்கை மற்றும் ஒரு சட்ட அறிவிப்புகளை " +"ஒரு: கோப்பு: `உரிமம். உங்கள் திட்ட அடைவு, இது தானாக பேக்கேசிங் கருவிகளால் சேர்க்கப்படும்." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" +"நான் எனது சொந்த வேலையை சட்டரீதியான கட்டுப்பாடுகள் இல்லாமல் பகிர்ந்து கொள்ள விரும்புகிறேன்" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" +"நீங்கள் உரிமத்தை சேர்க்கத் தேவையில்லை என்றாலும், உங்களிடம் அவ்வாறு செய்யாவிட்டால், உங்கள் " +"வேலையை பதிவிறக்கம் செய்ய, பயன்படுத்த அல்லது மேம்படுத்த யாருக்கும் எந்த அனுமதியும் இல்லை " +" `__, எனவே இது நீங்கள் உண்மையில் விரும்பியதற்கு * நேர்மாறாக " +"இருக்கலாம். `எம்ஐடி உரிமம் __ __ அதற்கு பதிலாக ஒரு சிறந்த " +"தேர்வாகும், ஏனெனில் இது எளிமையானது, பரவலாகப் பயன்படுத்தப்படுகிறது மற்றும் உங்கள் " +"வேலையுடன் யாரையும் அவர்கள் விரும்பியதைச் செய்ய அனுமதிக்கிறது (நீங்கள் வழக்குத் தொடுப்பதைத் " +"தவிர, நீங்கள் விரும்பாதது)." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" +"அதைப் பயன்படுத்த, `உரையை __ __ என்ற கோப்பில் ஒட்டவும்: கோப்பு:` " +"உரிமம். பின்னர், உங்கள்: கோப்பில் `` [திட்டம்] `` `` `` `` [திட்டம்] `` `` `` " +"pyproject.toml` இன் கீழ் `` உரிமம் = \"எம்ஐடி\" சேர்க்கவும் அல்லது அதன் கட்டமைப்பு கோப்பு/" +"பிரிவில் இருந்தால். நீங்கள் முடித்துவிட்டீர்கள்!" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "எனது திட்டத்தை ஒரு குறிப்பிட்ட உரிமத்தின் கீழ் விநியோகிக்க விரும்புகிறேன்" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" +"ஒரு குறிப்பிட்ட உரிமத்தைப் பயன்படுத்த, அதன் உரையை ஒரு: கோப்பு: `உரிமம். `ஏற்கனவே " +"நகலெடுக்கவும்,` `உரிமம் =\" உரிமம்-ஐடி \"` `[திட்டத்தின்]` `` `` உங்கள்: " +"`pyproject.toml` இன் கீழ் சேர்க்கவும், உங்கள் பேக்கேசிங் கருவி அதை ஆதரித்தால், அல்லது அதன் " +"கட்டமைப்பு கோப்பில் வேறு. `` உரிமம்-ஐடி`` மற்றும் நகலெடுக்கக்கூடிய உரிம உரையை " +"`Choosealicense __ __ அல்லது` spdx __ __ " +"போன்ற தளங்களில் காணலாம்." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" +"பல பிரபலமான குறியீடு ஓச்ட்கள், திட்ட வார்ப்புருக்கள் மற்றும் பேக்கேசிங் கருவிகள் உங்களுக்காக " +"உரிமக் கோப்பைச் சேர்க்கலாம், மேலும் எதிர்காலத்திலும் வெளிப்பாட்டை ஆதரிக்கலாம்." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "ஏற்கனவே உரிமம் பெற்ற ஒரு தொகுப்பை நான் பராமரிக்கிறேன்" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" +"உங்கள் திட்டத்தில் ஏற்கனவே உரிமக் கோப்புகள் மற்றும் மேனிலை தரவு இருந்தால், புதிய " +"செயல்பாட்டைப் பயன்படுத்த நீங்கள் இரண்டு மாற்றங்களை மட்டுமே செய்ய வேண்டும்." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +#, fuzzy +#| msgid "" +#| "In your project config file, enter your license expression under " +#| "``license`` (``[project]`` table in :file:`pyproject.toml`), or the " +#| "equivalent for your packaging tool, and make sure to remove any legacy " +#| "``license`` table subkeys or ``License ::`` classifiers. Your existing " +#| "``license`` value may already be valid as one (e.g. ``MIT``, ``Apache-2.0 " +#| "OR BSD-2-Clause``, etc); otherwise, check the `SPDX license list " +#| "`__ for the identifier that matches the license used in your " +#| "project." +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" +"உங்கள் திட்ட கட்டமைப்பு கோப்பில், உங்கள் உரிம வெளிப்பாட்டை `` உரிமம்`` (`` [திட்டம்] `` " +"அட்டவணை: கோப்பு: `pyproject.toml`), அல்லது உங்கள் பேக்கேசிங் கருவிக்கு சமமானதாக " +"உள்ளிட்டு, எதையும் அகற்றுவதை உறுதிசெய்க மரபு `` உரிமம்`` அட்டவணை சப் கீச் அல்லது `` " +"உரிமம் :: `` வகைப்படுத்திகள். உங்கள் இருக்கும் `` உரிமம்`` மதிப்பு ஏற்கனவே ஒன்றாக " +"செல்லுபடியாகும் (எ.கா. இல்லையெனில், உங்கள் திட்டத்தில் பயன்படுத்தப்படும் உரிமத்துடன் " +"பொருந்தக்கூடிய அடையாளங்காட்டிக்கு `SPDX உரிம பட்டியல் ` __ __ ஐ " +"சரிபார்க்கவும்." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" +"உங்கள் உரிமக் கோப்புகளை `` [திட்டம்] `` `இன் கீழ்` `உரிமக் கோப்புகள்` இன் கீழ் பட்டியலிடுவதை " +"உறுதிசெய்க: கோப்பு:` pyproject.toml` அல்லது உங்கள் கருவியின் உள்ளமைவு கோப்பில்." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" +"ஐப் பார்க்கவும்: ref: `உரிமம்-எடுத்துக்காட்டு-அடிப்படை` இது நடைமுறையில் எவ்வாறு " +"செயல்படுகிறது என்பதற்கான எளிய ஆனால் முழுமையான நிச உலக டெமோவுக்கு. உரிம " +"வகைப்படுத்தல்களை உரிம வெளிப்பாட்டில் எவ்வாறு மொழிபெயர்ப்பது என்பது குறித்த சிறந்த " +"உத்திகளையும் காண்க: PEP: `639` ஆசிரியர்கள்: `SPDX அடையாளங்காட்டிகளுக்கு மேப்பிங் உரிம " +"வகைப்படுத்திகள் <மேப்பிங் கிளாசிஃபியர்ச்டோச்பிஎக்ச்_> ____. பேக்கேசிங் கருவிகள் மரபு " +"உரிமம் பெறும் மெட்டாடேட்டாவை தானாக மாற்றுவதை ஆதரிக்கக்கூடும்; மேலும் தகவலுக்கு உங்கள் " +"கருவியின் ஆவணங்களை சரிபார்க்கவும்." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "எனது தொகுப்பில் வெவ்வேறு உரிமங்களின் கீழ் பிற குறியீடு அடங்கும்" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" +"உங்கள் திட்டத்தில் விற்பனையான சார்புநிலைகள் அல்லது பிற திறந்த மூல மென்பொருளிலிருந்து " +"நகலெடுக்கப்பட்ட கோப்புகள் போன்ற வெவ்வேறு உரிமங்களால் மூடப்பட்ட மற்றவர்களிடமிருந்து குறியீடு " +"இருந்தால், சம்பந்தப்பட்ட உரிமங்களையும் அவற்றுக்கிடையேயான உறவை விவரிக்க உரிம வெளிப்பாட்டை " +"உருவாக்கலாம்." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +#, fuzzy +#| msgid "" +#| "In short, ``License-1 AND License-2`` mean that *both* licenses apply to " +#| "your project, or parts of it (for example, you included a file under " +#| "another license), and ``License-1 OR License-2`` means that *either* of " +#| "the licenses can be used, at the user's option (for example, you want to " +#| "allow users a choice of multiple licenses). You can use parenthesis " +#| "(``()``) for grouping to form expressions that cover even the most " +#| "complex situations." +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" +"சுருக்கமாக, `` உரிமம் -1 மற்றும் உரிமம் -2`` என்பது உங்கள் திட்டத்திற்கு அல்லது அதன் " +"பகுதிகளுக்கு * இரண்டு * உரிமங்களும் பொருந்தும் என்று பொருள் (எடுத்துக்காட்டாக, நீங்கள் " +"மற்றொரு உரிமத்தின் கீழ் ஒரு கோப்பை சேர்த்துள்ளீர்கள்), மற்றும் `` உரிமம் -1 அல்லது உரிமம் " +"-2`` என்றால், பயனரின் விருப்பத்தில் * உரிமங்களில் * பயன்படுத்தப்படலாம் (எடுத்துக்காட்டாக, " +"பயனர்களுக்கு பல உரிமங்களைத் தேர்வு செய்ய அனுமதிக்க விரும்புகிறீர்கள்). மிகவும் சிக்கலான " +"சூழ்நிலைகளை கூட உள்ளடக்கும் வெளிப்பாடுகளை உருவாக்க குழுவிற்கு நீங்கள் அடைப்புக்குறிக்கு " +"(`` () `) பயன்படுத்தலாம்." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" +"உங்கள் திட்ட கட்டமைப்பு கோப்பில், உங்கள் உரிம வெளிப்பாட்டை `` உரிமம்`` (`` [திட்டம்] `` " +"அட்டவணை: கோப்பு: `pyproject.toml`), அல்லது உங்கள் பேக்கேசிங் கருவிக்கு சமமானதாக " +"உள்ளிட்டு, எதையும் அகற்றுவதை உறுதிசெய்க மரபு `` உரிமம்`` அட்டவணை சப் கீச் அல்லது `` " +"உரிமம் :: `` வகைப்படுத்திகள்." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" +"மேலும், உங்கள் திட்ட களஞ்சியத்தில் எங்காவது கோப்புகளாக அனைத்து உரிமங்களின் முழு உரிம " +"உரையையும் சேர்ப்பதை உறுதிசெய்க. `` [திட்டம்] `` `இல்: கோப்பு:` pyproject.toml` (உங்கள் " +"கருவி அதை ஆதரித்தால்), அல்லது உங்கள் கருவியின் உள்ளமைவில், அல்லது உங்கள் கருவியின் " +"உள்ளமைவில், அவை ஒவ்வொன்றிற்கும் உறவினர் பாதை அல்லது குளோப் வடிவங்களை பட்டியலிடுங்கள் " +"கோப்பு." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" +"உதாரணமாக, உங்கள் திட்டம் எம்ஐடி உரிமம் பெற்றதாக இருந்தால், அப்பாச்சி 2.0 அல்லது 2-கைது " +"பி.எச்.டி ஆகியவற்றின் கீழ் உரிமம் பெற்ற விற்பனையான சார்பு (சொல்லுங்கள், `` பேக்கேசிங்``) " +"இணைத்தால், உங்கள் உரிம வெளிப்பாடு `` எம்ஐடி மற்றும் (அப்பாச்சி- 2.0 அல்லது பி.எச்.டி -2-" +"அடைப்பு) ``. உங்கள் ரெப்போ ரூட்டில் `உரிமம். , எனவே அவை அனைத்தையும் சேர்க்க, நீங்கள் `` " +"[\"உரிமம். -Apache.txt \",\" _vendor/உரிமம்-bsd.txt \"]` `நேரடி கோப்பு பாதைகளாக." + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" +"ஒரு முழுமையான வேலை: ref: `உரிமம்-எடுத்துக்காட்டு-மேம்பட்டது` இது ஒரு நிச உலக " +"சிக்கலான திட்டத்திற்கு, பல தொழில்நுட்ப விவரங்களுடன் இதைப் பயன்படுத்துவதற்கு, மேலும் ஒரு " +"`பயிற்சி ` __ __ ஐ அணுகவும் SPDX அடையாளங்காட்டிகள் மற்றும் " +"வெளிப்பாடுகளைப் பயன்படுத்தி உதவி மற்றும் எடுத்துக்காட்டுகள்." + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "ஒரு பைபி நட்பு ரீட்மே தயாரித்தல்" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" +"உங்கள் திட்டத்தைப் புரிந்துகொள்ள உங்கள் பயனர்களுக்கு README கோப்புகள் உதவும், மேலும் உங்கள் " +"திட்டத்தின் விளக்கத்தை PYPI இல் அமைக்க பயன்படுத்தலாம். இந்த வழிகாட்டி ஒரு பைபி-நட்பு " +"வடிவத்தில் ஒரு README ஐ உருவாக்க உதவுகிறது மற்றும் உங்கள் தொகுப்பில் உங்கள் README ஐ " +"சேர்க்கவும், எனவே இது PYPI இல் தோன்றும்." + +#: ../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 "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" +"பைதான் திட்டங்களுக்கான README கோப்புகள் பெரும்பாலும் `` ReadMe``, `` readme.txt``, " +"`` ReadMe.rst``, அல்லது `` Readme.md`` என்று பெயரிடப்படுகின்றன." + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" +"உங்கள் README PYPI இல் சரியாகக் காண்பிக்க, PYPI ஆல் ஆதரிக்கப்படும் மார்க்அப் மொழியைத் " +"தேர்வுசெய்க. `பைபியின் ரீட்மே ரெண்டரர் ` _ " +"ஆகியவற்றால் ஆதரிக்கப்படும் வடிவங்கள்:" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "சாதாரண எழுத்து" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" +"`மறுசீரமைக்கப்பட்ட டெக்ச்ட் ` _ (ச்பின்க்ச் " +"நீட்டிப்புகள் இல்லாமல்)" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" +"மார்க் பேரூர் (`கிதுப் சுவையான மார்க் பேரூர் ` _ " +"இயல்பாக, அல்லது `காமன்மார்க் ` _))" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" +"உங்கள் திட்டத்தின் மூலத்தில் உங்கள் README கோப்பை சேமிப்பது வழக்கம், உங்கள்: கோப்பு: " +"`setup.py` கோப்பு." + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "உங்கள் தொகுப்பின் மெட்டாடேட்டாவில் உங்கள் README உட்பட" + +#: ../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 இன் உள்ளடக்கங்களைச் சேர்க்க, உங்கள் திட்டத்தின் `` " +"விளக்கம்`` மற்றும் `` விளக்கம்-உள்ளடக்க-வகை`` மெட்டாடேட்டாவை அமைக்கவும், பொதுவாக உங்கள் " +"திட்டத்தின்: கோப்பு: `setup.py` கோப்பில்." + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr ": Ref: `விளக்கம்-விருப்பத்தேர்வு`" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr ": குறிப்பு: `விளக்கம்-உள்ளடக்க வகை-விருப்பத்தேர்வு`" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" +"எடுத்துக்காட்டாக, இந்த மதிப்புகளை ஒரு தொகுப்பில் அமைக்க: கோப்பு: `setup.py` கோப்பில்,` " +"`setup ()` 's `` long_description`` மற்றும் `` long_description_content_type`` " +"ஐப் பயன்படுத்தவும்." + +#: ../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``." +msgstr "" +"`` Long_description`` இன் மதிப்பை README கோப்பின் உள்ளடக்கங்களுக்கு (பாதை அல்ல) " +"அமைக்கவும். `` உரை/வெற்று``, `` உரை/x-rst`` (மறுசீரமைப்புக்கு), `` " +"long_description_content_type`` ஐ உங்கள் ரீட்மே கோப்பின் மார்க்அப்பிற்கு ஏற்றுக்கொள்ளப்பட்ட " +"`` உள்ளடக்க-வகை``-ச்டைல் மதிப்புக்கு அமைக்கவும் அல்லது `` உரை/மார்க் டவுன்``." + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" +"திட்டத்தின் விளக்கத்தை எழுத நீங்கள் கிதுப்-சுவை மார்க் டவுனைப் பயன்படுத்துகிறீர்கள் என்றால், " +"பின்வரும் கருவிகளை மேம்படுத்துவதை உறுதிசெய்க:" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "அந்தந்த கருவிகளின் குறைந்தபட்ச தேவையான பதிப்புகள்:" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" +"திட்டத்தின் விநியோக தொகுப்புகளை பதிவேற்ற `` ட்வைன்`` ஐப் பயன்படுத்த " +"பரிந்துரைக்கப்படுகிறது:" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" +"எடுத்துக்காட்டாக, இதைக் காண்க: கோப்பு: `setup.py` கோப்பு, இது உள்ளடக்கங்களைப் " +"படிக்கிறது: கோப்பு:` readme.md` `` long_description`` மற்றும் மார்க்அப்பை கிட்அப்-" +"சுவையான மார்க் பேரூர் என அடையாளம் காட்டுகிறது:" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "மறுசீரமைப்பு மார்க்அப்பை சரிபார்க்கிறது" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" +"உங்கள் README மறுசீரமைப்பு டெக்ச்டில் எழுதப்பட்டிருந்தால், எந்தவொரு தவறான மார்க்அப்பும் அதை " +"வழங்குதல் செய்வதைத் தடுக்கும், இதனால் பைபி அதற்கு பதிலாக README இன் மூல மூலத்தைக் " +"காண்பிக்கும்." + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" +"டாக்ச்ட்ரிங்சில் பயன்படுத்தப்படும் சூரரிமாச்சிலை நீட்டிப்புகள்: doc: `வழிமுறைகள் ` மற்றும்: டாக்: `பாத்திரங்கள் ` (எ.கா. func: `getattr```\" அல்லது \"` `: குறிப்பு:` " +"எனது-குறிப்பு-லேபிள்```` \"), இங்கே அனுமதிக்கப்படவில்லை, மேலும்\" `` பிழை: " +"அறியப்படாத விளக்கமளிக்கப்பட்ட உரை பாத்திரம் \"py: func \".``\"." + +#: ../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/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +msgstr "" +"`ட்வைன் ` _; பதிப்பு 1.12.0 அல்லது அதற்கு மேற்பட்டது " +"தேவை:" + +#: ../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 "" +"கீழ் விவரிக்கப்பட்டுள்ளபடி உங்கள் திட்டத்திற்கான SDIST மற்றும் சக்கரத்தை உருவாக்குங்கள்: ref: " +"`உங்கள் திட்டத்தை பேக்கேசிங் செய்தல்`." + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "Sdist மற்றும் சக்கரத்தில் `` கயிறு காசோலை`` ஐ இயக்கவும்:" + +#: ../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 ஐ வழங்குவதில் ஏதேனும் சிக்கல்களைப் புகாரளிக்கும். உங்கள் மார்க்அப் " +"நன்றாக வழங்கினால், கட்டளை வெளியிடும் `` விநியோக கோப்பு பெயரைச் சரிபார்க்கிறது: தேர்ச்சி " +"பெற்றவர்``." + +#: ../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 "" +":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 "" +": கால: `pypi.org` என்பது பைபியின் புதிய, மீண்டும் எழுதப்பட்ட பதிப்பாகும், இது மரபு " +"பைபி குறியீடு தளத்தை மாற்றியுள்ளது. பைபியின் இயல்புநிலை பதிப்பாகும், மக்கள் " +"பயன்படுத்துவார்கள் என்று எதிர்பார்க்கப்படுகிறது. மக்கள் `` pypi.org`` உடன் தொடர்பு கொள்ள " +"வேண்டிய கருவிகள் மற்றும் செயல்முறைகள் இவை." + +#: ../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 "`` pypi.org`` என்பது செப்டம்பர் 2016 நிலவரப்படி இயல்புநிலை பதிவேற்ற தளமாகும்." + +#: ../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`` மூலம் பதிவேற்றங்கள் ** சூலை 3, 2017 அன்று*சுவிட்ச் ஆஃப்***. " +"ஏப்ரல் 13, 2018 நிலவரப்படி, `` pypi.org`` என்பது PYPI க்கான முகவரி ஆகும்." + +#: ../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/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" +"இயல்புநிலை பதிவேற்ற அமைப்புகள் பின்வரும் பதிப்புகளில் `` pypi.org`` க்கு மாற்றப்பட்டன:" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "பைதான் 2.7.13 (`` தொலைதூரங்கள்` புதுப்பிப்பு)" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "பைதான் 3.4.6 (`` தொலைதூரங்கள்` புதுப்பிப்பு)" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "பைதான் 3.5.3 (`` distutils`` புதுப்பிப்பு)" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "பைதான் 3.6.0 (`` தொலைதூரங்கள்` புதுப்பிப்பு)" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" +"கருவியின் இயல்புநிலை மாற்றுவதற்கான கருவியின் புதிய பதிப்பில் நீங்கள் இருப்பதை உறுதி " +"செய்வதோடு மட்டுமல்லாமல், அதன் இயல்புநிலை பதிவேற்ற முகவரி ஐ மேலெழுத கருவியை நீங்கள் " +"கட்டமைக்கவில்லை என்பதையும் உறுதிப்படுத்த வேண்டும். பொதுவாக இது அமைந்துள்ள ஒரு கோப்பில் " +"கட்டமைக்கப்பட்டுள்ளது: கோப்பு: `$ home/.pypirc`. நீங்கள் ஒரு கோப்பைக் கண்டால்:" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" +"பின்னர் `` களஞ்சியம்`` உடன் தொடங்கும் வரியை நீக்கவும், உங்கள் பதிவேற்ற கருவியின் இயல்புநிலை " +"முகவரி ஐப் பயன்படுத்துவீர்கள்." + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +msgstr "" +"சில காரணங்களால் உங்கள் கருவியின் பதிப்பை pypi.org ஐப் பயன்படுத்துவதற்கு இயல்புநிலையாக " +"இருக்கும் பதிப்பிற்கு மேம்படுத்த முடியாவிட்டால், நீங்கள் திருத்தலாம்: கோப்பு: `$ " +"home/.pypirc` மற்றும்` `களஞ்சியம்:` `வரி சேர்க்கவும் ." + +#: ../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 "" +"(``legacy`` in this முகவரி refers பெறுநர் the fact that this is the புதிய " +"சேவையகம் implementation's போன்மம் of the legacy சேவையகம் implementation's upload " +"API.)" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "தொகுப்பு பெயர்கள் மற்றும் மெட்டாடேட்டாவை பதிவு செய்தல்" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" +"முதல் பதிவேற்றத்திற்கு முன்னர் `` setup.py பதிவு` கட்டளையுடன் தொகுப்பு பெயர்களை " +"வெளிப்படையாக பதிவு செய்வது இனி தேவையில்லை, மேலும் தற்போது pypi.org இல் மரபு " +"பதிவேற்ற பநிஇ ஈமுலேசன் மூலம் ஆதரிக்கப்படவில்லை." + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" +"இதன் விளைவாக, பதிவேற்றங்களுக்கு pypi.org ஐப் பயன்படுத்துவதற்கு மாறிய பின் வெளிப்படையான " +"பதிவை முயற்சிப்பது பின்வரும் பிழை செய்தியைக் கொடுக்கும் ::" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" +"பதிவு படிநிலையைத் தவிர்ப்பதே தீர்வு, மற்றும் கலைப்பொருட்களைப் பதிவேற்றுவதற்கு நேரடியாக " +"தொடரவும்." + +#: ../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 "" +"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 "" +"மரபு டெச்ட்பை (testpy.python.org) இனி கிடைக்காது; அதற்கு பதிலாக `test.pypi.org " +"` _ ஐப் பயன்படுத்தவும். நீங்கள் டெச்ட்பிஐயைப் பயன்படுத்தினால், " +"உங்கள்: கோப்பு: `$ முகப்பு/.pypirc` டெச்ட்பைப்பின் புதிய இருப்பிடத்தைக் கையாள,` " +"`https: // testpy.python.org/pypi`` ஐ` `https: // தேர்வு உடன் மாற்றுவதன் மூலம் " +"புதுப்பிக்க வேண்டும் .pypi.org/மரபு/``, எடுத்துக்காட்டாக:" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "புதிய பயனர் கணக்குகளை பதிவு செய்தல்" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" +"PYPI க்கு எதிரான ச்பேம் தாக்குதல்களைத் தணிக்க உதவுவதற்காக, `` pypi.python.org`` மூலம் " +"புதிய பயனர் பதிவு**பிப்ரவரி 20, 2018 அன்று அணைக்கப்பட்டது***. `` Pypi.org`` இல் " +"புதிய பயனர் பதிவுகள் திறந்திருக்கும்." + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "தொகுப்புகள் உலாவுதல்" + +#: ../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." +msgstr "" +"`` Pypi.python.org`` `மற்ற PYPA ஆவணங்கள் போன்றவற்றிலிருந்து இன்னும் பயன்படுத்தப்படலாம் " +"என்றாலும், தொகுப்புகளை உலாவுவதற்கான இயல்புநிலை இடைமுகம்` `pypi.org``. " +"Pypi.python.org டொமைன் இப்போது pypi.org க்கு திருப்பி விடுகிறது, மேலும் " +"எதிர்காலத்தில் முடக்கப்படலாம்." + +#: ../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 "`` pypi.org`` என்பது தொகுப்புகளைப் பதிவிறக்குவதற்கான இயல்புநிலை புரவலன் ஆகும்." + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "வெளியிடப்பட்ட தொகுப்புகள் மற்றும் வெளியீடுகளை நிர்வகித்தல்" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +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/modernize-setup-py-project.rst:12 +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`." +msgstr "" +"ப: கால: `pyproject.toml` கோப்பு கடுமையாக பரிந்துரைக்கப்படுகிறது. A இன் இருப்பு: " +"கோப்பு: `pyproject.toml` கோப்பே அதிகம் கொண்டு வராது. ." + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" +"BIP இன் உருவாக்க தனிமைப்படுத்தும் அம்சத்தில் இது செல்வாக்கைக் கொண்டுள்ளது என்பதை நினைவில் " +"கொள்க, கீழே காண்க." + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" +"இல்லை,: கோப்பு: `setup.py` ஒரு நவீனத்தில் இருக்க முடியும்: குறிப்பு:` setuptools` " +"அடிப்படையிலான திட்டம். தி: கால: `setup.py` கோப்பு என்பது பைத்தானில் எழுதப்படும் " +"செட்டுப்டூல்களுக்கான சரியான உள்ளமைவு கோப்பு. இருப்பினும், பின்வரும் கட்டளைகள் நீக்கப்பட்டன, " +"** இனி இயக்கப்படக்கூடாது, மேலும் அவற்றின் பரிந்துரைக்கப்பட்ட மாற்று கட்டளைகள் அதற்கு " +"பதிலாக பயன்படுத்தப்பட வேண்டும்:" + +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python -m build``" +msgstr "`` பைதான் -எம் பில்ட்``" + +#: ../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 "" +"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 "" +"தி: கால: `திட்டம்` இருக்க வேண்டும் ஒரு: கோப்பு:` pyproject.toml` அதன் மூல மரத்தின் " +"மூலத்தில் `` [பில்ட்-சிச்டம்] `` அட்டவணை போன்றவற்றைக் கொண்டுள்ளது:" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" +"இது அனுமதிக்கும் தரப்படுத்தப்பட்ட முறையாகும்: கால: `முன்பக்கத்தை உருவாக்குங்கள் " +"<உருவாக்கம்>` இதை அறிந்து கொள்ளுங்கள்: குறிப்பு: `செட்டுப்டூல்ச்` என்பது: கால:` இந்த " +"திட்டத்திற்கு பின்தளத்தில் கட்ட உருவாக்கு <பின்தளத்தில் உருவாக்கு>." + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" +"A: FILE: `pyproject.toml` கோப்பு (காலியாக இருந்தாலும்) தூண்டுகிறது என்பதை நினைவில் " +"கொள்க: Ref:` pip` அதன் இயல்புநிலை நடத்தையை மாற்ற *தனிமைப்படுத்தலை *." + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr ": Ref: `விநியோகிக்கும்-பேக்கேச்கள்`" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr ": ref: `பைப்ரோசெக்ட்-பில்ட்-சிச்டம்-டேபிள்`" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +#, fuzzy +#| msgid ":doc:`pip:reference/build-system/pyproject-toml`" +msgid ":doc:`pip:reference/build-system`" +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 "" +"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 "" +"செடிப்டூல்களின் மேல், என்றால்: கோப்பு: `setup.py` மற்ற மூன்றாம் தரப்பு நூலகங்களை " +"(பைத்தானின் நிலையான நூலகத்திற்கு வெளியே) சார்ந்துள்ளது ." + +#: ../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 "எடுத்துக்காட்டாக, ஒரு: கோப்பு: இது போன்ற `setup.py` கோப்பு:" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" +"ஒரு: கோப்பு: `pyproject.toml` இது போன்ற கோப்பு (: கோப்பு:` setup.py` மாறாமல் " +"இருக்கும்):" + +#: ../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 "" +"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 "" +"முன்பக்கங்களை உருவாக்குவது பொதுவாக ஒரு இடைக்கால மெய்நிகர் சூழலை உருவாக்குகிறது, அங்கு " +"அவை `` பில்ட்-சிச்டம்.நான் ``` இன் கீழ் பட்டியலிடப்பட்டுள்ள உருவாக்க சார்புகளை (மற்றும் " +"அவற்றின் சார்புகளை) மட்டுமே நிறுவுகின்றன, மேலும் அந்த சூழலில் கட்டமைப்பைத் தூண்டுகின்றன." + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" +"சில திட்டங்களுக்கு இந்த தனிமைப்படுத்தல் தேவையற்றது, அதை பின்வருமாறு செயலிழக்கச் செய்யலாம்:" + +#: ../source/guides/modernize-setup-py-project.rst:126 +msgid "``python -m build --no-isolation``" +msgstr "`` பைதான் -எம் பில்ட் -இல்லை -தனிமைப்படுத்தல்``" + +#: ../source/guides/modernize-setup-py-project.rst:127 +msgid "``python -m pip install --no-build-isolation``" +msgstr "`` பைதான் -எம் பிஐபி நிறுவல்-இல்லை-பில்ட்-ஐசோலேசன்``" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "பேக்கேசிங் மெட்டாடேட்டாவை எவ்வாறு கையாள்வது?" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" +"அனைத்து நிலையான மெட்டாடேட்டாவையும் விருப்பமாக `` [திட்டம்] `` அட்டவணை: கோப்பு: " +"`pyproject.toml` க்கு மாற்றலாம்." + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "ஒரு: கோப்பு: `pyproject.toml` இது போன்ற கோப்பு:" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" +"படிக்க: குறிப்பு: `` [திட்டம்] `` அட்டவணையில் அனுமதிக்கப்பட்ட உள்ளடக்கத்தின் முழு " +"விவரக்குறிப்புக்கு `pyproject-project-table`." + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "மாறும் மெட்டாடேட்டாவை எவ்வாறு கையாள்வது?" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" +"சில பேக்கேசிங் மேனிலை தரவு புலங்கள் நிலையானதாக இல்லாவிட்டால், இந்த `` திட்டத்தில்] `` " +"அட்டவணையில் அவை `` டைனமிக்`` என பட்டியலிடப்பட வேண்டும்." + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "பின்வருமாறு நவீனமயமாக்கலாம்:" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr ": குறிப்பு: `அறிவித்தல்-திட்ட-மெட்டாடேட்டா-டைனமிக்`" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "மாற்ற முடியாத ஒன்று `` setup.py`` கோப்பை எதிர்பார்க்கிறது என்றால் என்ன செய்வது?" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" +"எடுத்துக்காட்டாக, எளிதாக மாற்ற முடியாத ஒரு செயல்முறை உள்ளது, மேலும் இது `` பைதான் " +"setup.py --name`` போன்ற கட்டளையை இயக்க வேண்டும்." + +#: ../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 "" +"ஒரு: கோப்பு: `setup.py` கோப்பை திட்ட மூல மரத்தில் அதன் அனைத்து உள்ளடக்கங்களும் நகர்த்திய " +"பின்னரும் விட்டுவிடுவது மிகவும் நல்லது: கோப்பு:` pyproject.toml`. இந்த கோப்பு இதைப் " +"போலவே மிகச்சிறியதாக இருக்கலாம்:" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr ": ref: `pyproject-toml-spec`" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr ": டாக்: `செட்ப்டூல்ச்: பில்ட்_மெட்டா`" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "பல பதிப்பு நிறுவல்கள்" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" +"ஈசி_ச்டால் ஒரே திட்டத்தின் வெவ்வேறு பதிப்புகளை ஒரே நேரத்தில் பல நிரல்களால் பகிரப்பட்ட " +"ஒற்றை சூழலில் நிறுவ அனுமதிக்கிறது, இது திட்டத்தின் பொருத்தமான பதிப்பை இயக்க நேரத்தில் " +"(`` pkg_resources`` ஐப் பயன்படுத்த வேண்டும்)." + +#: ../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." +msgstr "" +"பல பயன்பாட்டு நிகழ்வுகளுக்கு, மெய்நிகர் சூழல்கள் இந்த தேவையை `` தேவை` 'கட்டளை இல்லாமல் " +"நிவர்த்தி செய்கின்றன. இருப்பினும், ஒரே சூழலுக்குள் இணையான நிறுவல்களின் நன்மை என்னவென்றால், " +"இது லினக்ச் விநியோகத்தில் கணினி பைதான் போன்ற பல பயன்பாடுகளால் பகிரப்பட்ட சூழலுக்கு வேலை " +"செய்கிறது." + +#: ../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." +msgstr "" +"`` பி.கே. இது சிக்கல்களை ஏற்படுத்தக்கூடும், ஏனெனில் `` setuptools`` உருவாக்கிய கட்டளை " +"வரி ச்கிரிப்ட்கள் `` pkg_resources`` ஐப் பயன்படுத்துகின்றன. இதன் பொருள், " +"எடுத்துக்காட்டாக, `` மூக்கு`` அல்லது `` `` குனிகார்ன்`` மூலம் பயன்படுத்தப்பட்ட `` தேவை` " +"சோதனைகளை நீங்கள் பயன்படுத்த முடியாது, உங்கள் விண்ணப்பத்திற்கு கிடைக்கக்கூடிய எதையும் " +"தாக்குதல் அல்லாத பதிப்பு தேவைப்பட்டால் நிலையான `` sys.bath`` - முதன்மையான " +"பயன்பாட்டிற்கான ச்கிரிப்ட் ரேப்பர் இயல்புநிலையாக கிடைக்கும் பதிப்பில் பூட்டப்படும், எனவே " +"அடுத்தடுத்த `` தேவை` உங்கள் சொந்த குறியீட்டில் அழைப்பு ஒரு மோசமான பதிப்பு மோதலுடன் " +"தோல்வியடைகிறது." + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" +"முதல் முறையாக `` பி.கே. தனிப்பயன் ரேப்பர் ச்கிரிப்டை எழுத தேவை அல்லது பயன்பாட்டின் " +"முதன்மையான நுழைவு புள்ளியை நேரடியாக அழைக்க `` பைதான் 3 -c '' `` " +"பயன்படுத்த வேண்டும்." + +#: ../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" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" +"சிபிதான் குறிப்பு மொழிபெயர்ப்பாளரின் அம்சங்களில் ஒன்று, பைதான் குறியீட்டை செயல்படுத்த " +"அனுமதிப்பதைத் தவிர, மற்ற மென்பொருளால் பயன்படுத்த ஒரு பணக்கார சி பநிஇ " +"அம்பலப்படுத்துகிறது. இந்த சி ஏபிஐயின் மிகவும் பொதுவான பயன்பாடுகளில் ஒன்று, தூய பைதான் " +"குறியீட்டில் எப்போதும் எளிதாக அடையாத விசயங்களை அனுமதிக்கும் இறக்குமதி செய்யக்கூடிய சி " +"நீட்டிப்புகளை உருவாக்குவதாகும்." + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "பைனரி நீட்டிப்புகளின் கண்ணோட்டம்" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "வழக்குகளைப் பயன்படுத்துங்கள்" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" +"பைனரி நீட்டிப்புகளுக்கான வழக்கமான பயன்பாட்டு வழக்குகள் மூன்று வழக்கமான வகைகளாக " +"உடைக்கப்படுகின்றன:" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" +". வெறுமனே, கொடுக்கப்பட்ட கணினியில் முடுக்கப்பட்ட பதிப்பு கிடைக்கவில்லை என்றால், முடுக்கி " +"தொகுதிகள் எப்போதுமே ஒரு தூய பைத்தானைக் கொண்டிருக்கும். Cpython நிலையான நூலகம் " +"முடுக்கி தொகுதிகளை விரிவாகப் பயன்படுத்துகிறது. . செயல்படுத்தல் (`_datetimemodule.c " +" _ _) " +"கிடைக்கவில்லை." + +#: ../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 `_." +msgstr "" +"** ரேப்பர் தொகுதிகள் **: இந்த தொகுதிகள் தற்போதுள்ள சி இடைமுகங்களை பைதான் குறியீட்டிற்கு " +"வெளிப்படுத்த உருவாக்கப்படுகின்றன. அவை அடிப்படை சி இடைமுகத்தை நேரடியாக " +"அம்பலப்படுத்தலாம், இல்லையெனில் பநிஇ பயன்படுத்த எளிதாக்குவதற்கு பைதான் மொழி அம்சங்களைப் " +"பயன்படுத்தும் அதிக \"பைத்தானிக்\" பநிஇ அம்பலப்படுத்தலாம். Cpython நிலையான நூலகம் ரேப்பர் " +"தொகுதிகளை விரிவாகப் பயன்படுத்துகிறது. . com/python/cpython/blob/main/தொகுதிகள்/" +"_functoolsmodule.c> `_." + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" +"** குறைந்த-நிலை கணினி அணுகல் **: இந்த தொகுதிகள் CPython இயக்க நேரம், இயக்க முறைமை " +"அல்லது அடிப்படை வன்பொருளின் கீழ் நிலை அம்சங்களை அணுக உருவாக்கப்படுகின்றன. இயங்குதள " +"குறிப்பிட்ட குறியீடு மூலம், நீட்டிப்பு தொகுதிகள் தூய பைதான் குறியீட்டில் சாத்தியமில்லாத " +"விசயங்களை அடையக்கூடும். மொழி மட்டத்தில் வெளிப்படுத்தப்படாத மொழிபெயர்ப்பாளர் உட்புறங்களை " +"அணுகுவதற்காக பல CPYTHON நிலையான நூலக தொகுதிகள் C இல் எழுதப்பட்டுள்ளன. ." + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" +"சி நீட்டிப்புகளின் குறிப்பாக குறிப்பிடத்தக்க நற்பொருத்தம் என்னவென்றால், அவர்கள் " +"மொழிபெயர்ப்பாளர் இயக்க நேரத்திற்கு திரும்ப அழைக்கத் தேவையில்லை, அவர்கள் சிபிதானின் " +"உலகளாவிய மொழிபெயர்ப்பாளர் பூட்டை நீண்டகால செயல்பாடுகளைச் சுற்றி வெளியிடலாம் (அந்த " +"செயல்பாடுகள் சிபியு அல்லது IO பிணைப்பு என்பதைப் பொருட்படுத்தாமல்)." + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" +"எல்லா நீட்டிப்பு தொகுதிகளும் மேலே உள்ள வகைகளுக்கு அழகாக பொருந்தாது. NUMPY உடன் " +"சேர்க்கப்பட்ட நீட்டிப்பு தொகுதிகள், எடுத்துக்காட்டாக, மூன்று பயன்பாட்டு நிகழ்வுகளையும் " +"பரப்புகின்றன - அவை வேக காரணங்களுக்காக உள் சுழல்களை C க்கு நகர்த்துகின்றன, C, Fortran " +"மற்றும் பிற மொழிகளில் எழுதப்பட்ட வெளிப்புற நூலகங்களை போர்த்துகின்றன, மேலும் CPyThon " +"மற்றும் அடிப்படை இரண்டிற்கும் குறைந்த அளவிலான கணினி இடைமுகங்களைப் பயன்படுத்துகின்றன " +"திசையன் செய்யப்பட்ட செயல்பாடுகளை ஒரே நேரத்தில் செயல்படுத்துவதற்கும், உருவாக்கப்பட்ட " +"பொருட்களின் சரியான நினைவக அமைப்பை இறுக்கமாகக் கட்டுப்படுத்துவதற்கும் செயல்பாட்டு அமைப்பு." + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "குறைபாடுகள்" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" +"பைனரி நீட்டிப்புகளைப் பயன்படுத்துவதன் முக்கிய குறைபாடு என்னவென்றால், இது மென்பொருளின் " +"அடுத்தடுத்த விநியோகத்தை மிகவும் கடினமாக்குகிறது. பைத்தானைப் பயன்படுத்துவதன் நன்மைகளில் " +"ஒன்று, இது பெரும்பாலும் குறுக்கு தளம், மற்றும் நீட்டிப்பு தொகுதிகளை எழுதப் " +"பயன்படுத்தப்படும் மொழிகள் (பொதுவாக சி அல்லது சி ++, ஆனால் உண்மையில் சிபிதான் சி பநிஇ " +"உடன் பிணைக்கக்கூடிய எந்தவொரு மொழியும் பொதுவாக தனிப்பயன் பைனரிகளை உருவாக்க வேண்டும் " +"வெவ்வேறு தளங்கள்." + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "This means that இருமம் extensions:" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" +"இறுதி பயனர்கள் அவற்றை மூலத்திலிருந்து உருவாக்க முடியும், இல்லையெனில் யாராவது பொதுவான " +"தளங்களுக்கு முன்பே கட்டப்பட்ட பைனரிகளை வெளியிடுகிறார்கள்" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "Cpython குறிப்பு மொழிபெயர்ப்பாளரின் வெவ்வேறு கட்டடங்களுடன் பொருந்தாது" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" +"பைபி, அயர்ன் பிதான் அல்லது சைத்தான் போன்ற மாற்று மொழிபெயர்ப்பாளர்களுடன் பெரும்பாலும் " +"சரியாக வேலை செய்யாது" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" +"ஏண்ட்கோட் செய்யப்பட்டால், பராமரிப்பாளர்கள் பைத்தானுடன் மட்டுமல்லாமல், பைனரி நீட்டிப்பை " +"உருவாக்கப் பயன்படுத்தப்படும் மொழியுடனும், சிபிதான் சி பநிஇ விவரங்களுடனும் தெரிந்திருக்க " +"வேண்டும் என்று தேவைப்படுவதன் மூலம் பராமரிப்பை மிகவும் கடினமாக்குங்கள்." + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" +"ஒரு தூய பைதான் குறைவடையும் செயல்படுத்தல் வழங்கப்பட்டால், இரண்டு இடங்களில் மாற்றங்கள் " +"செயல்படுத்தப்பட வேண்டும் என்று தேவைப்படுவதன் மூலம் பராமரிப்பை மிகவும் கடினமாக்குங்கள், " +"மேலும் இரண்டு பதிப்புகளும் எப்போதும் செயல்படுத்தப்படுவதை உறுதிசெய்ய சோதனை தொகுப்பில் " +"கூடுதல் சிக்கலை அறிமுகப்படுத்துகின்றன." + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" +"பைனரி நீட்டிப்புகளை நம்புவதன் மற்றொரு தீமை என்னவென்றால், மாற்று இறக்குமதி வழிமுறைகள் " +"(சிப்ஃபைல்களிலிருந்து நேரடியாக தொகுதிகளை இறக்குமதி செய்யும் திறன் போன்றவை) " +"பெரும்பாலும் நீட்டிப்பு தொகுதிகளுக்கு வேலை செய்யாது (பெரும்பாலான தளங்களில் மாறும் " +"ஏற்றுதல் வழிமுறைகள் வட்டில் இருந்து நூலகங்களை மட்டுமே ஏற்ற முடியும்)." + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "ஏண்ட்கோட் செய்யப்பட்ட முடுக்கி தொகுதிகளுக்கு மாற்று வழிகள்" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" +"குறியீட்டை வேகமாக இயக்க நீட்டிப்பு தொகுதிகள் பயன்படுத்தப்படும்போது (விவரக்குறிப்பு கூடுதல் " +"பராமரிப்பு முயற்சிக்கு மதிப்புள்ள குறியீட்டை விவரக்குறிப்பு அடையாளம் கண்டுள்ள பிறகு), பல " +"மாற்றுகளும் கருத்தில் கொள்ளப்பட வேண்டும்:" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" +"இருக்கும் உகந்த மாற்றுகளைத் தேடுங்கள். CPython நிலையான நூலகத்தில் பல உகந்த தரவு " +"கட்டமைப்புகள் மற்றும் வழிமுறைகள் (குறிப்பாக பில்டின்ச் மற்றும் `` சேகரிப்புகள்` மற்றும் `` " +"itertools`` தொகுதிகள்) உள்ளன. பைதான் தொகுப்பு குறியீடு கூடுதல் மாற்றுகளையும் " +"வழங்குகிறது. சில நேரங்களில், நிலையான நூலகம் அல்லது மூன்றாம் தரப்பு தொகுதியின் " +"பொருத்தமான தேர்வு உங்கள் சொந்த முடுக்கி தொகுதியை உருவாக்க வேண்டிய அவசியத்தைத் " +"தவிர்க்கலாம்." + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" +"க்கு long running applications, the JIT compiled `PyPy interpreter `__ சி-வைகாசி offer a suitable alternative பெறுநர் the தரநிலை " +"CPython runtime. The main barrier பெறுநர் adopting PyPy is typically reliance " +"on மற்றொன்று இருமம் extension தொகுதிகள் - while PyPy does emulate the CPython C " +"பநிஇ, தொகுதிகள் that rely on that cause problems க்கு the PyPy JIT, and the " +"போன்மம் layer can often expose latent defects in extension தொகுதிகள் that " +"CPython currently tolerates (frequently around குறிப்பு counting errors - an " +"பொருள் having one live குறிப்பு instead of two often won't இடைவேளை anything, " +"but இல்லை குறிப்புகள் instead of one is a major problem)." + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" +"`சித்தான் ____ என்பது ஒரு முதிர்ந்த நிலையான தொகுப்பி, இது சி " +"நீட்டிப்பு தொகுதிகளில் பெரும்பாலான பைதான் குறியீட்டை தொகுக்க முடியும். ஆரம்ப தொகுப்பு " +"சில வேக அதிகரிப்புகளை வழங்குகிறது (சிபிதான் மொழிபெயர்ப்பாளர் அடுக்கைத் தவிர்ப்பதன் " +"மூலம்), மற்றும் சைதனின் விருப்ப நிலையான தட்டச்சு நற்பொருத்தங்கள் வேக அதிகரிப்புக்கு " +"கூடுதல் வாய்ப்புகளை வழங்கும். சைதனைப் பயன்படுத்துவது பைனரி நீட்டிப்புகளைப் " +"பயன்படுத்துவதோடு தொடர்புடைய `தீமைகள்`_ ஐக் கொண்டுள்ளது, ஆனால் பைதான் புரோகிராமர்களுக்கான " +"நுழைவதற்கு குறைக்கப்பட்ட தடையைக் கொண்டிருப்பதன் நன்மையைக் கொண்டுள்ளது (சி அல்லது சி ++ " +"போன்ற பிற மொழிகளுடன் ஒப்பிடும்போது)." + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" +"`Numba ` __ என்பது ஒரு புதிய கருவியாகும், இது விஞ்ஞான " +"பைதான் சமூகத்தின் உறுப்பினர்களால் உருவாக்கப்பட்டது, இது ஒரு பைதான் பயன்பாட்டின் துண்டுகளை " +"தேர்ந்தெடுக்கப்பட்ட தொகுப்பை சொந்த இயந்திரக் குறியீட்டிற்கு அனுமதிக்க எல்.எல்.வி.எம் இயக்க " +"நேரம். குறியீடு இயங்கும் கணினியில் எல்.எல்.வி.எம் கிடைக்க வேண்டும், ஆனால் குறிப்பிடத்தக்க " +"வேக அதிகரிப்புகளை வழங்க முடியும், குறிப்பாக திசையன்மயமாக்கலுக்கு ஏற்ற செயல்பாடுகளுக்கு." + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "ஏண்ட்கோட் செய்யப்பட்ட ரேப்பர் தொகுதிகளுக்கு மாற்று வழிகள்" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" +"சி பநிஇ (பயன்பாட்டு பைனரி இடைமுகம்) பல பயன்பாடுகளுக்கு இடையில் செயல்பாட்டைப் " +"பகிர்வதற்கான பொதுவான தரமாகும். Cpython C பநிஇ (பயன்பாட்டு நிரலாக்க இடைமுகம்) இன் " +"பலங்களில் ஒன்று பைத்தான் பயனர்களை அந்த செயல்பாட்டைத் தட்ட அனுமதிக்கிறது. இருப்பினும், " +"தொகுதிகளை கையால் மடக்குவது மிகவும் கடினமானது, எனவே பல மாற்று அணுகுமுறைகள் கருத்தில் " +"கொள்ளப்பட வேண்டும்." + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" +"கீழே விவரிக்கப்பட்டுள்ள அணுகுமுறைகள் விநியோக வழக்கை எளிதாக்குவதில்லை, ஆனால் அவை " +"போர்வுற்ற தொகுதிகளை புதுப்பித்த நிலையில் வைத்திருப்பதற்கான பராமரிப்பு சுமையை கணிசமாகக் " +"குறைக்க முடியும்." + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" +"முடுக்கி தொகுதிகள் உருவாக்க பயனுள்ளதாக இருப்பதோடு மட்டுமல்லாமல், சி அல்லது சி ++ " +"ஏபிஐகளுக்கான ரேப்பர் தொகுதிகள் உருவாக்க சைதான் __ __ பரவலாகப் " +"பயன்படுத்தப்படுகிறது. இது இடைமுகங்களை கையால் போர்த்துவதை உள்ளடக்கியது, இது ரேப்பர் " +"குறியீட்டை வடிவமைத்து மேம்படுத்துவதில் பரந்த அளவிலான சுதந்திரத்தை அளிக்கிறது, ஆனால் " +"மிகப் பெரிய ஏபிஐக்களை விரைவாக மடக்குவதற்கு நல்ல தேர்வாக இருக்காது. மூன்றாம் தரப்பு " +"கருவிகளின் பட்டியலைப் பார்க்கவும் " +"`_ சைதனுடன் தானியங்கி மடக்குதல். பைபி மற்றும் பிச்டன் போன்ற சிபிதான் போன்ற சி-ஏபிஐ " +"வழங்கும் செயல்திறன் சார்ந்த பைதான் செயலாக்கங்களையும் இது ஆதரிக்கிறது." + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" +". இதற்கு முன் செயலாக்க படி தேவையில்லை; இது முற்றிலும் வார்ப்புரு சி ++ இல் " +"எழுதப்பட்டுள்ளது. செட்டுப்டூல்கள் அல்லது செமேக் கட்டமைப்புகளுக்கு உதவியாளர்கள் " +"சேர்க்கப்பட்டுள்ளனர். இது `boost.python __, ஆனால் பூச்ட் நூலகங்கள் அல்லது பிசாம் " +"தேவையில்லை ." + +#: ../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 "" +". சி தொகுதியை அதன் தலைப்பு கோப்புகளின் அடிப்படையில் மடிக்க இது ஒப்பீட்டளவில் " +"நேரடியானதாக அமைகிறது." + +#: ../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." +msgstr "" +"`` Cffi`` இன் முக்கிய நன்மைகளில் ஒன்று, இது பைபி JIT உடன் இணக்கமானது, இது CFFI " +"ரேப்பர் தொகுதிகள் பைபியின் தடமறியும் JIT மேம்படுத்தல்களில் முழுமையாக பங்கேற்க " +"அனுமதிக்கிறது." + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" +"`ச்விக் ____ என்பது ஒரு ரேப்பர் இடைமுக செனரேட்டர் ஆகும், இது " +"பைதான் உள்ளிட்ட பல்வேறு நிரலாக்க மொழிகளை சி மற்றும் சி ++ குறியீட்டுடன் இடைமுகப்படுத்த " +"அனுமதிக்கிறது." + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" +"நிலையான நூலகத்தின் `` ctypes`` தொகுதி, தலைப்பு செய்தி கிடைக்காதபோது சி நிலை " +"இடைமுகங்களை அணுகுவதற்கு பயனுள்ளதாக இருக்கும்போது, அது சி பநிஇ மட்டத்தில் மட்டுமே " +"இயங்குகிறது என்பதன் மூலம் பாதிக்கப்படுகிறது, இதனால் எந்த தானியங்கி நிலைத்தன்மையும் இல்லை " +"இடைமுகம் உண்மையில் நூலகத்தால் ஏற்றுமதி செய்யப்படுகிறது மற்றும் பைதான் குறியீட்டில் " +"அறிவிக்கப்பட்ட ஒன்று. இதற்கு நேர்மாறாக, மேலே உள்ள மாற்றுகள் அனைத்தும் சி * பநிஇ * " +"மட்டத்தில் செயல்பட முடியும், சி தலைப்பு கோப்புகளைப் பயன்படுத்தி நூலகத்தால் ஏற்றுமதி " +"செய்யப்படும் இடைமுகத்திற்கும் பைதான் ரேப்பர் தொகுதியால் எதிர்பார்க்கப்படுவதற்கும் இடையிலான " +"நிலைத்தன்மையை உறுதிசெய்கிறது. `` Cffi`` * * சி பநிஇ மட்டத்தில் நேரடியாக செயல்பட " +"முடியும் என்றாலும், அது அந்த வழியில் பயன்படுத்தப்படும்போது அதே இடைமுக முரண்பாடு " +"சிக்கல்களால் `` ctypes`` போன்றவற்றால் பாதிக்கப்படுகிறது." + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "குறைந்த அளவிலான கணினி அணுகலுக்கான மாற்று வழிகள்" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" +"குறைந்த அளவிலான கணினி அணுகல் தேவைப்படும் பயன்பாடுகளுக்கு (காரணத்தைப் பொருட்படுத்தாமல்), " +"ஒரு பைனரி நீட்டிப்பு தொகுதி பெரும்பாலும் * அதைப் பற்றிச் செல்ல சிறந்த வழியாகும். " +"சிபிதான் இயக்க நேரத்திற்கான குறைந்த அளவிலான அணுகலுக்கு இது குறிப்பாக உண்மை, ஏனெனில் " +"சில செயல்பாடுகள் (உலகளாவிய மொழிபெயர்ப்பாளர் பூட்டை வெளியிடுவது போன்றவை) " +"மொழிபெயர்ப்பாளர் குறியீட்டை இயக்கும்போது வெறுமனே செல்லாது, `` ctypes`` அல்லது `` " +"cffi` போன்ற ஒரு தொகுதி கூட இருந்தாலும் கூட தொடர்புடைய சி பநிஇ இடைமுகங்களுக்கான " +"அணுகலைப் பெற `பயன்படுத்தப்படுகிறது." + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" +"நீட்டிப்பு தொகுதி அடிப்படை இயக்க முறைமை அல்லது வன்பொருளைக் கையாளும் சந்தர்ப்பங்களுக்கு " +"(சிபிதான் இயக்க நேரத்தை விட), சில நேரங்களில் ஒரு சாதாரண சி நூலகத்தை எழுதுவது நல்லது " +"(அல்லது சி ++ அல்லது ஏற்றுமதி செய்யக்கூடிய ரச்ட் போன்ற மற்றொரு கணினி நிரலாக்க மொழியில் " +"ஒரு நூலகம் ஒரு சி இணக்கமான ஏபிஐ), பின்னர் மேலே விவரிக்கப்பட்ட மடக்குதல் நுட்பங்களில் " +"ஒன்றைப் பயன்படுத்தி இடைமுகத்தை இறக்குமதி செய்யக்கூடிய பைதான் தொகுதியாகக் கிடைக்கச் " +"செய்யுங்கள்." + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "பைனரி நீட்டிப்புகளை செயல்படுத்துகிறது" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" +"Cpython: doc: `விரிவாக்குதல் மற்றும் உட்பொதித்தல் <பைதான்: விரிவாக்குதல்/குறியீட்டு>` " +"வழிகாட்டியை எழுதுவதற்கான ஒரு அறிமுகம் அடங்கும்: doc: `C <பைதானில் தனிப்பயன் நீட்டிப்பு " +"தொகுதி: நீட்டித்தல்/நீட்டித்தல்>`." + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" +"Fixme: உங்கள் நீட்டிப்பு தொகுதிகளை நீங்கள் கையால் வைக்க விரும்பாததற்கு இவை அனைத்தும் ஒரு " +"காரணம் என்பதை விரிவாகக் கூறுங்கள் :)" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "நீட்டிப்பு தொகுதி வாழ்க்கை சுழற்சி" + +#: ../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/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "பகிரப்பட்ட நிலையான நிலை மற்றும் துணை விளக்கக்காரர்களின் தாக்கங்கள்" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "கிலின் தாக்கங்கள்" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "நினைவக ஒதுக்கீடு பநிஇ கள்" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "ABI பொருந்தக்கூடிய தன்மை" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" +"சிறிய வெளியீடுகளுக்கு (3.2, 3.3, 3.4, முதலியன) இடையே பநிஇ நிலைத்தன்மைக்கு சிபிதான் " +"சி பநிஇ பொறுப்பு அளிக்காது. இதன் பொருள், பொதுவாக, பைத்தானின் ஒரு பதிப்பிற்கு எதிராக " +"நீட்டிப்பு தொகுதியை நீங்கள் உருவாக்கினால், பைத்தானின் அதே சிறிய பதிப்போடு வேலை செய்வது " +"மட்டுமே பொறுப்பு அளிக்கப்படுகிறது, வேறு எந்த சிறிய பதிப்புகளுடனும் அல்ல." + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" +"பைதான் 3.2 வரையறுக்கப்பட்ட பநிஇ ஐ அறிமுகப்படுத்தியது, இது பைத்தானின் சி பநிஇ நன்கு " +"வரையறுக்கப்பட்ட துணைக்குழு ஆகும். வரையறுக்கப்பட்ட பநிஇ க்கு தேவையான சின்னங்கள் \"நிலையான " +"ABI\" ஐ உருவாக்குகின்றன, இது அனைத்து பைதான் 3.x பதிப்புகளிலும் இணக்கமாக இருக்கும் " +"என்று பொறுப்பு அளிக்கப்படுகிறது. நிலையான ஏபிஐக்கு எதிராக கட்டப்பட்ட நீட்டிப்புகளைக் கொண்ட " +"சக்கரங்கள் `` அபி 3`` பநிஇ குறிச்சொல்லைப் பயன்படுத்துகின்றன, அவை அனைத்து பைதான் 3. ஃச் " +"பதிப்புகளுடன் பொருந்தக்கூடியவை என்பதை பிரதிபலிக்க." + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" +"Cpythons: Doc: `C பநிஇ நிலைத்தன்மை <பைதான்: சி-ஏபிஐ / ச்டேபிள்>` பக்கம் பநிஇ / பநிஇ " +"ச்திரத்தன்மை உத்தரவாதங்கள், வரையறுக்கப்பட்ட பநிஇ மற்றும் \"வரையறுக்கப்பட்ட பநிஇ\" இன் " +"சரியான உள்ளடக்கங்களை எவ்வாறு பயன்படுத்துவது என்பது பற்றிய விரிவான தகவல்களை வழங்குகிறது." + +#: ../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: கட்டிட நீட்டிப்புகளுக்கு கிடைக்கக்கூடிய பில்ட்-பேக்கெண்டுகளை மறைக்கவும்." + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "பல தளங்களுக்கான நீட்டிப்புகளை உருவாக்குதல்" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" +"உங்கள் நீட்டிப்பை விநியோகிக்க நீங்கள் திட்டமிட்டால், நீங்கள் வழங்க வேண்டும்: கால: `சக்கரங்கள் " +"` நீங்கள் ஆதரிக்க விரும்பும் அனைத்து தளங்களுக்கும். இவை பொதுவாக தொடர்ச்சியான " +"ஒருங்கிணைப்பு (சிஐ) அமைப்புகளில் கட்டப்பட்டுள்ளன. தொஒ இலிருந்து அதிக மறுபகிர்வு " +"செய்யக்கூடிய இருமங்களை உருவாக்க உதவும் கருவிகள் உள்ளன; இவை பின்வருவனவற்றை " +"உள்ளடக்குகின்றன: ref: `cibuildwheel` மற்றும்: ref:` மல்டிபில்ட்`." + +#: ../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::" +msgstr "" +"பெரும்பாலான நீட்டிப்புகளுக்கு, நீங்கள் ஆதரிக்க விரும்பும் அனைத்து தளங்களுக்கும் சக்கரங்களை " +"உருவாக்க வேண்டும். இதன் பொருள் நீங்கள் உருவாக்க வேண்டிய சக்கரங்களின் எண்ணிக்கை ::" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" +"Cpython ஐப் பயன்படுத்துதல்: ref: `நிலையான அபி ` நீங்கள் வழங்க " +"வேண்டிய சக்கரங்களின் எண்ணிக்கையை கணிசமாகக் குறைக்க உதவும், ஏனெனில் ஒரு மேடையில் ஒரு " +"சக்கரத்தை அனைத்து பைதான் சிறிய பதிப்புகளிலும் பயன்படுத்தலாம்; மேட்ரிக்சின் ஒரு பரிமாணத்தை " +"நீக்குகிறது. பைத்தானின் ஒவ்வொரு புதிய சிறிய பதிப்பிற்கும் புதிய சக்கரங்களை உருவாக்க " +"வேண்டிய அவசியத்தையும் இது நீக்குகிறது." + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "சாளரங்களுக்கான பைனரி நீட்டிப்புகள்" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" +"பைனரி நீட்டிப்பை உருவாக்குவதற்கு முன், உங்களிடம் பொருத்தமான தொகுப்பி கிடைப்பதை உறுதி " +"செய்வது தேவை. சாளரங்களில், விசுவல் சி அதிகாரப்பூர்வ CPyThon மொழிபெயர்ப்பாளரை உருவாக்க " +"பயன்படுகிறது, மேலும் இணக்கமான பைனரி நீட்டிப்புகளை உருவாக்க பயன்படுத்தப்பட வேண்டும். " +"பைனரி நீட்டிப்புகளுக்கு ஒரு உருவாக்க சூழலை அமைக்க, `விசுவல் ச்டுடியோ சமூக பதிப்பை " +" __ __ - எந்த அண்மைக் கால " +"பதிப்பும் நன்றாக உள்ளது." + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" +"ஒரு எச்சரிக்கை: நீங்கள் விசுவல் ச்டுடியோ 2019 அல்லது அதற்குப் பிறகு பயன்படுத்தினால், உங்கள் " +"நீட்டிப்பு ஒரு \"கூடுதல்\" கோப்பைப் பொறுத்தது, `` vcruntime140_1.dll``, `` " +"vcruntime140.dll`` உடன் கூடுதலாக 2015 க்கு முந்தைய அனைத்து பதிப்புகளும் சார்ந்துள்ளது " +"ஆன். இந்த கூடுதல் கோப்பை சேர்க்காத CPyThon இன் பதிப்புகளில் உங்கள் நீட்டிப்பைப் " +"பயன்படுத்துவதற்கு இது கூடுதல் தேவையைச் சேர்க்கும். இதைத் தவிர்க்க, நீங்கள் தொகுக்கும் நேர " +"வாதத்தை ``/d2fh4 -`` சேர்க்கலாம். பைத்தானின் அண்மைக் கால பதிப்புகளில் இந்த கோப்பை " +"உள்ளடக்கியிருக்கலாம்." + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" +"3.5 க்கு முன்னர் பைத்தானைக் கட்டுவது ஊக்கமளிக்கிறது, ஏனெனில் விசுவல் ச்டுடியோவின் பழைய " +"பதிப்புகள் மைக்ரோசாப்டிலிருந்து இனி கிடைக்காது. பழைய பதிப்புகளை நீங்கள் உருவாக்க வேண்டும் " +"என்றால், நீங்கள் `` distutils_use_sdk = 1` மற்றும் `` mssdk = 1`` ஆகியவற்றை " +"அமைக்கலாம், தற்போது செயல்படுத்தப்பட்ட MSVC இன் பதிப்பைக் கண்டுபிடிக்கும்படி " +"கட்டாயப்படுத்தலாம், மேலும் உங்கள் நீட்டிப்பை வடிவமைக்கும்போது கவனிப்பைப் பயன்படுத்த வேண்டும் " +"வெவ்வேறு நூலகங்களில் மல்லோக்/இலவச நினைவகத்திற்கு அல்ல, மாற்றப்பட்ட தரவு கட்டமைப்புகளை " +"நம்புவதைத் தவிர்க்கவும், மற்றும் பல. நீட்டிப்பு தொகுதிகளை உருவாக்குவதற்கான கருவிகள் " +"பொதுவாக உங்களுக்காக இந்த விசயங்களைத் தவிர்க்கின்றன." + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "லினக்சிற்கான பைனரி நீட்டிப்புகள்" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" +"லினக்ச் பைனரிகள் பழைய விநியோகங்களுடன் இணக்கமாக இருக்க போதுமான பழைய GLIBC ஐப் " +"பயன்படுத்த வேண்டும். `மேனிலினக்ச் ` _ கப்பல்துறை " +"படங்கள் பொதுவான கட்டமைப்புகளில் பெரும்பாலான தற்போதைய லினக்ச் விநியோகங்களை ஆதரிக்கும் " +"அளவுக்கு ஒரு GLIBC உடன் உருவாக்கும் சூழலை வழங்குகின்றன." + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "MACOS க்கான பைனரி நீட்டிப்புகள்" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" +"மாகோ களில் பைனரி பொருந்தக்கூடிய தன்மை இலக்கு குறைந்தபட்ச வரிசைப்படுத்தல் முறையால் " +"தீர்மானிக்கப்படுகிறது, எ.கா. *10. செட்டுப்டூல்கள் / தொலைதூரங்களுடன் கட்டும் போது, " +"வரிசைப்படுத்தல் இலக்கு ``-பிளாட்-பெயர்``, எ.கா. `` MACOSX-10.9-X86_64``. மேகோச் " +"பைதான் விநியோகங்களுக்கான பொதுவான வரிசைப்படுத்தல் இலக்குகளுக்கு, `மேக்பிதான் ச்பின்னிங் " +"சக்கரங்கள் விக்கி ` _." + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "பைனரி நீட்டிப்புகளை வெளியிடுகிறது" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" +"PYPI மூலம் பைனரி நீட்டிப்புகளை வெளியிடுவது தூய பைதான் தொகுப்புகளை வெளியிடுவது போன்ற " +"அதே பதிவேற்ற வழிமுறைகளைப் பயன்படுத்துகிறது. பில்ட்-பேக்கெண்டைப் பயன்படுத்தி உங்கள் " +"நீட்டிப்புக்கு ஒரு சக்கரக் கோப்பை உருவாக்கி, அதை பைபியில் பதிவேற்றவும்: டாக்: `ட்வைன் " +"<கயிறு: குறியீட்டு>`." + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "பைனரி மட்டும் வெளியீடுகளைத் தவிர்க்கவும்" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" +"உங்கள் பைனரி நீட்டிப்புகளையும் அவற்றை உருவாக்கப் பயன்படுத்தப்பட்ட மூலக் குறியீடும் வெளியிட " +"வேண்டும் என்று கடுமையாக பரிந்துரைக்கப்படுகிறது. பயனர்கள் தேவைப்பட்டால் மூலத்திலிருந்து " +"நீட்டிப்பை உருவாக்க இது அனுமதிக்கிறது. குறிப்பிடத்தக்க வகையில், டிச்ட்ரோ தொகுப்பு " +"களஞ்சியங்களுக்கான சொந்த உருவாக்க அமைப்புகளுக்குள் மூலத்திலிருந்து உருவாக்கும் சில லினக்ச் " +"விநியோகங்களுக்கு இது தேவைப்படுகிறது." + +#: ../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 "" +"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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "ச்கிகிட்-கட்டமைப்போடு குறுக்கு-தளம் சக்கர விளைவாக்கம்" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" +"`Scikit-build _ _ தொகுப்பு " +"சுருக்க குறுக்கு-தளம் உருவாக்கும் செயல்பாடுகளுக்கு உதவுகிறது மற்றும் பைனரி நீட்டிப்பு " +"தொகுப்புகளை உருவாக்கும்போது கூடுதல் திறன்களை வழங்குகிறது. கூடுதல் ஆவணங்கள் `சி இயக்க " +"நேரம், கம்பைலர் மற்றும் உருவாக்க கணினி செனரேட்டர் ` _ பைதான் பைனரி விரிவாக்க " +"தொகுதிகளிலும் கிடைக்கிறது." + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "சி/சி ++ நீட்டிப்பு தொகுதிகள் அறிமுகம்" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" +"டெபியன் அமைப்பில் CPython ஆல் நீட்டிப்பு தொகுதிகள் எவ்வாறு பயன்படுத்தப்படுகின்றன என்பதற்கான " +"ஆழமான விளக்கத்திற்கு, பின்வரும் கட்டுரைகளைப் பார்க்கவும்:" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "`(சி) பைதான் நீட்டிப்பு தொகுதிகள் என்றால் என்ன? இப்போது" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "`கில் ` _" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "C ++ `_" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "பைனரி சக்கரங்களுக்கான கூடுதல் பரிசீலனைகள்" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" +"`Pypackaging-native ` _ வலைத்தளமானது " +"பைதான் தொகுப்புகளை சொந்தக் குறியீட்டைக் கொண்டு பேக்கேசிங் செய்வதில் கூடுதல் பாதுகாப்பு " +"உள்ளது. ஆழ்ந்த விளக்கங்கள் மற்றும் குறிப்புகளுடன், இதுபோன்ற திட்டங்களுக்கு மிக முக்கியமான " +"பேக்கேசிங் சிக்கல்களின் கண்ணோட்டத்தை வழங்குவதை இது நோக்கமாகக் கொண்டுள்ளது." + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" +"பைதான் அல்லாத தொகுக்கப்பட்ட சார்புநிலைகள் (\"சொந்த சார்புநிலைகள்\"), சொந்தக் குறியீட்டின் " +"பநிஇ (பயன்பாட்டு பைனரி இடைமுகம்), சிம்ட் குறியீட்டின் சார்பு மற்றும் குறுக்கு தொகுப்பு " +"ஆகியவற்றின் முக்கியத்துவம்." + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "பேக்கேசிங் பெயர்வெளி தொகுப்புகள்" + +#: ../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 "" +"பெயரளவிலான தொகுப்புகள் துணை பேக்குகள் மற்றும் தொகுதிகளை ஒரு ஒற்றை: காலத்திற்குள் " +"பிரிக்க உங்களை அனுமதிக்கின்றன: `தொகுப்பு <இறக்குமதி தொகுப்பு>` பல, தனி: கால: " +"`விநியோக தொகுப்புகள் <விநியோக தொகுப்பு>` (** விநியோகங்கள் ** என குறிப்பிடப்படுகின்றன " +"தெளிவற்ற தன்மையைத் தவிர்க்க இந்த ஆவணம்). எடுத்துக்காட்டாக, உங்களிடம் பின்வரும் தொகுப்பு " +"அமைப்பு இருந்தால்:" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "இந்த தொகுப்பை உங்கள் குறியீட்டில் பயன்படுத்துகிறீர்கள் ::" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "இந்த துணை தொகுப்புகளை நீங்கள் இரண்டு தனித்தனி விநியோகங்களாக உடைக்கலாம்:" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" +"ஒவ்வொரு துணைத் தொகுப்பையும் இப்போது தனித்தனியாக நிறுவலாம், பயன்படுத்தலாம் மற்றும் பதிப்பு " +"செய்யலாம்." + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" +"தளர்வான தொடர்புடைய தொகுப்புகளின் பெரிய சேகரிப்புக்கு பெயர்வெளி தொகுப்புகள் பயனுள்ளதாக " +"இருக்கும் (ஒரு நிறுவனத்திடமிருந்து பல தயாரிப்புகளுக்கான கிளையன்ட் நூலகங்களின் பெரிய " +"கார்பச் போன்றவை). இருப்பினும், பெயர்வெளி தொகுப்புகள் பல எச்சரிக்கைகளுடன் வருகின்றன, அவை " +"எல்லா நிகழ்வுகளிலும் பொருத்தமானவை அல்ல. ஒரு எளிய மாற்று என்னவென்றால், `` " +"mynamespace_subpackage_a`` போன்ற உங்கள் விநியோகங்கள் அனைத்திலும் ஒரு முன்னொட்டைப் " +"பயன்படுத்துவது (நீங்கள் `` mynamespace_subpackage_a ஐ subpackage_a ஆக இறக்குமதி " +"செய்யலாம்) இறக்குமதி பொருளை குறுகியதாக வைத்திருக்க)." + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "பெயர்வெளி தொகுப்பை உருவாக்குதல்" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" +"பெயர்வெளி தொகுப்புகளை உருவாக்குவதற்கு தற்போது இரண்டு வெவ்வேறு அணுகுமுறைகள் உள்ளன, " +"அவற்றில் இருந்து பிந்தையது ஊக்கமளிக்கிறது:" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" +"`சொந்த பெயர்வெளி தொகுப்புகள்`_ ஐப் பயன்படுத்தவும். இந்த வகை பெயர்வெளி தொகுப்பு இதில் " +"வரையறுக்கப்பட்டுள்ளது: PEP: `420` மற்றும் பைதான் 3.3 மற்றும் அதற்குப் பிறகு கிடைக்கிறது. " +"உங்கள் பெயர்வெளியில் உள்ள தொகுப்புகள் எப்போதாவது பைதான் 3 மற்றும் நிறுவலை `` பிப்`` " +"வழியாக மட்டுமே ஆதரிக்க வேண்டும் என்றால் இது பரிந்துரைக்கப்படுகிறது." + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" +"`மரபு பெயர்வெளி தொகுப்புகள்`_ ஐப் பயன்படுத்தவும். இது `pkgutil- பாணி பெயர்வெளி " +"தொகுப்புகள்`_ மற்றும்` pkg_resources- பாணி பெயர்வெளி தொகுப்புகள்`_ ஆகியவற்றைக் " +"கொண்டுள்ளது." + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "சொந்த பெயர்வெளி தொகுப்புகள்" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" +"பைதான் 3.3 சேர்க்கப்பட்டது ** மறைமுக ** பெயர்வெளி தொகுப்புகள்: பெப்: `420`. ஒரு சொந்த " +"பெயர்வெளி தொகுப்பை உருவாக்க தேவையானது என்னவென்றால், நீங்கள் தவிர்க்கவும்: கோப்பு: `__init " +"__. பெயர்வெளி தொகுப்பு கோப்பகத்திலிருந்து. ஒரு எடுத்துக்காட்டு கோப்பு அமைப்பு " +"(பின்வருமாறு: குறிப்பு: `எச்.ஆர்.சி-லேஅவுட் <செட்டப்டூல்ச்: எச்.ஆர்.சி-லேஅவுட்>`):" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" +"பெயர்வெளி தொகுப்பைப் பயன்படுத்தும் ஒவ்வொரு விநியோகமும் பின்வாங்குவது மிகவும் முக்கியம்: " +"கோப்பு: `__init __. Py` அல்லது pkgutil- பாணியைப் பயன்படுத்துகிறது: கோப்பு:` __init " +"__. Py`. எந்தவொரு விநியோகமும் இல்லையென்றால், அது பெயர்வெளி வழக்கு தோல்வியடையும், மற்ற " +"துணை தொகுப்புகள் இறக்குமதி செய்யப்படாது." + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" +"`` எச்.ஆர்.சி-லேஅவுட்`` அடைவு அமைப்பு பெரும்பாலானவற்றால் தொகுப்புகளை தானாக " +"கண்டுபிடிப்பதை அனுமதிக்கிறது: கால: `பின்தளத்தில் உருவாக்கு <பின்தளத்தில் உருவாக்கு>`. " +"காண்க: குறிப்பு: மேலும் தகவலுக்கு `எச்.ஆர்.சி-லேஅவுட்-வி.எச்-பிளாட்-லேஅவுட்`. " +"எவ்வாறாயினும், தொகுப்புகளின் விலக்குகள் அல்லது சேர்த்தல்களை நீங்களே நிர்வகிக்க விரும்பினால், " +"இது உயர் மட்டத்தில் கட்டமைக்க முடியும்: கோப்பு: `pyproject.toml`:" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "ஒரு: கோப்பு: `setup.cfg`:" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "அல்லது: கோப்பு: `setup.py`:" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" +":ref:`setuptools` will தேடல் the directory structure க்கு implicit பெயர்வெளி " +"தொகுப்பு by default." + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" +"இரண்டு சொந்த பெயர்வெளி தொகுப்புகளின் முழுமையான வேலை உதாரணத்தை `சொந்த பெயர்வெளி " +"தொகுப்பு எடுத்துக்காட்டு திட்டம்`_ இல் காணலாம்." + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" +"பூர்வீக மற்றும் PKGUTIL- பாணி பெயர்வெளி தொகுப்புகள் பெரும்பாலும் இணக்கமானவை என்பதால், " +"பைத்தான் 2 மற்றும் 3 ஐ ஆதரிக்க வேண்டிய விநியோகங்களில் பைதான் 3 மற்றும் PKGUTIL- பாணி " +"பெயர்வெளி தொகுப்புகளை மட்டுமே ஆதரிக்கும் விநியோகங்களில் நீங்கள் சொந்த பெயர்வெளி " +"தொகுப்புகளைப் பயன்படுத்தலாம்." + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +msgstr "மரபு பெயர்வெளி தொகுப்புகள்" + +#: ../source/guides/packaging-namespace-packages.rst:160 +#, fuzzy +#| 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." +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 one of these " +"methods." +msgstr "" +"இதற்கு முன்னர் பெயர்வெளி தொகுப்புகளை உருவாக்கப் பயன்படுத்தப்பட்ட இந்த இரண்டு முறைகள்: PEP: " +"`420`, இப்போது வழக்கற்றுப் போய்விட்டதாகக் கருதப்படுகின்றன, மேலும் இந்த முறையைப் " +"பயன்படுத்தும் தொகுப்புகளுடன் உங்களுக்கு பொருந்தக்கூடிய தன்மை தேவைப்பட்டால் " +"பயன்படுத்தப்படக்கூடாது. மேலும், டிஓசி: `பி.கே." + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" +"ஏற்கனவே உள்ள தொகுப்பை இடம்பெயர, பெயர்வெளியைப் பகிரும் அனைத்து தொகுப்புகளும் ஒரே " +"நேரத்தில் இடம்பெயர வேண்டும்." + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" +"சொந்த பெயர்வெளி தொகுப்புகள் மற்றும் PKGUTIL- பாணி பெயர்வெளி தொகுப்புகள் பெரும்பாலும் " +"இணக்கமானவை என்றாலும், PKG_RESOURCES- பாணி பெயர்வெளி தொகுப்புகள் மற்ற முறைகளுடன் " +"பொருந்தாது. ஒரே பெயர்வெளிக்கு தொகுப்புகளை வழங்கும் வெவ்வேறு விநியோகங்களில் வெவ்வேறு " +"முறைகளைப் பயன்படுத்துவது தவிர்க்க முடியாதது." + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "Pkgutil- பாணி பெயர்வெளி தொகுப்புகள்" + +#: ../source/guides/packaging-namespace-packages.rst:175 +#, fuzzy +#| 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." +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" +"பைதான் 2.3 அறிமுகப்படுத்தியது: டாக்: `pkgutil ` தொகுதி " +"மற்றும்: py: func: `python: pkgutil.extend_path` செயல்பாடு. பைதான் 2.3+ மற்றும் " +"பைதான் 3 ஆகிய இரண்டிற்கும் இணக்கமாக இருக்க வேண்டிய பெயர்வெளி தொகுப்புகளை அறிவிக்க இதைப் " +"பயன்படுத்தலாம். இது மிக உயர்ந்த பொருந்தக்கூடிய அளவிற்கு பரிந்துரைக்கப்பட்ட " +"அணுகுமுறையாகும்." + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" +"ஒரு pkgutil- பாணி பெயர்வெளி தொகுப்பை உருவாக்க, நீங்கள் ஒரு: கோப்பு: `__init __. " +"பெயர்வெளி தொகுப்புக்கான கோப்பு:" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" +"தி: கோப்பு: `__init __. பெயர்வெளி தொகுப்புக்கான கோப்பு பின்வருவனவற்றைக் கொண்டிருக்க " +"வேண்டும்:" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" +"** பெயர்வெளி தொகுப்பைப் பயன்படுத்தும் ஒவ்வொரு ** விநியோகமும் அத்தகைய: கோப்பு: __init " +"__. Py`. எந்தவொரு விநியோகமும் இல்லையென்றால், அது பெயர்வெளி வழக்கு தோல்வியடையும், மற்ற " +"துணை தொகுப்புகள் இறக்குமதி செய்யப்படாது. ஏதேனும் கூடுதல் குறியீடு: கோப்பு: `__init " +"__. Py` அணுக முடியாததாக இருக்கும்." + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" +"இரண்டு Pkgutil- பாணி பெயர்வெளி தொகுப்புகளின் முழுமையான வேலை உதாரணத்தை `pkgutil " +"பெயர்வெளி எடுத்துக்காட்டு திட்டம்`_ இல் காணலாம்." + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "PKG_RESOURCES-பாணி பெயர்வெளி தொகுப்புகள்" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +#, fuzzy +#| 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." +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" +". பெயர்வெளி தொகுப்புகளை அறிவிக்க இவை ஒன்றாக பயன்படுத்தப்படலாம். இந்த அணுகுமுறை இனி " +"பரிந்துரைக்கப்படவில்லை என்றாலும், இது தற்போதுள்ள பெரும்பாலான பெயர்வெளி தொகுப்புகளில் " +"பரவலாக உள்ளது. இந்த முறையைப் பயன்படுத்தும் ஏற்கனவே உள்ள பெயர்வெளி தொகுப்புக்குள் நீங்கள் " +"ஒரு புதிய விநியோகத்தை உருவாக்குகிறீர்கள் என்றால், வெவ்வேறு முறைகள் குறுக்கு-இணக்கமானவை " +"அல்ல என்பதால் இதைப் பயன்படுத்த தொடர்ந்து பரிந்துரைக்கப்படுகிறது, மேலும் ஏற்கனவே உள்ள " +"தொகுப்பை இடம்பெயர முயற்சிப்பது நல்லதல்ல." + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" +"PKG_RESOURCES- பாணி பெயர்வெளி தொகுப்பை உருவாக்க, நீங்கள் ஒரு: கோப்பு: `__init __. " +"பெயர்வெளி தொகுப்புக்கான கோப்பு:" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" +"சில பழைய பரிந்துரைகள் பெயர்வெளி தொகுப்பில் பின்வருவனவற்றை அறிவுறுத்துகின்றன: கோப்பு: " +"`__init __. Py`:" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" +"இதன் பின்னணியில் உள்ள சிந்தனை என்னவென்றால், செட்டுப்டூல்ச் கிடைக்காத அரிதான விசயத்தில் " +"தொகுப்புகள் PKGUTIL- பாணி தொகுப்புகளுக்கு விழும். இது நல்லதல்ல, ஏனெனில் PKGUTIL " +"மற்றும் PKG_RESOURCES-பாணி பெயர்வெளி தொகுப்புகள் குறுக்கு இணக்கமானவை அல்ல. " +"செட்ப்டூல்களின் இருப்பு ஒரு கவலையாக இருந்தால், தொகுப்பு `` install_requires`` வழியாக " +"செட்டுப்டூல்களை வெளிப்படையாக சார்ந்து இருக்க வேண்டும்." + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" +"இறுதியாக, ஒவ்வொரு விநியோகமும் `` பெயர்வெளி_பேக்கேச்கள்` வாதத்தை வழங்க வேண்டும்: func: " +"`~ setuptools.setup` இல்: கோப்பு:` setup.py`. உதாரணமாக:" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" +"அறிவிலிமையம் செயல்கள் சிஐ/சிடி பணிப்பாய்வுகளைப் பயன்படுத்தி தொகுப்பு விநியோக " +"வெளியீடுகளை வெளியிடுகிறது" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" +"`கிட்அப் செயல்கள் சிஐ/சி.டி`_ அறிவிலிமையம் மேடையில் ஒரு நிகழ்வு நிகழும்போது " +"தொடர்ச்சியான கட்டளைகளை இயக்க உங்களை அனுமதிக்கிறது. ஒரு பிரபலமான தேர்வு ஒரு `` புச்`` " +"நிகழ்வால் தூண்டப்பட்ட ஒரு பணிப்பாய்வு. குறிக்கப்பட்ட உறுதிப்பாட்டைத் தள்ளும்போதெல்லாம் பைதான் " +"விநியோகத்தை எவ்வாறு வெளியிடுவது என்பதை இந்த வழிகாட்டி உங்களுக்குக் காட்டுகிறது. இது " +"வெளியீட்டிற்கு `பைபா/சிஎச்-ஆக்சன்-பைபி-வெளியீட்டு அறிவிலிமையம் அதிரடி`_ ஐப் " +"பயன்படுத்தும். மூல தொகுப்புகளை தற்காலிகமாக சேமித்து பதிவிறக்குவதற்கு இது கிதுபின் " +"`பதிவேற்ற-ஆர்டிஃபாக்ட்`_ மற்றும்` பதிவிறக்கம்-பார்ட்டிஃபாக்ட்`_ செயல்களையும் " +"பயன்படுத்துகிறது." + +#: ../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." +msgstr "" +"இந்த வழிகாட்டி *உங்களிடம் ஏற்கனவே ஒரு திட்டம் உள்ளது என்று கருதுகிறது. இந்த வழிகாட்டி " +"தளமான குறிப்பிட்ட திட்டங்களை உருவாக்குவதற்கான விவரங்களையும் தவிர்க்கிறது. உங்களிடம் " +"பைனரி கூறுகள் இருந்தால், பாருங்கள்: குறிப்பு: `cibuildwheel` இன் அறிவிலிமையம் அதிரடி " +"எடுத்துக்காட்டுகள்." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:25 +#, fuzzy +#| msgid "Configuring trusted publishing" +msgid "Configuring Trusted Publishing" +msgstr "நம்பகமான வெளியீட்டை உள்ளமைத்தல்" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:27 +#, fuzzy +#| 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." +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." +msgstr "" +"இந்த வழிகாட்டி `கிதுப் செயல்கள் CI/CD`_ உடன் இணைக்க PYPI இன்` நம்பகமான வெளியீடு`_ " +"செயல்படுத்தலை நம்பியுள்ளது. பாதுகாப்பு காரணங்களுக்காக இது பரிந்துரைக்கப்படுகிறது, " +"ஏனெனில் உங்கள் ஒவ்வொரு திட்டத்திற்கும் தனித்தனியாக உருவாக்கப்பட்ட டோக்கன்கள் உருவாக்கப்பட்டு " +"தானாகவே காலாவதியாகின்றன. இல்லையெனில், நீங்கள் PYPI மற்றும் TestPypi இரண்டிற்கும் `API " +"டோக்கன்`_ ஐ உருவாக்க வேண்டும். மூன்றாம் தரப்பு குறியீடுகளுக்கு வெளியிடினால்: DOC: " +"`devpi `, நீங்கள் ஒரு பயனர்பெயர்/கடவுச்சொல் கலவையை வழங்க " +"வேண்டியிருக்கலாம்." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +#, fuzzy +#| 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." +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." +msgstr "" +"இந்த வழிகாட்டி PYPI மற்றும் TestPypi இரண்டிலும் பதிவேற்றுவதை நிரூபிக்கும் என்பதால், " +"எங்களுக்கு கட்டமைக்கப்பட்ட இரண்டு நம்பகமான வெளியீட்டாளர்கள் தேவை. உங்கள் புதிய: கால: `PYPI " +"திட்டம் <திட்டம்>` `பைபி திட்டம்:` பைபி திட்டம்: `பைபி திட்டம்:` PYPI திட்டம்: `பைபி " +"திட்டம்:` பைபி திட்டம்: `பைபி திட்டம்:` பைபி திட்டம்: `பைபி திட்டம்: எவ்வாறாயினும், நீங்கள் " +"அதன் உரிமையாளராக இருந்தால், முன்பே இருக்கும் எந்தவொரு திட்டத்திலும் `நம்பகமான பப்ளிசிங்`_ " +"ஐச் சேர்க்கவும் முடியும்." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" +"இந்த வழிகாட்டியின் முந்தைய பதிப்புகளை நீங்கள் பின்பற்றினால், நேரடி பைபி மற்றும் டெச்ட்பிஐ " +"அணுகலுக்காக `` pypi_api_token`` மற்றும் `` test_pypi_api_token` ஆகியவற்றை நீங்கள் " +"உருவாக்கியுள்ளீர்கள். இவை இப்போது வழக்கற்றுப் போய்விட்டன, அவற்றை உங்கள் அறிவிலிமையம் " +"களஞ்சியத்திலிருந்து அகற்றி, உங்கள் பழைய அமைப்பை புதியதாக மாற்றினால் அவற்றை உங்கள் பைபி " +"மற்றும் டெச்ட்பிஐ கணக்கு அமைப்புகளில் ரத்து செய்ய வேண்டும்." + +#: ../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 "" +"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 "" +"உங்கள் புதியதை வெளியிட விரும்பும் பெயரை நிரப்பவும்: கால: `பைபி திட்டம் <திட்டம்>` கீழ் " +"(உங்கள் `` setup.cfg`` அல்லது `` pyproject.toml``), Kithub களஞ்சிய உரிமையாளரின் " +"பெயர் (org அல்லது பயனர்), மற்றும் களஞ்சிய பெயர், மற்றும் `` .github/`` இன் கீழ் வெளியீட்டு " +"பணிப்பாய்வு கோப்பின் பெயர் கோப்புறை, காண்க: குறிப்பு: `பணிப்பாய்வு-வரையறை`. இறுதியாக, " +"அறிவிலிமையம் சூழலின் பெயரைச் சேர்க்கவும் (`` பைபி``) நாங்கள் உங்கள் களஞ்சியத்தின் கீழ் " +"அமைக்கப் போகிறோம். நம்பகமான வெளியீட்டாளரை பதிவு செய்யுங்கள்." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" +"இப்போது, https://test.pypi.org/manage/account/publishing/ க்குச் சென்று இரண்டாவது " +"படியை மீண்டும் செய்யவும், ஆனால் இந்த நேரத்தில், அறிவிலிமையம் சூழலின் பெயராக `` " +"டெச்ட்பைபி`` ஐ உள்ளிடவும்." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" +"உங்கள் \"நிலுவையில் உள்ள\" வெளியீட்டாளர்கள் இப்போது அவர்களின் முதல் பயன்பாட்டிற்கு தயாராக " +"உள்ளனர், மேலும் நீங்கள் முதல் முறையாக அவற்றைப் பயன்படுத்தியவுடன் உங்கள் திட்டங்களை தானாக " +"உருவாக்கும்." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" +"உங்களிடம் டெச்ட்பை கணக்கு இல்லையென்றால், நீங்கள் அதை உருவாக்க வேண்டும். இது வழக்கமான PYPI " +"கணக்கைப் போலவே இல்லை." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:78 +#, fuzzy +#| msgid "" +#| "For security reasons, you must require `manual approval `_ on each " +#| "run for the ``pypi`` environment." +msgid "" +"For security reasons, you must require `manual approval `_ on each run for the ``pypi`` environment." +msgstr "" +"பாதுகாப்பு காரணங்களுக்காக, உங்களுக்கு `கையேடு ஒப்புதல் தேவை ` _ on ஒவ்வொன்றும் " +"`` பைபி`` சூழலுக்கு ஓடுகின்றன." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "பணிப்பாய்வு வரையறையை உருவாக்குதல்" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" +"Kithub CI/CD பணிப்பாய்வுகள் `` .github/பணிப்பாய்வு/`` உங்கள் களஞ்சியத்தின் கோப்பகத்தில் " +"சேமிக்கப்பட்ட YAML கோப்புகளில் அறிவிக்கப்படுகின்றன." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +#, fuzzy +#| msgid "Let's create a ``.github/workflows/publish-to-test-pypi.yml`` file." +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "`` .Github/பணிப்பாய்வு/வெளியீடு-க்கு-சோதனை-pypi.yml`` கோப்பை உருவாக்குவோம்." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" +"இதை ஒரு அர்த்தமுள்ள பெயருடன் தொடங்கி, இந்த பணிப்பாய்வுகளை அறிவிலிமையம் இயக்க வேண்டிய " +"நிகழ்வை வரையறுக்கவும்:" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" +"முறையே PYPI மற்றும் TestPypi க்கு வெளியிட இரண்டு வேலைகள் மற்றும் விநியோக தொகுப்புகளை " +"உருவாக்க கூடுதல் வேலை ஆகியவற்றை வரையறுக்க வேண்டும்." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" +"முதலில், உங்கள் திட்டத்தின் தொலைதூர தொகுப்புகளை உருவாக்குவதற்கும் அவற்றை பின்னர் பயன்படுத்த " +"சேமிப்பதற்கும் வேலையை வரையறுப்போம்:" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" +"இது உங்கள் களஞ்சியத்தை தொஒ ரன்னரில் பதிவிறக்கம் செய்து பின்னர் கிடைக்கக்கூடிய புதிய பைதான் " +"3 வெளியீட்டை நிறுவி செயல்படுத்தும்." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" +"இப்போது நாம் மூலத்திலிருந்து தொலைதூரங்களை உருவாக்கி அவற்றை சேமிக்க முடியும். இந்த " +"எடுத்துக்காட்டில், `` பில்ட்`` தொகுப்பைப் பயன்படுத்துவோம். எனவே இதை படிகள் பட்டியலில் " +"சேர்க்கவும்:" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "பணிப்பாய்வு வேலை சூழலை வரையறுத்தல்" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:130 +#, fuzzy +#| 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." +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 "" +"இப்போது, எங்கள் வேலைக்கு ஆரம்ப அமைப்பைச் சேர்ப்போம், அது பைபிக்கு வெளியிடப்படும். இது ஒரு " +"செயல்முறையாகும், இது நாங்கள் பின்னர் வரையறுக்கும் கட்டளைகளை இயக்கும். இந்த வழிகாட்டியில், " +"அறிவிலிமையம் செயல்களால் வழங்கப்பட்ட அண்மைக் கால நிலையான உபுண்டு எல்.டி.எச் பதிப்பைப் " +"பயன்படுத்துவோம். இது வேலை அதன் சூழலில் இயங்குவதற்கான ஒரு அறிவிலிமையம் சூழலையும், " +"கிட்அப்பின் இடைமுகம் இல் காண்பிக்கப்பட வேண்டிய முகவரி ஐயும் வரையறுக்கிறது. கூடுதலாக, `` " +"பைபி-பப்ளிச்`` நடவடிக்கைகள் பைபிக்கு ரகசியமற்ற நம்பகமான வெளியீட்டை செயல்படுத்த வேண்டும் " +"என்று ஓபன்ஐடி இணைப்பு கிள்ளாக்கைப் பெற அனுமதிக்கிறது." + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "PYPI க்கு விநியோகத்தை வெளியிடுகிறது" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" +"இந்த படி `பைபா/சிஎச்-ஆக்சன்-பிப்-பிபிலிச்`_ அறிவிலிமையம் செயலைப் பயன்படுத்துகிறது: " +"சேமிக்கப்பட்ட விநியோக தொகுப்பு` பதிவிறக்கம்-ஆர்டிஃபாக்ட்`_ செயலால் பதிவிறக்கம் செய்யப்பட்ட " +"பிறகு, இது `` மாவட்ட/`கோப்புறையின் உள்ளடக்கங்களை பதிவேற்றுகிறது நிபந்தனையின்றி " +"பைபிக்குள்." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "டெச்ட்பிபிக்கு வெளியிடுவதற்கு பணிப்பாய்வு தனி" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" +"இப்போது, இந்த படிகளை மீண்டும் செய்து, `` வேலைகள்`` பிரிவின் கீழ் டெச்ட்பை தொகுப்பு " +"குறியீட்டுக்கு வெளியிட மற்றொரு வேலையை உருவாக்கவும்:" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" +"`` டெச்ட்பை`` அறிவிலிமையம் சூழலில் கையேடு ஒப்புதல்கள் தேவைப்படுவது பொதுவாக " +"தேவையற்றது, ஏனெனில் இது முதன்மையான கிளைக்கு ஒவ்வொரு உறுதியிலும் இயங்க " +"வடிவமைக்கப்பட்டுள்ளது மற்றும் ஆரோக்கியமான வெளியீட்டு வெளியீட்டு குழாய்த்திட்டத்தைக் குறிக்க " +"பெரும்பாலும் பயன்படுத்தப்படுகிறது." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "முழு சிஐ/சிடி பணிப்பாய்வு" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" +"இந்த பத்தி மேலே உள்ள வழிகாட்டியைப் பின்பற்றிய பிறகு முழு பணிப்பாய்வுகளையும் காட்டுகிறது." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "அவ்வளவுதான், எல்லோரும்!" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" +"இப்போது, கிட்அப்பில் உங்கள் அறிவிலி களஞ்சிய ரிமோட்டிற்கு குறிக்கப்பட்ட உறுதிப்பாட்டை நீங்கள் " +"தள்ளும்போதெல்லாம், இந்த பணிப்பாய்வு அதை பைபிக்கு வெளியிடும். இது உங்கள் ஆல்பா பயனர்களுக்கு " +"சோதனை கட்டமைப்பை வழங்குவதற்கும், உங்கள் வெளியீட்டு குழாய் ஆரோக்கியமாக இருப்பதை " +"உறுதிசெய்வதற்கும் பயனுள்ளதாக இருக்கும் டெச்ட்பிபிக்கு எந்தவொரு உந்துதலையும் வெளியிடும்!" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" +"உங்கள் களஞ்சியத்தில் அடிக்கடி செயல்படும் செயல்பாடு இருந்தால், ஒவ்வொரு உந்துதலும் " +"விவரிக்கப்பட்டுள்ளபடி டெச்ட்பைட்டில் பதிவேற்றப்பட்டால், திட்டம் `PYPI திட்ட அளவு வரம்பை " +"` _. வரம்பை அதிகரிக்க முடியும், ஆனால் " +"ஒரு சிறந்த தீர்வு ஒரு பைபி-இணக்கமான சேவையகத்தைப் பயன்படுத்தலாம்: குறிப்பு நோக்கங்களுக்காக " +"தொஒ இல் `பைபிசெவர்`." + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" +"ஒருங்கிணைந்த அறிவிலிமையம் செயல்களை அவற்றின் அண்மைக் கால பதிப்புகளில் வைத்திருக்க " +"பரிந்துரைக்கப்படுகிறது, அவற்றை அடிக்கடி புதுப்பிக்கிறது." + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "கட்டிடம் மற்றும் வெளியீடு" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "ஓச்டிங்" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +msgid "Installation" +msgstr "நிறுவல்" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "0; முகவரி = ../../விவாதங்கள்/ஒற்றை-மூல பதிப்பு/" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "பழமையான ஒற்றை மூல தொகுப்பு பதிப்பு இணைப்பை திருப்பிவிடுதல் ..." + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "பக்கம் தானாகவே புதுப்பிக்கவில்லை என்றால், காண்க: குறிப்பு: `ஒற்றை-மூல-பதிப்பு`." + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "பல பைதான் பதிப்புகளை ஆதரிக்கிறது" + +#: ../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 "" +"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 "" +"பைதான் தொகுப்பை உருவாக்க தேவையான வேலைக்கு கூடுதலாக, பைத்தானின் வெவ்வேறு பதிப்புகளில் " +"தொகுப்பு கிடைக்க வேண்டும் என்பது பெரும்பாலும் தேவை. வெவ்வேறு பைதான் பதிப்புகளில் " +"வெவ்வேறு (அல்லது மறுபெயரிடப்பட்ட) நிலையான நூலக தொகுப்புகள் இருக்கலாம், மேலும் பைதான் " +"பதிப்புகள் 2.x மற்றும் 3.x க்கு இடையிலான மாற்றங்கள் மொழி தொடரியல் மாற்றங்களை " +"உள்ளடக்குகின்றன." + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" +"கைமுறையாக நிகழ்த்தப்பட்டது, அனைத்து இலக்கு பைதான் பதிப்புகளிலும் (மற்றும் OSS!) தொகுப்பு " +"சரியாக செயல்படுவதை உறுதிசெய்ய தேவையான அனைத்து சோதனைகளும் மிகவும் நேரத்தை " +"எடுத்துக்கொள்ளக்கூடும். அதிர்ச்டவசமாக, இதைக் கையாள்வதற்கு பல கருவிகள் கிடைக்கின்றன, இவை " +"சுருக்கமாக இங்கே விவாதிக்கப்படும்." + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "தானியங்கு சோதனை மற்றும் தொடர்ச்சியான ஒருங்கிணைப்பு" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" +"தானியங்கு சோதனைக்கு பல புரவலன் செய்யப்பட்ட சேவைகள் கிடைக்கின்றன. இந்த சேவைகள் பொதுவாக " +"உங்கள் மூலக் குறியீடு களஞ்சியத்தை கண்காணிக்கும் (எ.கா. கமிட் செய்யப்படுகிறது." + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" +"இந்த சேவைகள் பைதானின் பல பதிப்புகளில் உங்கள் திட்டத்தின் சோதனைத் தொகுப்பை இயக்குவதற்கான " +"வசதிகளையும் வழங்குகின்றன, மேலும் உருவாக்குபவர் அத்தகைய சோதனைகளைச் செய்யாமல், குறியீடு " +"செயல்படுமா என்பது குறித்த விரைவான கருத்துக்களை அளிக்கிறது." + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" +"விக்கிபீடியாவில் ஒரு விரிவான `ஒப்பீடு ` _ பல தொடர்ச்சியான-ஒருங்கிணைப்பு " +"அமைப்புகளில் உள்ளது. லினக்ச், மேக் மற்றும் சாளரங்கள் முழுவதும் தானியங்கு சோதனையை வழங்கும் " +"போது இரண்டு புரவலன் செய்யப்பட்ட சேவைகள் உள்ளன:" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +#, fuzzy +#| 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." +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." +msgstr "" +"`டிராவிச் சி ` _ லினக்ச் மற்றும் மேகோச் சூழல் இரண்டையும் " +"வழங்குகிறது. லினக்ச் சூழல் உபுண்டு 12.04 எல்.டி.எச் சர்வர் பதிப்பு 64 பிட் ஆகும், அதே " +"நேரத்தில் மேகோச் 10.9.2 ஆகும்." + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" +"`Appveyor ` _ சாளரங்கள் சூழலை வழங்குகிறது (விண்டோச் " +"சர்வர் 2012)." + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" +"`டிராவிச் சிஐ`_ மற்றும் அப்சேயர்_ இருவருக்கும் ஒரு` யாம் _ _ " +"வடிவமைக்கப்பட்ட கோப்பு சோதனைக்கான வழிமுறைகளுக்கான விவரக்குறிப்பாக தேவைப்படுகிறது. " +"ஏதேனும் சோதனைகள் தோல்வியுற்றால், அந்த குறிப்பிட்ட உள்ளமைவுக்கான வெளியீட்டு பதிவை ஆய்வு " +"செய்யலாம்." + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" +"ஒற்றை மூல மூலோபாயத்துடன் பைதான் 2 மற்றும் 3 இரண்டிலும் பயன்படுத்தப்பட வேண்டிய பைதான் " +"திட்டங்களுக்கு, பல விருப்பங்கள் உள்ளன." + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "ஒற்றை மூல பைதான் தொகுப்புகளுக்கான கருவிகள்" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" +"`ஆறு ` _ என்பது பைதான் 2 மற்றும் பைதான் 3 க்கு " +"இடையிலான வேறுபாடுகளை மடக்குவதற்காக பெஞ்சமின் பீட்டர்சன் உருவாக்கிய ஒரு கருவியாகும். " +"சிக்ச்_ தொகுப்பு பரவலான பயன்பாட்டை அனுபவித்துள்ளது மற்றும் ஒரு பைதான் 2 மற்றும் 3 " +"இரண்டிலும் பயன்படுத்தக்கூடிய ஒற்றை மூல பைதான் தொகுதியை எழுத நம்பகமான வழி. சிக்ச்_ " +"தொகுதி பயன்படுத்தப்படலாம் பைதான் 2.5 வரை. `நவீனமயமாக்கல் ` _, அர்மின் ரோனாச்சரால் உருவாக்கப்பட்டது, ஆறு_ வழங்கிய குறியீடு மாற்றங்களை " +"தானாகவே பயன்படுத்த பயன்படுத்தலாம்." + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" +"சிக்ச்_, `பைதான்-ஃபியூச்சர் ` _ என்பது " +"பைதான் 2 மற்றும் பைதான் 3 மூலக் குறியீட்டிற்கு இடையில் பொருந்தக்கூடிய அடுக்கை வழங்கும் ஒரு " +"தொகுப்பு; இருப்பினும், சிக்ச்_ போலல்லாமல், இந்த தொகுப்பு பைதான் 2 மற்றும் பைதான் 3 க்கு " +"இடையில் இரண்டு பைதான் பதிப்புகளில் ஒன்றோடு பொருந்தக்கூடிய மொழி தொடரியல் மூலம் " +"இயங்குதளத்தை வழங்குவதை நோக்கமாகக் கொண்டுள்ளது: ஒருவர் பயன்படுத்தலாம்" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "பைதான் 3 திட்டத்தில் ஒரு பைதான் 2 (தொடரியல் மூலம்) தொகுதி." + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "* பைதான் 2 * திட்டத்தில் ஒரு பைதான் 3 (தொடரியல் மூலம்) தொகுதி." + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" +"இரு திசை காரணமாக, பைதான் 2 தொகுப்பை பைதான் 3 தொடரியல் தொகுதி-மூலம்-தொகுதிக்கு " +"மாற்றுவதற்கான பாதையை பைதான்-ஃபியூட்ர்_ வழங்குகிறது. இருப்பினும், சிக்ச்_ க்கு மாறாக, " +"பைதான்-ஃபியூச்சர்_ பைதான் 2.6 இலிருந்து மட்டுமே ஆதரிக்கப்படுகிறது. சிக்ச்_ க்கு " +"நவீனமயமாக்கல்_ ஐப் போலவே, பைதான்-ஃபியூட்யூர்_ இரண்டு ச்கிரிப்டுகளுடன் `` எதிர்காலம்`` " +"மற்றும் `` பேசூரைச்`` என அழைக்கப்படுகிறது, இது முறையே பைதான் 2 தொகுதி அல்லது பைதான் " +"3 தொகுதிக்கு பயன்படுத்தப்படலாம்." + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" +"சிக்ச்_ அல்லது பைதான்-ஃபுட்யூர்_ இன் பயன்பாடு உங்கள் தொகுப்புக்கு கூடுதல் இயக்க நேர " +"சார்புநிலையைச் சேர்க்கிறது: பைதான்-ஃபியூட்யூர்_ உடன், `` எதிர்காலம்` ச்கிரிப்டை ``-ச்டேச் " +"1`` விருப்பத்துடன் அழைக்கலாம், இது ஒரு பைதான் 2.6+ மாற்றங்களை மட்டுமே பயன்படுத்துகிறது " +"பைதானுக்கு முன்னோக்கி-இணக்கத்தன்மைக்கு ஏற்கனவே வழங்குகிறது. மீதமுள்ள பொருந்தக்கூடிய " +"சிக்கல்களுக்கு கையேடு மாற்றங்கள் தேவைப்படும்." + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "எந்த பைதான் என்ன?" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" +"`பைதான் 2 ` " +"__, __, `பைதான் 3.0-3.3 இப்போது பைதான் பதிப்புகளுக்கு இடையில் ஏதேனும் மாற்றங்கள் உங்கள் " +"தொகுப்பைப் பாதிக்குமா என்பதைச் சரிபார்க்க இந்த பட்டியல்கள் பயன்படுத்தப்படலாம்." + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "AppWeyor ஐப் பயன்படுத்தி சாளரங்களை ஆதரித்தல்" + +#: ../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 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 "" +"உங்கள் திட்டத்திற்கான சாளரங்கள் ஆதரவை வழங்க இலவச `AppVeyor`_ தொடர்ச்சியான ஒருங்கிணைப்பு " +"சேவையை எவ்வாறு பயன்படுத்துவது என்பதை இந்த பிரிவு உள்ளடக்கியது. சாளரங்களில் குறியீட்டைச் " +"சோதிப்பது மற்றும் சி நீட்டிப்புகளைப் பயன்படுத்தும் திட்டங்களுக்கான விண்டோச்-இலக்கு பைனரிகளை " +"உருவாக்குவது இதில் அடங்கும்." + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" +"பல திட்டங்கள் இயல்பாக யூனிக்சில் உருவாக்கப்பட்டுள்ளன, மேலும் சாளரங்கள் ஆதரவை வழங்குவது ஒரு " +"சவாலாக இருக்கும், ஏனெனில் பொருத்தமான சாளரங்கள் சோதனை சூழலை அமைப்பது அற்பமானது அல்ல, " +"மேலும் மென்பொருள் உரிமங்களை வாங்க வேண்டியிருக்கும்." + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" +"AppVeair பணி என்பது தொடர்ச்சியான ஒருங்கிணைப்பு சேவையாகும், இது நன்கு அறியப்பட்ட " +"`டிராவிச்`_ சேவையைப் போன்றது, இது பொதுவாக` கிதுப்`_ இல் வழங்கப்பட்ட திட்டங்களால் " +"சோதனைக்கு பயன்படுத்தப்படுகிறது. இருப்பினும், டிராவிசைப் போலல்லாமல், ஆப்சியரில் உள்ள " +"தொழிலாளர்கள் சாளரங்கள் ஓச்ட்கள் மற்றும் பைதான் நீட்டிப்புகளை உருவாக்க தேவையான கம்பைலர்கள் " +"நிறுவப்பட்டுள்ளன." + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" +"சாளரங்கள் பயனர்களுக்கு பொதுவாக சி கம்பைலருக்கு அணுகல் இல்லை, எனவே `` பைதான் -எம் பிஐபி " +"நிறுவல் `` வழியாக வழங்கல் நிறுவக்கூடிய வகையில் பைபியில் பைனரி சக்கரங்களை " +"விநியோகிக்கும் சி நீட்டிப்புகளைப் பயன்படுத்தும் திட்டங்களை நம்பியுள்ளது. AppWeyor ஐ " +"உருவாக்க சேவையாகப் பயன்படுத்துவதன் மூலம் (அதை சோதனைக்கு பயன்படுத்தாவிட்டாலும் கூட) " +"பிரத்யேக சாளரங்கள் சூழல் இல்லாத திட்டங்களுக்கு விண்டோச்-இலக்கு கொண்ட இருமங்களை வழங்க " +"முடியும்." + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" +"உங்கள் திட்டத்திற்கான சாளரங்கள் சக்கரங்களை உருவாக்க AppWeyor ஐப் பயன்படுத்த, சேவையில் " +"உங்களிடம் ஒரு கணக்கு இருக்க வேண்டும். ஒரு கணக்கை அமைப்பதற்கான வழிமுறைகள் `AppVeior " +"ஆவணத்தில் __ __ இல் கொடுக்கப்பட்டுள்ளன. திறந்த மூல " +"திட்டங்களுக்கு கணக்கின் இலவச அடுக்கு போதுமானது." + +#: ../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`_ உடன் ஒருங்கிணைப்பை வழங்குகிறது, எனவே உங்கள் " +"திட்டம் அந்த இரண்டு சேவைகளில் ஒன்றில் புரவலன் செய்யப்படும் வரை, AppWeair ஒருங்கிணைப்பை " +"அமைப்பது நேரடியானது." + +#: ../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 "" +"உங்கள் ஆப்சேயர் கணக்கை அமைத்து, உங்கள் திட்டத்தைச் சேர்த்தவுடன், ஒவ்வொரு முறையும் ஒரு கமிட் " +"நிகழும் போது AppWeyor தானாகவே உங்கள் திட்டத்தை உருவாக்கும். இந்த நடத்தை டிராவிசின் " +"பயனர்களுக்கு தெரிந்திருக்கும்." + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "உங்கள் திட்டத்தில் AppWeyor ஆதரவைச் சேர்ப்பது" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" +"உங்கள் திட்டத்தை Appveyor எவ்வாறு உருவாக்க வேண்டும் என்பதை வரையறுக்க, உங்கள் திட்டத்தில் " +"ஒரு: கோப்பு: `appweyear.yml` கோப்பைச் சேர்க்க வேண்டும். கோப்பில் என்ன சேர்க்கப்படலாம் " +"என்பதற்கான முழு விவரங்களும் AppWayor ஆவணத்தில் உள்ளன. இந்த வழிகாட்டி சக்கர கட்டமைப்புகளை " +"அமைக்க தேவையான விவரங்களை வழங்கும்." + +#: ../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 "" +"பைத்தானுக்கான நீட்டிப்புகளை உருவாக்க தேவையான அனைத்து கம்பைலர் கருவித்தொகுப்புகளையும் " +"இயல்பாகவே AppWeyor அடங்கும். 3.3 மற்றும் 3.4 இன் பைதான் 2.7, 3.5+ மற்றும் 32-பிட் " +"பதிப்புகளுக்கு, கருவிகள் பெட்டியின் வெளியே செயல்படுகின்றன. ஆனால் பைதான் 3.3 மற்றும் 3.4 " +"இன் 64-பிட் பதிப்புகளுக்கு, 64-பிட் கம்பைலர்களை எங்கு கண்டுபிடிப்பது என்பதை " +"தொலைதூரங்களுக்கு தெரியப்படுத்த ஒரு சிறிய அளவு கூடுதல் உள்ளமைவு தேவை. (3.5 முதல், " +"பயன்படுத்தப்படும் விசுவல் ச்டுடியோவின் பதிப்பில் கூடுதல் அமைப்பு இல்லாத 64-பிட் கம்பைலர்கள் " +"உள்ளன)." + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "appweyor.yml" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" +"இந்த கோப்பை `இங்கே __." + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" +"தி: கோப்பு: `appveyor.yml` கோப்பு உங்கள் திட்டத்தின் ரூட் கோப்பகத்தில் இருக்க வேண்டும். " +"இது `` யம்ல்` `வடிவத்தில் உள்ளது, மேலும் பல பிரிவுகளைக் கொண்டுள்ளது." + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" +"உங்கள் சக்கரங்கள் உருவாக்கப்படும் பைதான் பதிப்புகளை வரையறுப்பதற்கான முக்கிய நற்பொருத்தம் `` " +"சூழல்`` பிரிவு. 32-பிட் மற்றும் 64-பிட் கட்டமைப்புகளில் பைதான் 2.6, 2.7, 3.3, 3.4 " +"மற்றும் 3.5 நிறுவப்பட்ட பைதான் 2.6, நிறுவப்பட்டுள்ளது. பைதான் 2.6 தவிர இந்த சூழல்கள் " +"அனைத்திற்கும் எடுத்துக்காட்டு கோப்பு உருவாகிறது. பைதான் 2.6 க்கு நிறுவுவது மிகவும் " +"சிக்கலானது, ஏனெனில் இது பிஐபி சேர்க்கப்படவில்லை. இந்த ஆவணத்தில் நாங்கள் 2.6 ஐ " +"ஆதரிக்கவில்லை (விண்டோச் பயனர்கள் இன்னும் பைதான் 2 ஐப் பயன்படுத்துவதால் பொதுவாக பைதான் 2.7 " +"க்கு அதிக தொல்லை இல்லாமல் செல்ல முடியும்)." + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" +"திட்டத்திற்குத் தேவைப்படும் கூடுதல் மென்பொருளை நிறுவ `` நிறுவல்` பிரிவு PIP ஐப் " +"பயன்படுத்துகிறது. சக்கரங்களை உருவாக்குவதற்கான ஒரே தேவை `` சக்கரம்`` திட்டமாகும், ஆனால் " +"திட்டங்கள் இந்த குறியீட்டை சில சூழ்நிலைகளில் தனிப்பயனாக்க விரும்பலாம் (எடுத்துக்காட்டாக, `` " +"சைதான்`` போன்ற கூடுதல் பில்ட் தொகுப்புகளை நிறுவ அல்லது `` போன்ற சோதனைக் கருவிகளை " +"நிறுவவும் விரும்பலாம் நச்சு``)." + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" +"`` பில்ட்`` பிரிவு வெறுமனே கட்டமைப்பை அணைக்க வேண்டும் - பைத்தானுக்கு எந்த கட்டமைப்பும் " +"தேவையில்லை, `` சி#`` போன்ற மொழிகளைப் போலல்லாமல்." + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" +"உங்கள் திட்டத்திற்கு ஏற்ப வடிவமைக்க வேண்டிய முக்கிய பிரிவுகள் `` டெச்ட்_ச்கிரிப்ட்`` மற்றும் " +"`` பிறகு_டெச்ட்``." + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" +"உங்கள் திட்டத்தின் சோதனைகளை இயக்கும் இடம் `` டெச்ட்_ச்கிரிப்ட்`` பிரிவு. வழங்கப்பட்ட கோப்பு " +"`` setup.py test`` ஐப் பயன்படுத்தி உங்கள் சோதனை தொகுப்பை இயக்குகிறது. நீங்கள் சக்கரங்களை " +"உருவாக்குவதில் மட்டுமே ஆர்வமாக இருந்தால், சாளரங்களில் உங்கள் சோதனைகளை இயக்குவதில் அல்ல, " +"இந்த பகுதியை `` எதிரொலி தவிர்க்கப்பட்ட சோதனைகள்` போன்ற போலி கட்டளையுடன் மாற்றலாம். `` " +"மூக்கு`` அல்லது: கோப்பு: `py.test` போன்ற மற்றொரு சோதனை கருவியைப் பயன்படுத்த " +"விரும்பலாம். அல்லது `` டாக்ச்`` போன்ற சோதனை இயக்கியைப் பயன்படுத்த விரும்பலாம் - " +"இருப்பினும் நீங்கள் `` டோக்ச்`` ஐப் பயன்படுத்துகிறீர்கள் என்றால், நீங்கள் கருத்தில் கொள்ள வேண்டிய " +"சில கூடுதல் உள்ளமைவு மாற்றங்கள் உள்ளன, அவை கீழே விவரிக்கப்பட்டுள்ளன." + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" +"உங்கள் சோதனைகள் முடிந்ததும் `` after_test`` இயங்கும், அவ்வாறே சக்கரங்கள் கட்டப்பட வேண்டும். " +"உங்கள் திட்டம் பரிந்துரைக்கப்பட்ட கருவிகளைப் பயன்படுத்துகிறது (குறிப்பாக, `` " +"setuptools``) பின்னர் `` setup.py.py bdist_wheel`` கட்டளை உங்கள் சக்கரங்களை " +"உருவாக்கும்." + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" +"உங்கள் சோதனைகள் செய் பெற்றால் மட்டுமே சக்கரங்கள் கட்டப்படும் என்பதை நினைவில் கொள்க. " +"சாளரங்களில் உங்கள் சோதனைகள் தோல்வியடையும் என்று நீங்கள் எதிர்பார்த்தால், மேலே " +"விவரிக்கப்பட்டபடி அவற்றைத் தவிர்க்கலாம்." + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "ச்கிரிப்ட் உதவி" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" +"தி: கோப்பு: `appveyor.yml` கோப்பு ஒரு உதவி ச்கிரிப்டை நம்பியுள்ளது, இது பைதான் 3.3 " +"மற்றும் 3.4 இல் 64-பிட் கட்டமைப்புகளுக்கு SDK கம்பைலரைப் பயன்படுத்த சூழலை அமைக்கிறது. " +"ஒரு கம்பைலர் தேவையில்லை, அல்லது 64-பிட் சாளரங்களில் 3.3 அல்லது 3.4 ஐ ஆதரிக்காத " +"திட்டங்களுக்கு, மட்டுமே: கோப்பு: `appveyor.yml` கோப்பு தேவை." + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" +". தேர்ந்தெடுக்கப்பட்ட பைதான் பதிப்பிற்கு பொருத்தமான தொகுப்பாளருடன் சூழலில் கட்டளையிடவும். " +"நீங்கள் செய்ய வேண்டியதெல்லாம், ஒற்றை சூழல் மாறியை `` Distutils_use_sdk`` `` 1`` " +"மதிப்புக்கு அமைப்பதோடு, மீதமுள்ள ச்கிரிப்ட் செய்கிறது. இது பைதான் 3.3 அல்லது 3.4 இன் 64-" +"பிட் கட்டங்களுக்கு தேவையான SDK ஐ அமைக்கிறது, எனவே வேறு எந்த கட்டமைப்பிற்கும் சூழல் " +"மாறியை அமைக்க வேண்டாம்." + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" +"நீங்கள் வெறுமனே தொகுதி கோப்பை பதிவிறக்கம் செய்து அதை மாற்றாமல் உங்கள் திட்டத்தில் சேர்க்கலாம்." + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "கட்டப்பட்ட சக்கரங்களுக்கான அணுகல்" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" +"உங்கள் உருவாக்கம் முடிந்ததும், உங்கள் திட்டத்திற்கான AppWayer கட்டுப்பாட்டு குழுவிலிருந்து " +"கட்டப்பட்ட சக்கரங்கள் கிடைக்கும். ஒவ்வொரு கட்டமைப்பிற்கும் உருவாக்க நிலை பக்கத்திற்குச் செல்வதன் " +"மூலம் அவற்றைக் காணலாம். உருவாக்க வெளியீட்டின் உச்சியில் தொடர்ச்சியான இணைப்புகள் உள்ளன, " +"அவற்றில் ஒன்று \"கலைப்பொருட்கள்\". அந்த பக்கத்தில் அந்த பைதான் பதிப்பு / கட்டிடக்கலைக்கான " +"சக்கரங்களுக்கான இணைப்புகளின் பட்டியல் இருக்கும். உங்கள் வெளியீட்டு செயல்முறையின் ஒரு " +"பகுதியாக அந்த சக்கரங்களை பதிவிறக்கம் செய்து அவற்றை PYPI இல் பதிவேற்றலாம்." + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "டாக்சுடன் சோதனை" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" +"பல திட்டங்கள்: DOC: `TOX ` அவர்களின் சோதனைகளை இயக்க கருவி " +"பயன்படுத்துகின்றன. திட்டத்தால் விநியோகிக்கப்படும் சரியான கோப்புகளைப் பயன்படுத்தி " +"தனிமைப்படுத்தப்பட்ட சூழலில் சோதனைகள் இயக்கப்படுவதை இது உறுதி செய்கிறது." + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" +"AppWeyor இல் `` டோக்ச்`` ஐப் பயன்படுத்துவதற்கு இரண்டு கூடுதல் பரிசீலனைகள் உள்ளன " +"(உண்மையில், இந்த சிக்கல்கள் AppWeyor க்கு குறிப்பிட்டவை அல்ல, மேலும் பிற தொஒ அமைப்புகளை " +"பாதிக்கலாம்)." + +#: ../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." +msgstr "" +"இயல்பாக, `` டோக்ச்`` சோதனை செயல்முறைகளுக்கு சுற்றுச்சூழல் மாறிகளின் தேர்ந்தெடுக்கப்பட்ட " +"துணைக்குழுவை மட்டுமே அனுப்புகிறது. கம்பைலரைக் கட்டுப்படுத்த `` டிச்ட்டில்ச்`` சுற்றுச்சூழல் " +"மாறிகளைப் பயன்படுத்துவதால், இந்த \"சோதனை தனிமைப்படுத்தல்\" நற்பொருத்தம் சோதனைகள் " +"இயல்புநிலையாக தவறான தொகுப்பைப் பயன்படுத்தும்." + +#: ../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 "" +"தேவையான சுற்றுச்சூழல் மாறிகளை துணை செயலாக்கத்திற்கு அனுப்ப `` டோக்ச்`` கட்டாயப்படுத்த, " +"துணை செயலாக்கத்திற்கு அனுப்பப்பட வேண்டிய கூடுதல் சுற்றுச்சூழல் மாறிகள் பட்டியலிட `` " +"டோக்ச்` உள்ளமைவு விருப்பத்தை `` பயணிகள்`` அமைக்க வேண்டும். SDK கம்பைலர்களுக்கு, உங்களுக்கு " +"தேவை" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "`` Distutils_use_sdk``" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "`` Mssdk``" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "`` சேர்க்கவும்``" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +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." +msgstr "" +"`` பயணிகள்`` விருப்பத்தை உங்கள்: கோப்பில் அமைக்கலாம்: `Tox.ini`, அல்லது உங்கள் பொதுவான " +"திட்டக் கோப்புகளில் விண்டோச்-குறிப்பிட்ட அமைப்புகளைச் சேர்ப்பதைத் தவிர்க்க விரும்பினால்,` " +"`Tox_testenv_passenv`` சுற்றுச்சூழல் மாறி. வழங்கப்பட்ட: கோப்பு: `` `` " +"`distutils_use_sdk`` அமைக்கும்போதெல்லாம் இயல்புநிலையாக இதைச் செய்கிறது." + +#: ../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)." +msgstr "" +"ஊடாடும் வகையில் பயன்படுத்தும்போது, `` டோக்ச்`` பல சூழல்களுக்கு எதிராக உங்கள் சோதனைகளை " +"இயக்க உங்களை அனுமதிக்கிறது (பெரும்பாலும், இதன் பொருள் பல பைதான் பதிப்புகள்). டிராவிச் " +"அல்லது ஆப்சியர் போன்ற தொஒ சூழலில் இந்த நற்பொருத்தம் பயனுள்ளதாக இருக்காது, அங்கு அனைத்து " +"சோதனைகளும் ஒவ்வொரு உள்ளமைவுக்கும் தனிமைப்படுத்தப்பட்ட சூழல்களில் இயக்கப்படுகின்றன. இதன் " +"விளைவாக, எந்த சூழலைப் பயன்படுத்த வேண்டும் என்பதைக் குறிப்பிடுவதற்கு திட்டங்கள் பெரும்பாலும் " +"`` -e envname`` க்கு `` டோக்ச்`` க்கு வழங்குகின்றன (பைத்தானின் பெரும்பாலான " +"பதிப்புகளுக்கு இயல்புநிலை சூழல்கள் உள்ளன)." + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" +"இருப்பினும், இது APPWEYOR போன்ற சாளரங்கள் தொஒ அமைப்புடன் நன்றாக வேலை செய்யாது, அங்கு " +"பைதான் 3.4 (32-பிட் மற்றும் 64-பிட்) இரண்டு நிறுவல்கள் உள்ளன, ஆனால் ஒரு `` py34`` சூழல் " +"மட்டுமே `` டாக்ச்``." + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" +"எனவே, `` டோக்ச்`` ஐப் பயன்படுத்தி சோதனைகளை இயக்குவதற்கு, திட்டங்கள் இயல்புநிலை `` பை`` " +"சூழலை `` டோக்ச்`` இல் பயன்படுத்த வேண்டும், இது பைதான் மொழிபெயர்ப்பாளரைப் " +"பயன்படுத்துகிறது, இது `` டாக்ச்`` ஐ இயக்க பயன்படுத்தப்பட்டது. AppWeyor சோதனைகளை " +"இயக்கும்போது, அவை உள்ளமைக்கப்பட்ட மொழிபெயர்ப்பாளருடன் இயக்கப்படும் என்பதை இது உறுதி " +"செய்யும்." + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" +"`` பை`` சூழலின் கீழ் இயங்குவதை ஆதரிக்க, சிக்கலான `` டோக்ச்`` உள்ளமைவுகளைக் கொண்ட " +"திட்டங்கள் அவற்றின்: கோப்பு: `Tox.ini` கோப்பை மாற்ற வேண்டியிருக்கலாம். இருப்பினும், " +"அவ்வாறு செய்வது இந்த ஆவணத்தின் எல்லைக்கு வெளியே உள்ளது." + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "தானாகவே சக்கரங்களை பதிவேற்றும்" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" +"சக்கரங்களை தானாக பதிவேற்ற AppWeyor ஐக் கோர முடியும். ஒரு `` வரிசைப்படுத்தல்`` படி " +"கிடைக்கிறது: கோப்பு: `appveyor.yml` இது பயன்படுத்தப்படலாம் (எடுத்துக்காட்டாக) " +"கட்டமைக்கப்பட்ட கலைப்பொருட்களை ஒரு FTP தளத்திற்கு நகலெடுக்கவும் அல்லது அமேசான் S3 " +"உதாரணமாகவோ. இதை எப்படி செய்வது என்பது குறித்த ஆவணங்கள் AppWayer வழிகாட்டிகளில் " +"சேர்க்கப்பட்டுள்ளன." + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" +"மாற்றாக, கட்டமைப்பிற்கு `` கயிறு பதிவேற்றம்` படி சேர்க்க முடியும். வழங்கப்பட்ட: கோப்பு: " +"`appveyor.yml` இதைச் செய்யாது, ஏனெனில் ஒவ்வொரு உறுதிப்பாட்டிற்கும் பிறகு புதிய " +"சக்கரங்களை பதிவேற்றுவது விரும்பத்தக்கது என்பது தெளிவாகத் தெரியவில்லை (சில திட்டங்கள் " +"இதைச் செய்ய விரும்பினாலும்)." + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "வெளிப்புற சார்புநிலைகள்" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" +"வழங்கப்பட்ட ச்கிரிப்ட்கள் 3 வது தரப்பு வெளிப்புற நூலகங்களை நம்பாத எந்தவொரு விநியோகத்தையும் " +"வெற்றிகரமாக உருவாக்கும்." + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" +"விநியோகத்திற்குத் தேவையான வெளிப்புற நூலகங்களை பதிவிறக்கம் மற்றும்/அல்லது " +"உருவாக்குவதற்கு: கோப்பு: `appveyor.yml` உள்ளமைவு (பொதுவாக\" நிறுவு \"பிரிவில்) " +"படிகளைச் சேர்க்க முடியும். தேவைப்பட்டால், இந்த நூலகங்களின் இருப்பிடத்தை கம்பைலருக்கு " +"வழங்குவதற்கு கூடுதல் உள்ளமைவைச் சேர்க்க முடியும். இருப்பினும், இந்த நிலை உள்ளமைவு இந்த " +"ஆவணத்தின் எல்லைக்கு அப்பாற்பட்டது." + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "ச்கிரிப்ட்களை ஆதரிக்கவும்" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "குறிப்புக்கு, SDK அமைவு உதவி ச்கிரிப்ட் இங்கே பட்டியலிடப்பட்டுள்ளது:" + +#: ../source/guides/supporting-windows-using-appveyor.rst:233 +msgid "``appveyor-sample/build.cmd``" +msgstr "`` appweyor-sample/build.cmd``" + +#: ../source/guides/tool-recommendations.rst:5 +msgid "Tool recommendations" +msgstr "கருவி பரிந்துரைகள்" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" +"பைதான் பேக்கேசிங் நிலப்பரப்பு பல வேறுபட்ட கருவிகளைக் கொண்டுள்ளது. பல பணிகளுக்கு, தி: " +"கால: `பைதான் பேக்கேசிங் ஆணையம் <பைதான் பேக்கேசிங் ஆணையம் (பைபா)>` (பைபா, பல பேக்கேசிங் " +"கருவிகளை உள்ளடக்கிய மற்றும் இந்த வழிகாட்டியை பராமரிக்கும் பணிக்குழு) வேண்டுமென்றே ஒரு " +"போர்வை பரிந்துரை செய்யாது; எடுத்துக்காட்டாக, பல கட்டமைப்புகளை உருவாக்குவதற்கான காரணம் " +"என்னவென்றால், முன்னர் தனித்துவமான பின்தளத்தில், செடுப்டூல்சை விட சில பயனர்களின் " +"தேவைகளுக்கு சிறப்பாக பணி செய்யும் புதிய பின்தளத்தில் வளர்ச்சியை செயல்படுத்துவதற்காக " +"நிலப்பரப்பு திறக்கப்பட்டது. இந்த வழிகாட்டி பரவலாக அங்கீகரிக்கப்பட்ட சில கருவிகளை " +"சுட்டிக்காட்டுகிறது, மேலும் நீங்கள் பயன்படுத்த வேண்டிய கருவிகளின் சில பரிந்துரைகளையும் " +"உருவாக்குகிறது, ஏனெனில் அவை நீக்கப்பட்டவை அல்லது பாதுகாப்பற்றவை." + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "மெய்நிகர் சூழல்கள்" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" +"மெய்நிகர் சூழல்களை கைமுறையாக உருவாக்குவதற்கும் பயன்படுத்துவதற்கும் நிலையான கருவிகள்: " +"ref: `மெய்நிகர்என்வ்` (பைபா திட்டம்) மற்றும்: டாக்:` வெவி <பைதான்: நூலகம்/வெவி> `(பைதான் " +"நிலையான நூலகத்தின் ஒரு பகுதி, மெய்நிகர்என்வின் சில அம்சங்களைக் காணவில்லை என்றாலும்) ." + +#: ../source/guides/tool-recommendations.rst:28 +msgid "Installing packages" +msgstr "தொகுப்புகளை நிறுவுதல்" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" +". இதற்கான பைப்பின் பரிந்துரைகளை நீங்கள் படிக்க விரும்பலாம்: DOC: `பாதுகாப்பான நிறுவல்கள் " +"`. நிலையான நூலக தொகுப்பு மூலம் பெரும்பாலான " +"பைதான் நிறுவல்களில் பிஐபி இயல்பாகவே கிடைக்கிறது: டிஓசி: `உறுதிப்படுத்தல் <பைதான்: " +"நூலகம்/உறுதி>`." + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" +"மாற்றாக. PIPX என்பது PIP மற்றும் WVV ஐச் சுற்றியுள்ள ஒரு ரேப்பர் ஆகும், இது ஒவ்வொரு " +"பயன்பாட்டையும் ஒரு பிரத்யேக மெய்நிகர் சூழலில் நிறுவுகிறது. இது வெவ்வேறு பயன்பாடுகளின் " +"சார்புகளுக்கிடையேயான மோதல்களைத் தவிர்க்கிறது, மேலும் கணினி அளவிலான பயன்பாடுகளுடன் அதே " +"பைதான் மொழிபெயர்ப்பாளரை (குறிப்பாக லினக்சில்) பயன்படுத்துகிறது." + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +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 "" +"இங்கே அல்லது ஒரு புதிய விவாதத்தில் ஒரு \"பிப் வெர்சச் காண்டா\" ஒப்பீட்டை எழுதுங்கள்." + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" +"** அல்ல ** `` ஈசி_இன்ச்டால்`` ஐப் பயன்படுத்தவும் (இதன் பகுதி: குறிப்பு: `செடிப்டூல்ச்`), " +"இது பிஐக்கு ஆதரவாக நீக்கப்பட்டது (விவரங்களுக்கு பார்க்க: குறிப்பு:` பிப் vs ஈசி_இன்ச்டால்` " +"விவரங்களுக்கு). அதேபோல், ** செய்ய வேண்டாம் ** `` பைதான் அமைவு. ." + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "கோப்புகளைப் பூட்டவும்" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" +":ref:`pip-tools` and :ref:`Pipenv` அரே two recognized கருவிகள் பெறுநர் create " +"lock files, which contain the exact versions of அனைத்தும் தொகுப்பு installed " +"into an environment, க்கு reproducibility purposes." + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "பின்தளத்தில் உருவாக்குங்கள்" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" +"தயவுசெய்து, நினைவில் கொள்ளுங்கள்: இந்த ஆவணம் வாசகரை ஒரு குறிப்பிட்ட கருவியை நோக்கி " +"நகர்த்த முற்படுவதில்லை, பொதுவான கருவிகளைக் கணக்கிட மட்டுமே. வெவ்வேறு பயன்பாட்டு " +"வழக்குகளுக்கு பெரும்பாலும் சிறப்பு பணிப்பாய்வு தேவைப்படுகிறது." + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" +"பிரபலமானது: கால: `பின்தளத்தில் உருவாக்குங்கள் <பின்தளத்தில் உருவாக்கு>` தூய-பைதான் " +"தொகுப்புகளுக்கு அகர வரிசைப்படி அடங்கும்:" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" +". ஒரு குறைந்தபட்ச மற்றும் கருத்துள்ள கட்டமைப்பை பின்தளத்தில் உருவாக்குதல். இது " +"செருகுநிரல்களை ஆதரிக்காது." + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" +"அட்ச்லிங்_ - உருவாக்கப்பட்டது ஆனால் தனித்தனியாக: ref: `அட்ச்`. செருகுநிரல்களை " +"ஆதரிக்கிறது." + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" +"PDM-Backend_-உருவாக்கப்பட்டது ஆனால் தனித்தனியாக: ref: `PDM`. செருகுநிரல்களை " +"ஆதரிக்கிறது." + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" +"கவிதை-கோர்_-உருவாக்கப்பட்டது ஆனால் தனித்தனியாக: ref: `கவிதை`. செருகுநிரல்களை " +"ஆதரிக்கிறது." + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" +"இந்த பட்டியலில் உள்ள மற்ற பின்தளத்தில் போலல்லாமல், கவிதை-கோர் தரத்தை ஆதரிக்காது: ref: " +"`[திட்டம்] அட்டவணை <எழுதுதல்-பைபிரோசெக்ட்-டாம்>` (இது `` [கருவி.பொயெட்ரி] `` அட்டவணை " +"ஆகியவற்றில் வேறு வடிவத்தைப் பயன்படுத்துகிறது )." + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr ". செருகுநிரல்களை ஆதரிக்கிறது." + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" +"நீங்கள் செட்ப்டூல்களைப் பயன்படுத்தினால், தரப்படுத்தல் முயற்சிகளுக்கு முன்னறிவிக்கும் சில " +"நற்பொருத்தங்கள் இப்போது நீக்கப்பட்டுள்ளன, மேலும் * தற்காலிகமாக * மட்டுமே பொருந்தக்கூடிய " +"தன்மைக்காக வைக்கப்பட்டுள்ளன என்பதை நினைவில் கொள்க." + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" +"குறிப்பாக, ** செய்ய வேண்டாம் ** நேரடி `` பைதான் setup.py`` அழைப்புகளை பயன்படுத்தவும். " +"மறுபுறம், செடிப்டூல்களை ஒரு: கோப்பு: `setup.py` கோப்பு இன்னும் முழுமையாக " +"ஆதரிக்கப்படுகிறது, இருப்பினும் நவீனத்தைப் பயன்படுத்த பரிந்துரைக்கப்படுகிறது: குறிப்பு:` " +"[திட்டம்] பைபிரொசெக்ட். `(அல்லது: கோப்பு:` setup.cfg`) முடிந்த போதெல்லாம் மற்றும் " +"வைத்திருங்கள்: கோப்பு: `setup.py` நிரல் உள்ளமைவு தேவைப்பட்டால் மட்டுமே. காண்க: ref: " +"`setup-py- deprecated`." + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" +"நீங்கள் நீக்கப்பட்ட அம்சங்களின் பிற எடுத்துக்காட்டுகள் ** அல்ல ** பயன்பாடு `` " +"setup_requires`` வாதத்தை `` அமைவு () `` (பயன்படுத்தவும்: ref: `[பில்ட்-சிச்டம்] " +"அட்டவணை `இல்: கோப்பு:` pyproject.toml` " +"அதற்கு பதிலாக), மற்றும் `` Ease_install`` கட்டளை (cf. : Ref: `PIP vs " +"Ease_install`)." + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" +"செய்யுங்கள் ** அல்ல ** பயன்பாடு: குறிப்பு: `டிச்டிடில்ச்`, இது நீக்கப்பட்டது, மேலும் " +"பைத்தான் 3.12 இல் உள்ள நிலையான நூலகத்திலிருந்து அகற்றப்பட்டது, இருப்பினும் இது இன்னும் " +"செட்டுப்டூல்களிலிருந்து கிடைக்கிறது." + +#: ../source/guides/tool-recommendations.rst:115 +#, fuzzy +#| msgid "Building binary extensions" +msgid "Build backends for extension modules" +msgstr "பைனரி நீட்டிப்புகளை உருவாக்குதல்" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" +"இதில் தொகுப்புகளுக்கு: கால: `நீட்டிப்பு தொகுதிகள் <நீட்டிப்பு தொகுதி>`, நீட்டிப்பு " +"எழுதப்பட்ட மொழிக்கு பிரத்யேக ஆதரவுடன் ஒரு உருவாக்க முறையைப் பயன்படுத்துவது நல்லது, " +"எடுத்துக்காட்டாக:" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" +":ref:`setuptools` -- natively supports C and C++ (with third-party " +"செருகுநிரல்கள் க்கு Go and Rust)," + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and மற்றொன்று மொழிகள் supported " +"by Meson," + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" +":ref:`scikit-build-core` -- C, C++, Fortran, and மற்றொன்று மொழிகள் supported by " +"CMake," + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr ": ref: `` Maturin` - ரச்ட், சரக்கு வழியாக." + +#: ../source/guides/tool-recommendations.rst:128 +msgid "Building distributions" +msgstr "கட்டிட வழங்கல்" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" +"உருவாக்குவதற்கான நிலையான கருவி: கால: `மூல வழங்கல் <மூல வழங்கல் (அல்லது\" SDIST " +"\")>` மற்றும்: கால: `சக்கரங்கள் ` PYPI இல் பதிவேற்றுவதற்கு: ref: `build`. " +"இது உங்களை பின்தளத்தில் கட்டியெழுப்புவதைத் தூண்டும்: குறிப்பு: `அறிவிக்கப்பட்ட ` இல்: கோப்பு: `pyproject.toml`." + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" +"** செய்ய வேண்டாம் ** இந்த பணிக்கு `` பைதான் அமைவு. அனைத்து நேரடி அழைப்புகளும்: கோப்பு: " +"`setup.py`: ref:` நீக்கப்பட்ட `." + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" +"உங்களிடம் இருந்தால்: சொல்: `நீட்டிப்பு தொகுதிகள் <நீட்டிப்பு தொகுதி>` மற்றும் பல " +"தளங்களுக்கான சக்கரங்களை விநியோகிக்க விரும்பினால், பயன்படுத்தவும்: ref: `cibuildwheel` " +"உங்கள் தொஒ அமைப்பின் ஒரு பகுதியாக விநியோகிக்கக்கூடிய சக்கரங்களை உருவாக்க." + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "PYPI இல் பதிவேற்றுகிறது" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" +"ஆதரிக்கப்பட்ட சிஐ/சிடி இயங்குதளங்கள் வழியாக புரவலன் செய்யப்பட்ட அல்லது வெளியிடப்பட்ட " +"திட்டங்களுக்கு, பயன்படுத்த பரிந்துரைக்கப்படுகிறது: rew: `நம்பகமான வெளியீடு <நம்பகமான-" +"வெளியீட்டு>`, இது ஒரு சிஐ/சிடி பணிப்பாய்வுகளிலிருந்து பைபிக்கு பாதுகாப்பாக பதிவேற்ற " +"அனுமதிக்கிறது கைமுறையாக கட்டமைக்கப்பட்ட பநிஇ கிள்ளாக்கு." + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" +"நவம்பர் 2024 நிலவரப்படி, நம்பகமான வெளியீட்டு வழங்குநர்களாக பின்வரும் தளங்களை PYPI " +"ஆதரிக்கிறது:" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "Github செயல்கள் (`` https: // github.com`` இல்)" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "Gitlab ci/cd (`https: // gitlab.com` இல்)" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "செயல்பாட்டு" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "கூகிள் முகில்" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "கிடைக்கக்கூடிய மற்ற முறை, தொகுப்பை கைமுறையாகப் பயன்படுத்துவதே: ref: `கயிறு`." + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" +"** ஒருபோதும் ** இந்த பணிக்கு `` பைதான் அமைவு. இருப்பதற்கு கூடுதலாக: ref: `நீக்கப்பட்ட " +"`, இது பாதுகாப்பற்றது." + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "பணிப்பாய்வு கருவிகள்" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" +"இந்த கருவிகள் ஒரு திட்டத்திற்கான மெய்நிகர் சூழல்களை தானாக நிர்வகிக்கும் சுற்றுச்சூழல் " +"மேலாளர்கள். அவை \"பணி ஓட்டப்பந்தய வீரர்களாகவும்\" செயல்படுகின்றன, சோதனைகளை இயக்குதல், " +"ஆவணங்களை தொகுத்தல், சில கோப்புகளை மீண்டும் உருவாக்குதல் போன்ற பணிகளை வரையறுக்கவும், " +"செயல்படுத்தவும் உங்களை அனுமதிக்கிறது. அவற்றில் சில விநியோகங்களை உருவாக்குவதற்கும் PYPI " +"இல் பதிவேற்றுவதற்கும் குறுக்குவழிகளை வழங்குகின்றன, மேலும் பயன்பாடுகளுக்கான சில உதவி " +"பூட்டு கோப்புகள் . அவர்கள் பெரும்பாலும் மேலே குறிப்பிட்ட கருவிகளை பேட்டை கீழ் " +"அழைக்கிறார்கள். அகர வரிசைப்படி:" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr ": Ref: `Flit`," + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr ": ref: `அட்ச்`," + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr ": DOC: `Nox `," + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr ": Ref: `PDM`," + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr ": ref: `பைபென்வ்`," + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr ": ref: `கவிதை`," + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr ": டாக்: `டாக்ச் <டோக்ச்: குறியீட்டு>`." + +#: ../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 "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" +"இந்தப் பக்கத்தில் உள்ள தகவல்கள் நகர்ந்தன: DOC: `Setuptools: USerguide/Miscelliveane`` " +"செட்டுப்லூல்ச் ஆவணத்தில்." + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" +"`` TestPypi`` என்பது ஒரு தனி நிகழ்வு: கால: `பைதான் தொகுப்பு குறியீட்டு (PYPI)` இது " +"உண்மையான குறியீட்டை பாதிப்பதைப் பற்றி கவலைப்படாமல் விநியோக கருவிகளை முயற்சிக்கவும் " +"செயல்முறையாகவும் உங்களை அனுமதிக்கிறது. TestPypi `test.pypi.org _ _ இல் புரவலன் செய்யப்படுகிறது" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "உங்கள் கணக்கை பதிவு செய்தல்" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" +"டெச்ட்பிஐ லைவ் PYPI இலிருந்து ஒரு தனி தரவுத்தளத்தைக் கொண்டிருப்பதால், டெச்ட்பிஐக்கு " +"குறிப்பாக ஒரு தனி பயனர் கணக்கு தேவைப்படும். உங்கள் கணக்கை பதிவு செய்ய https://" +"test.pypi.org/account/register/ க்குச் செல்லவும்." + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" +"டெச்ட்பிஐவுக்கான தரவுத்தளம் அவ்வப்போது கத்தரிக்கப்படலாம், எனவே பயனர் கணக்குகள் நீக்கப்படுவது " +"வழக்கத்திற்கு மாறானதல்ல." + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "கயிறுடன் டெச்ட்பை பயன்படுத்துதல்" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" +"`` --Repository`` கொடியைக் குறிப்பிடுவதன் மூலம் ref: `ட்வைன்` உங்கள் விநியோகங்களை " +"டெச்ட்பைட்டில் பதிவேற்றலாம்:" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" +"`` Https://test.pypi.org/project/ `` `` மாதிரி வெளியீட்டு`` " +"என்பது நீங்கள் பதிவேற்றிய உங்கள் திட்டத்தின் பெயர். உங்கள் திட்டம் தளத்தில் தோன்றுவதற்கு ஒரு " +"மணித்துளி அல்லது இரண்டு நேரம் ஆகலாம்." + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "PIP உடன் டெச்ட்பைப்பைப் பயன்படுத்துதல்" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" +"நீங்கள் சொல்லலாம்: ref: `` --index-url`` கொடியைக் குறிப்பிடுவதன் மூலம் PYPI க்கு " +"பதிலாக டெச்ட்பிஐயிலிருந்து தொகுப்புகளை பதிவிறக்கம் செய்ய `பிப்`:" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" +"PYPI இலிருந்து தொகுப்புகளையும் பதிவிறக்கம் செய்ய PIP ஐ அனுமதிக்க விரும்பினால், PYPI ஐ " +"சுட்டிக்காட்ட `` --extra-index-url`` ஐக் குறிப்பிடலாம். நீங்கள் சோதிக்கும் தொகுப்பில் " +"சார்புநிலைகள் இருக்கும்போது இது பயனுள்ளதாக இருக்கும்:" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "TestPypi ஐ அமைத்தல்: கோப்பு: `.pypirc`" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" +"ஒவ்வொரு முறையும் உங்கள் பயனர்பெயர் மற்றும் கடவுச்சொல்லுக்கு கேட்கப்படுவதைத் தவிர்க்க " +"விரும்பினால், உங்கள்: கோப்பு: `$ home/.pypirc`:" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "உங்கள் `` pyproject.toml`` எழுதுதல்" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" +"`` pyproject.toml`` என்பது பேக்கேசிங் கருவிகளால் பயன்படுத்தப்படும் ஒரு உள்ளமைவு " +"கோப்பு, அதே போல் லிண்டர்கள், வகை செக்கர்ச் போன்ற பிற கருவிகளும் இந்த கோப்பில் மூன்று " +"சாத்தியமான டாம்ல் அட்டவணைகள் உள்ளன." + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" +"`` [பில்ட்-சிச்டம்] `` அட்டவணை ** வலுவாக பரிந்துரைக்கப்படுகிறது **. எந்தெந்த: கால: " +"`பின்தளத்தில் உருவாக்கு` நீங்கள் பயன்படுத்தும் மற்றும் உங்கள் திட்டத்தை உருவாக்க வேறு எந்த " +"சார்புகள் தேவை என்பதை அறிவிக்க இது உங்களை அனுமதிக்கிறது." + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" +"`` [திட்டம்] `` அட்டவணை என்பது உங்கள் திட்டத்தின் அடிப்படை மெட்டாடேட்டாவான சார்புநிலைகள், " +"உங்கள் பெயர் போன்றவற்றைக் குறிப்பிட பெரும்பாலான பின்தளத்தில் பயன்படுத்தும் வடிவமாகும்." + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" +"`` [கருவி] `` அட்டவணையில் கருவி-குறிப்பிட்ட சப்டேபிள்கள் உள்ளன, எ.கா., `` [கருவி. " +"இந்த அட்டவணையை மட்டுமே இங்கே தொடுகிறோம், ஏனெனில் அதன் உள்ளடக்கங்கள் ஒவ்வொரு கருவியாலும் " +"வரையறுக்கப்படுகின்றன. குறிப்பிட்ட கருவியின் ஆவணங்களை அதில் எதைக் கொண்டிருக்கலாம் என்பதை " +"அறியவும்." + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" +"`` [பில்ட்-சிச்டம்] `` அட்டவணை எப்போதும் இருக்க வேண்டும், நீங்கள் பயன்படுத்தும் பின்தளத்தில் " +"எந்த கட்டமைப்பைப் பொருட்படுத்தாமல் (`` [உருவாக்க-அமைப்பு] `` * நீங்கள் பயன்படுத்தும் " +"உருவாக்க கருவியை வரையறுக்கிறது)." + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" +"மறுபுறம், `` [திட்டம்] `` அட்டவணை * பெரும்பாலான * பின்தளத்தில் உருவாக்கப்படுகிறது, " +"ஆனால் சிலர் பின்தளத்தில் கட்டியெழுப்ப வேறு வடிவத்தைப் பயன்படுத்துகின்றனர்." + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" +"ஒரு குறிப்பிடத்தக்க விதிவிலக்கு கவிதை_, இது பதிப்பு 2.0 க்கு முன் (சனவரி 5, 2025 " +"வெளியிடப்பட்டது) `` [திட்டம்] `` அட்டவணையைப் பயன்படுத்தவில்லை, இது அதற்கு பதிலாக `` " +"[கருவி.பொயெட்ரி] `` அட்டவணையைப் பயன்படுத்தியது. பதிப்பு 2.0 உடன், இது இரண்டையும் " +"ஆதரிக்கிறது. மேலும், Setuptools_ உருவாக்கு Enceded `` [திட்டம்] `` அட்டவணை, மற்றும் " +"பழைய வடிவம் `` setup.cfg`` அல்லது `` setup.py`` இரண்டையும் ஆதரிக்கிறது." + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" +"புதிய திட்டங்களுக்கு, `` [திட்டம்] `` அட்டவணையைப் பயன்படுத்தவும், சில நிரல் உள்ளமைவு " +"தேவைப்பட்டால் (சி நீட்டிப்புகளை உருவாக்குவது போன்றவை), ஆனால் `` setup.cfg`` மற்றும் ` " +"`setup.py`` வடிவங்கள் இன்னும் செல்லுபடியாகும். காண்க: ref: `setup-py- deprecated`." + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "உருவாக்க பின்தளத்தில் அறிவித்தல்" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" +"`` [பில்ட்-சிச்டம்] `` அட்டவணையில் ஒரு `` பில்ட்-பேக்கெண்ட்`` விசையைக் கொண்டுள்ளது, இது " +"பயன்படுத்த வேண்டிய பின்தளத்தில் குறிப்பிடுகிறது. இது ஒரு `` தேவைப்படும் `விசையும் " +"உள்ளது, இது திட்டத்தை உருவாக்கத் தேவையான சார்புகளின் பட்டியல் - இது பொதுவாக உருவாக்கும் " +"பின்தளத்தில் தொகுப்பாகும், ஆனால் அதில் கூடுதல் சார்புகளும் இருக்கலாம். பதிப்புகளையும் நீங்கள் " +"கட்டுப்படுத்தலாம், எ.கா., `` தேவை = [\"செட்டப்டூல்ச்> = 61.0\"] ``." + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" +"வழக்கமாக, உங்கள் உருவாக்க பின்தளத்தில் ஆவணங்கள் பரிந்துரைப்பதை நீங்கள் நகலெடுக்கவும் (பிறகு: " +"குறிப்பு: `உங்கள் கட்டமைப்பைத் தேர்ந்தெடுப்பது <தேர்வு-கட்டும்-பின்>`). சில பொதுவான " +"கட்டமைப்பிற்கான மதிப்புகள் இங்கே:" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "நிலையான எதிராக மாறும் மேனிலை தரவு" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "இந்த வழிகாட்டியின் மீதமுள்ளவை `` [திட்டம்] `` அட்டவணைக்கு அர்ப்பணிக்கப்பட்டுள்ளன." + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" +"பெரும்பாலான நேரங்களில், நீங்கள் ஒரு `` [திட்டம்] `` புலத்தின் மதிப்பை நேரடியாக " +"எழுதுவீர்கள். எடுத்துக்காட்டாக: `` தேவை-பைதான் = \"> = 3.8\" ``, அல்லது `` பதிப்பு = " +"\"1.0\" ``." + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" +"இருப்பினும், சில சந்தர்ப்பங்களில், உங்கள் உருவாக்க பின்தளத்தில் உங்களுக்காக மெட்டாடேட்டாவைக் " +"கணக்கிட அனுமதிப்பது பயனுள்ளதாக இருக்கும். எடுத்துக்காட்டாக: உங்கள் குறியீட்டில் உள்ள `__ " +"பதிப்பு__`` என்ற பண்புகளிலிருந்து, ஒரு அறிவிலி குறிச்சொல் அல்லது அதற்கு ஒத்ததாக " +"பலவற்றை உருவாக்கும் பின்தளத்தில் கட்டலாம். இதுபோன்ற சந்தர்ப்பங்களில், நீங்கள் புலத்தை மாறும் " +"எனக் குறிக்க வேண்டும், எ.கா.," + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" +"ஒரு புலம் மாறும் போது, அதை நிரப்புவது பின்தளத்தில் பொறுப்பு. அது எவ்வாறு செய்கிறது " +"என்பதை அறிய உங்கள் உருவாக்க பின்தளத்தில் ஆவணத்தை அணுகவும்." + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "அடிப்படை செய்தி" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "`` பெயர்``" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" +"உங்கள் திட்டத்தின் பெயரை பைபியில் வைக்கவும். இந்த புலம் தேவைப்படுகிறது மற்றும் மாறும் எனக் " +"குறிக்க முடியாத ஒரே புலம்." + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" +"திட்டத்தின் பெயர் ASCII கடிதங்கள், இலக்கங்கள், \"` _`` \", ஐபன்கள்\" `` -` \"மற்றும்\" " +"`` .`` \"ஆகியவற்றை அடிக்கோடிட்டுக் காட்ட வேண்டும். இது ஒரு அடிக்கோடிட்ட, ஐபன் அல்லது " +"காலத்துடன் தொடங்கவோ முடிவடையவோ கூடாது." + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" +"திட்டப் பெயர்களின் ஒப்பீடு என்பது வழக்கு உணர்வற்றது மற்றும் தன்னிச்சையாக நீண்டகாலமாக " +"அண்டர்ச்கோர்ச், ஐபன்கள் மற்றும்/அல்லது காலங்களை சமமாக நடத்துகிறது. எடுத்துக்காட்டாக, நீங்கள் " +"`` கூல்-ச்டஃப்`` என்ற திட்டத்தை பதிவுசெய்தால், பயனர்கள் அதை பதிவிறக்கம் செய்ய முடியும் " +"அல்லது பின்வரும் ஏதேனும் எழுத்துப்பிழைகளைப் பயன்படுத்தி அதை சார்புநிலையை அறிவிக்க " +"முடியும்: `` கூல்-ச்டஃப்``, `` கூல்.ச்டஃப் ``, `` கூல்_ச்டஃப்``, `` கூல் __- .-__ " +"பொருள்``." + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "உங்கள் திட்டத்தின் பதிப்பை வைக்கவும்." + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" +"`` 2020.0.0A1`` (ஆல்பா வெளியீட்டிற்கு) போன்ற இன்னும் சில சிக்கலான பதிப்பு " +"குறிப்பிடப்பட்டவர்கள் சாத்தியமானவை; முழு விவரங்களுக்கு `விவரக்குறிப்பு <பதிப்பு-" +"விவரக்குறிப்புகள்>` ஐப் பார்க்கவும்." + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" +"இந்த புலம் தேவைப்படுகிறது, இருப்பினும் இது பெரும்பாலும் மாறும் என்று குறிக்கப்பட்டுள்ளது" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" +"`` __Version__`` பண்புக்கூறு அல்லது ஒரு அறிவிலி குறிச்சொல்லிலிருந்து பதிப்பை " +"நிரப்புவது போன்ற நிகழ்வுகளைப் பயன்படுத்த இது அனுமதிக்கிறது. மேலும் விவரங்களுக்கு `ஒற்றை-" +"மூல-பதிப்பு` கலந்துரையாடலை அணுகவும்." + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "சார்பு மற்றும் தேவைகள்" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "`` சார்புகள்``/`` விருப்ப-சார்புநிலைகள்``" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "உங்கள் திட்டத்திற்கு சார்பு இருந்தால், அவற்றை இப்படி பட்டியலிடுங்கள்:" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" +"காண்க: குறிப்பு: `சார்பு குறிப்பான்கள் <சார்பு-விவரக்குறிப்புகள்>` முழு தொடரியல் மூலம் " +"பதிப்புகளைக் கட்டுப்படுத்த நீங்கள் பயன்படுத்தலாம்." + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" +"உங்கள் தொகுப்பின் ஒரு குறிப்பிட்ட அம்சத்திற்கு மட்டுமே தேவைப்பட்டால், உங்கள் சார்புகளில் " +"சிலவற்றை விருப்பமாக மாற்ற நீங்கள் விரும்பலாம். அவ்வாறான நிலையில், அவற்றை `` விருப்ப-" +"சார்புநிலைகளில் வைக்கவும்`." + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" +"விசைகள் ஒவ்வொன்றும் \"பேக்கேசிங் கூடுதல்\" என்பதை வரையறுக்கிறது. மேலே உள்ள " +"எடுத்துக்காட்டில், ஒருவர் பயன்படுத்தலாம், எ.கா." + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "``-பைதான் தேவை`" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" +"நீங்கள் ஆதரிக்கும் பைத்தானின் குறைந்தபட்ச பதிப்பை அறிவிக்க இது உங்களை அனுமதிக்கிறது [#-" +"க்கு-பைதான்-மேல்-பிணைப்புகள் தேவை] _." + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "இயங்கக்கூடிய ச்கிரிப்ட்களை உருவாக்குதல்" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" +"உங்கள் தொகுப்பின் ஒரு பகுதியாக ஒரு கட்டளையை நிறுவ, அதை `` [project.scripts] `` " +"அட்டவணையில் அறிவிக்கவும்." + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" +"இந்த எடுத்துக்காட்டில், உங்கள் திட்டத்தை நிறுவிய பிறகு, ஒரு `` ச்பேம்-கிளி`` கட்டளை " +"கிடைக்கும். இந்த கட்டளையை செயல்படுத்துவது `` இறக்குமதி sys க்கு சமமானதாக இருக்கும்; " +"ச்பேம் இறக்குமதி Main_cli இலிருந்து; sys.exit (main_cli ()) ``." + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" +"சாளரங்களில், இந்த வழியில் தொகுக்கப்பட்ட ச்கிரிப்ட்களுக்கு ஒரு முனையம் தேவை, எனவே நீங்கள் " +"அவற்றை ஒரு வரைகலை பயன்பாட்டிலிருந்து தொடங்கினால், அவை ஒரு முனையத்தை பாப் அப் செய்யும். " +"இது நிகழாமல் தடுக்க, `` [project.scripts] `` என்பதற்கு பதிலாக `` [project.gui-" +"scripts] `` அட்டவணையைப் பயன்படுத்தவும்." + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" +"அவ்வாறான நிலையில், உங்கள் ச்கிரிப்டை கட்டளை வரியிலிருந்து தொடங்குவது உடனடியாக " +"கட்டுப்பாட்டைக் கொடுக்கும், ச்கிரிப்டை பின்னணியில் இயக்கும்." + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" +"`` [Project.scripts] `` மற்றும் `` [project.gui-scripts] `` ஆகியவற்றுக்கு " +"இடையேயான வேறுபாடு சாளரங்களில் மட்டுமே பொருத்தமானது." + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "உங்கள் திட்டம் பற்றி" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "`` ஆசிரியர்கள்`/`` பராமரிப்பாளர்கள்``" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" +"இந்த இரண்டு துறைகளிலும் ஒரு பெயர் மற்றும்/அல்லது மின்னஞ்சல் முகவரியால் அடையாளம் காணப்பட்ட " +"நபர்களின் பட்டியல்கள் உள்ளன." + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "`` விளக்கம்``" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" +"இது உங்கள் திட்டத்தின் ஒரு வரி விளக்கமாக இருக்க வேண்டும், இது உங்கள் திட்ட பக்கத்தின் " +"\"தலைப்பு\" என்று பைபியில் (`எடுத்துக்காட்டு ` _), மற்றும் தேடல் " +"முடிவுகளின் பட்டியல்கள் போன்ற பிற இடங்கள் (`எடுத்துக்காட்டு < pypi-search-pip_> `_)." + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "`` ரீட்மே``" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" +"இது உங்கள் திட்டத்தின் நீண்ட விளக்கமாகும், இது உங்கள் திட்ட பக்கத்தில் PYPI இல் காண்பிக்க. " +"பொதுவாக, உங்கள் திட்டத்தில் `` readme.md`` அல்லது `` Readme.rst`` கோப்பைக் " +"கொண்டிருக்கும், மேலும் அதன் கோப்பு பெயரை இங்கே வைக்கவும்." + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "README இன் வடிவம் நீட்டிப்பிலிருந்து தானாக கண்டறியப்படுகிறது:" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "`` Readme.md`` → `கிதுப்-சுவை கொண்ட மார்க் பேரூர் ` _," + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "`` Readme.rst`` → `மறுசீரமைப்பு ` _ (Sphinx நீட்டிப்புகள் இல்லாமல்)." + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "இது போன்ற வடிவமைப்பையும் நீங்கள் வெளிப்படையாகக் குறிப்பிடலாம்:" + +#: ../source/guides/writing-pyproject-toml.rst:297 +#, fuzzy +#| msgid "``license-files``" +msgid "``license`` and ``license-files``" +msgstr "`` உரிம-கோப்புகள்``" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +#, fuzzy +#| msgid "" +#| "This is a valid :term:`SPDX license expression ` " +#| "consisting of one or more :term:`license identifiers `. The full license list is available at the `SPDX license " +#| "list page `_. The supported list version is 3.17 or any " +#| "later compatible one." +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" +"இது செல்லுபடியாகும்: சொல்: `SPDX உரிம வெளிப்பாடு <உரிம வெளிப்பாடு>` ஒன்று அல்லது " +"அதற்கு மேற்பட்டவற்றைக் கொண்டது: கால: `உரிம அடையாளங்காட்டிகள் <உரிம அடையாளங்காட்டி>`. " +"முழு உரிம பட்டியல் `SPDX உரிம பட்டியல் பக்கத்தில் ` _ இல் " +"கிடைக்கிறது. ஆதரிக்கப்பட்ட பட்டியல் பதிப்பு 3.17 அல்லது பின்னர் இணக்கமான ஒன்றாகும்." + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +#, fuzzy +#| msgid "hatch" +msgid "hatchling" +msgstr "அட்ச்" + +#: ../source/guides/writing-pyproject-toml.rst:313 +#, fuzzy +#| msgid "Setuptools" +msgid "setuptools" +msgstr "Setuptools" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +#, fuzzy +#| msgid "Build backends" +msgid "pdm-backend" +msgstr "பின்தளத்தில் உருவாக்குங்கள்" + +#: ../source/guides/writing-pyproject-toml.rst:316 +#, fuzzy +#| msgid "poetry" +msgid "poetry-core" +msgstr "பா" + +#: ../source/guides/writing-pyproject-toml.rst:317 +#, fuzzy +#| msgid "build" +msgid "uv-build" +msgstr "உருவாக்கு" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "`` உரிமம்``" + +#: ../source/guides/writing-pyproject-toml.rst:331 +#, fuzzy +#| msgid "" +#| "This is a valid :term:`SPDX license expression ` " +#| "consisting of one or more :term:`license identifiers `. The full license list is available at the `SPDX license " +#| "list page `_. The supported list version is 3.17 or any " +#| "later compatible one." +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" +"இது செல்லுபடியாகும்: சொல்: `SPDX உரிம வெளிப்பாடு <உரிம வெளிப்பாடு>` ஒன்று அல்லது " +"அதற்கு மேற்பட்டவற்றைக் கொண்டது: கால: `உரிம அடையாளங்காட்டிகள் <உரிம அடையாளங்காட்டி>`. " +"முழு உரிம பட்டியல் `SPDX உரிம பட்டியல் பக்கத்தில் ` _ இல் " +"கிடைக்கிறது. ஆதரிக்கப்பட்ட பட்டியல் பதிப்பு 3.17 அல்லது பின்னர் இணக்கமான ஒன்றாகும்." + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" +"ஒரு பொதுவான விதியாக, குழப்பத்தைத் தவிர்ப்பதற்காக, ஒரு நிலையான, நன்கு அறியப்பட்ட " +"உரிமத்தைப் பயன்படுத்துவது நல்லது, ஏனெனில் சில நிறுவனங்கள் உரிமம் அங்கீகரிக்கப்படாத " +"மென்பொருளைத் தவிர்ப்பதால்." + +#: ../source/guides/writing-pyproject-toml.rst:353 +#, fuzzy +#| msgid "" +#| "If your project is licensed with a license that doesn't have an existing " +#| "SPDX identifier, you can create a custom one in format ``LicenseRef-" +#| "[idstring]``. The custom identifiers must follow the SPDX specification, " +#| "`clause 10.1 `_ of the version 2.2 or any later " +#| "compatible one." +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" +"ஏற்கனவே உள்ள SPDX அடையாளங்காட்டி இல்லாத உரிமத்துடன் உங்கள் திட்டத்திற்கு உரிமம் " +"வழங்கப்பட்டால், நீங்கள் தனிப்பயன் ஒன்றை வடிவத்தில் உருவாக்கலாம் `` licenseref- [idstring] " +"``. தனிப்பயன் அடையாளங்காட்டிகள் SPDX விவரக்குறிப்பைப் பின்பற்ற வேண்டும், `பிரிவு 10.1 " +" _ _ _ _ _ _ அல்லது பின்னர் இணக்கமான ஏதேனும் ஒன்று." + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "`` உரிம-கோப்புகள்``" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" +"இது உங்கள் தொகுப்புடன் விநியோகிக்க விரும்பும் பிற சட்டத் தகவல்களைக் கொண்ட உரிமக் கோப்புகள் " +"மற்றும் கோப்புகளின் பட்டியல்." + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "குளோப் வடிவங்கள் விவரக்குறிப்பைப் பின்பற்ற வேண்டும்:" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" +"எண்ணெழுத்து எழுத்துக்கள், அடிக்கோடிட்டு (`` _``), ஐபன்கள் (`` -``) மற்றும் புள்ளிகள் " +"(`` .``) ஆகியவை சொற்களஞ்சியத்துடன் பொருந்தும்." + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" +"சிறப்பு எழுத்துக்கள்: ``*``, ``? ``, `` ** `` மற்றும் எழுத்து வரம்புகள்: [] " +"ஆதரிக்கப்படுகின்றன." + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "பாதை டிலிமிட்டர்கள் முன்னோக்கி ச்லாச் எழுத்துக்குறியாக இருக்க வேண்டும் (``/``)." + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" +"வடிவங்கள் கொண்ட கோப்பகத்துடன் தொடர்புடையவை: கோப்பு: `pyproject.toml`, இதனால் ஒரு ச்லாச் " +"பாத்திரத்துடன் தொடங்கக்கூடாது." + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "பெற்றோர் அடைவு குறிகாட்டிகள் (`` ..``) பயன்படுத்தப்படக்கூடாது." + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "ஒவ்வொரு குளோபும் குறைந்தது ஒரு கோப்பை பொருத்த வேண்டும்." + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" +"நேரடி பாதைகள் செல்லுபடியாகும் குளோப்கள். இந்த விவரக்குறிப்பால் மூடப்படாத எந்த எழுத்துக்கள் " +"அல்லது எழுத்துக்குறி காட்சிகளும் தவறானவை." + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "`` முக்கிய வார்த்தைகள்``" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" +"இந்த முக்கிய வார்த்தைகளை மக்கள் தேடும்போது உங்கள் திட்டத்தை பரிந்துரைக்க இது பைபியின் தேடல் " +"பெட்டியை உதவும்." + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "`` வகைப்படுத்திகள்``" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" +"உங்கள் திட்டத்திற்கு பொருந்தும் PYPI வகைப்படுத்திகளின் பட்டியல். `சாத்தியக்கூறுகளின் முழு " +"பட்டியலையும் சரிபார்க்கவும் <வகைப்படுத்தி-பட்டியல்_>` _." + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" +"ஒரு திட்டம் ஆதரிக்கும் பைதான் பதிப்புகள் என்ன என்பதை அறிவிக்க வகைப்படுத்திகளின் பட்டியல் " +"பெரும்பாலும் பயன்படுத்தப்பட்டாலும், இந்த செய்தி திட்டங்களை நிறுவுவதற்கு அல்ல, PYPI இல் " +"திட்டங்களைத் தேடுவதற்கும் உலாவுவதற்கும் மட்டுமே பயன்படுத்தப்படுகிறது. ஒரு திட்டத்தை " +"நிறுவக்கூடிய பைதான் பதிப்புகளை உண்மையில் கட்டுப்படுத்த, பயன்படுத்தவும்: ref: `-பைதான் " +"தேவை." + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" +"ஒரு தொகுப்பு PYPI இல் பதிவேற்றப்படுவதைத் தடுக்க, சிறப்பு `` தனிப்பட்ட :: பதிவேற்ற " +"வேண்டாம்`` வகைப்படுத்தியைப் பயன்படுத்தவும். `` தனிப்பட்ட :: `` உடன் தொடங்கி " +"வகைப்படுத்திகளுடன் தொகுப்புகளை PYPI எப்போதும் நிராகரிக்கும்." + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "`` urls``" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" +"உங்கள் திட்டத்துடன் தொடர்புடைய முகவரி களின் பட்டியல், உங்கள் PYPI திட்ட பக்கத்தின் இடது " +"பக்கப்பட்டியில் காட்டப்படும்." + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" +"காண்க: குறிப்பு: பைபி மற்றும் பிற பேக்கேசிங் கருவிகள் குறிப்பாக அறிந்த லேபிள்களின் " +"பட்டியலுக்கு `நன்கு அறியப்பட்ட-லேபிள்கள்`, மற்றும்` பைபியின் திட்ட மேனிலை தரவு டாக்ச் " +" `_ PYPI- குறிப்பிட்ட " +"முகவரி செயலாக்கத்திற்கு." + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" +"லேபிளில் இடைவெளிகள் இருந்தால், அதை மேற்கோள் காட்ட வேண்டும், எ.கா., `` வலைத்தளம் = " +"\"https://example.com\" ." + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" +"பயனர்கள் பயன்படுத்த அறிவுறுத்தப்படுகிறார்கள்: ref: `நன்கு அறியப்பட்ட-லேபிள்கள்` தங்கள் திட்ட " +"முகவரி களுக்கு பொருத்தமான இடங்களில், மெட்டாடேட்டாவின் நுகர்வோர் (தொகுப்பு குறியீடுகள் " +"போன்றவை) தங்கள் விளக்கக்காட்சியை நிபுணத்துவம் பெற முடியும்." + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" +"எடுத்துக்காட்டாக, பின்வரும் மெட்டாடேட்டாவில், `` MyHomePage`` அல்லது `` \"பதிவிறக்கம் " +"இணைப்பு\" `` என்பது ஒரு நன்கு அறியப்பட்ட சிட்டை, எனவே அவை சொற்களஞ்சியமாக வழங்கப்படும்:" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" +"இந்த மெட்டாடேட்டாவில் `` முகப்புப்பக்கத்தில்`` மற்றும் `பதிவிறக்கம்`` இரண்டும் நன்கு " +"அறியப்பட்ட சமமானவை (` `முகப்புப்பக்கத்தை`` மற்றும்` பதிவிறக்கம்``) கொண்டுள்ளன, மேலும் அந்த " +"சொற்பொருளை மனதில் கொண்டு வழங்கலாம் (திட்டத்தின் முகப்புப் பக்கம் மற்றும் அதன் வெளிப்புற " +"பதிவிறக்க இடம் முறையே)." + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "மேம்பட்ட செருகுநிரல்கள்" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" +"சில தொகுப்புகளை செருகுநிரல்கள் மூலம் நீட்டிக்க முடியும். எடுத்துக்காட்டுகளில் பைடெச்ட்_ " +"மற்றும் பைக்மென்ட்ச்_ ஆகியவை அடங்கும். அத்தகைய சொருகி உருவாக்க, நீங்கள் அதை `` " +"[Project.entry- புள்ளிகள்] `` இதைப் போன்ற ஒரு துணைப்பிரிவில் அறிவிக்க வேண்டும்:" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "பார்க்க: ref: `சொருகி வழிகாட்டி <சொருகி-நுழைவு புள்ளிகள்>` மேலும் தகவலுக்கு." + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "ஒரு முழு சான்று" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" +"``-பைதான் = \"<= 3.10\" `` இங்கே. `இந்த வலைப்பதிவு இடுகையில் <-பைதான்-பிளாக்-" +"போச்ட்_>` _ சாத்தியமான சிக்கல்கள் தொடர்பான சில தகவல்களைக் கொண்டுள்ளது." + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" +"பைதான் பேக்கேசிங் பயனர் கையேடு (பைபக்) என்பது பைதான் மென்பொருளை பேக்கேசிங் செய்வதற்கான " +"பயிற்சிகள் மற்றும் வழிகாட்டிகளின் தொகுப்பாகும்." + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "பைதான், பேக்கேசிங், வழிகாட்டி, பயிற்சி" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "பைதான் பேக்கேசிங் பயனர் கையேடு" + +#: ../source/index.rst:25 +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." +msgstr "" +"நவீன கருவிகளுடன் பைதான் தொகுப்புகளை விநியோகிக்கவும் நிறுவவும் உதவும் பயிற்சிகள் மற்றும் " +"குறிப்புகளின் தொகுப்பான *பைதான் பேக்கேசிங் பயனர் கையேடு *க்கு வருக." + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" +"இந்த வழிகாட்டி `கிதுப்`_ இல் பராமரிக்கப்படுகிறது: டாக்:` பைதான் பேக்கேசிங் ஆணையம் " +"<பைபா: குறியீட்டு> `. நாங்கள் மகிழ்ச்சியுடன் ஏற்றுக்கொள்கிறோம்: டாக்: `பங்களிப்புகள் மற்றும் " +"பின்னூட்டங்கள் <பங்களிப்பு>`. ." + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "கண்ணோட்டம் மற்றும் ஓட்டம்" + +#: ../source/index.rst:40 +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." +msgstr "" +"பைதான் பேக்கேசிங் பற்றிய உங்கள் புரிதலை உருவாக்குவது ஒரு பயணம். பொறுமை மற்றும் " +"தொடர்ச்சியான முன்னேற்றம் ஆகியவை வெற்றிக்கு முதன்மை. கண்ணோட்டம் மற்றும் ஓட்ட பிரிவுகள் பைதான் " +"பேக்கேசிங் சுற்றுச்சூழல் அமைப்பைப் புரிந்துகொள்வதற்கான தொடக்க புள்ளியை வழங்குகின்றன." + +#: ../source/index.rst:44 +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." +msgstr "" +"தி: டாக்: `கண்ணோட்டம்` திட்டங்களைத் தயாரிக்கும் மற்றும் விநியோகிக்கும் போது பைதான் " +"பேக்கேசிங் மற்றும் அதன் பயன்பாட்டை விளக்குகிறது. உங்கள் பயன்பாட்டு வழக்குக்கு மிகவும் " +"பொருத்தமான கருவிகள் மற்றும் செயல்முறைகளைத் தேர்ந்தெடுப்பது பற்றிய புரிதலை உருவாக்க இந்த " +"பிரிவு உங்களுக்கு உதவுகிறது. பேக்கேசிங் என்றால் என்ன, அது தீர்க்கும் சிக்கல்கள் மற்றும் " +"முக்கிய பரிசீலனைகள் இதில் அடங்கும்." + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" +"உங்கள் குறியீட்டை வெளியிடப் பயன்படுத்தப்படும் பணிப்பாய்வுகளின் கண்ணோட்டத்தைப் பெற, காண்க: " +"டாக்: `பேக்கேசிங் ஓட்டம் `." + +#: ../source/index.rst:57 +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:" +msgstr "" +"பயிற்சிகள் முதல் முறையாக ஒரு திட்டத்தை முடிக்க தேவையான படிகளை கடந்து செல்கின்றன. " +"பயிற்சிகள் உங்களுக்கு வெற்றிபெற உதவுவதையும் எதிர்கால ஆய்வுக்கு ஒரு தொடக்க புள்ளியை " +"வழங்குவதையும் நோக்கமாகக் கொண்டுள்ளன. தி: டாக்: `டுடோரியல்கள்/குறியீட்டு` பிரிவில் " +"பின்வருவன அடங்கும்:" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "ப: டிஓசி: `தொகுப்புகளை நிறுவுவதற்கான பயிற்சி <பயிற்சிகள்/நிறுவல்-பேக்கேச்கள்>`" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" +"ப: டாக்: `விண்ணப்ப சார்புகளை நிர்வகிப்பதற்கான பயிற்சி <பயிற்சிகள்/நிர்வாக-சார்புநிலைகள்>` " +"பதிப்பு கட்டுப்படுத்தப்பட்ட திட்டத்தில்" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" +"ப: டாக்: `பேக்கேசிங் மற்றும் விநியோகித்தல் பற்றிய பயிற்சி <டுடோரியல்கள்/பேக்கேசிங்-" +"திட்டங்கள்>` உங்கள் திட்டம்" + +#: ../source/index.rst:71 +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." +msgstr "" +"வழிகாட்டிகள் ஒரு குறிப்பிட்ட பணியைச் செய்ய நடவடிக்கைகளை வழங்குகின்றன. பைதான் " +"பேக்கேசிங்கை ஏற்கனவே அறிந்த மற்றும் குறிப்பிட்ட தகவல்களைத் தேடும் பயனர்களுக்கு வழிகாட்டிகள் " +"அதிக கவனம் செலுத்துகின்றன." + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" +"தி: டாக்: `வழிகாட்டிகள்/குறியீட்டு` பிரிவு மூன்று முக்கிய பகுதிகளில்\" எப்படி " +"\"அறிவுறுத்தல்களை வழங்குகிறது: தொகுப்பு நிறுவல்; தொகுப்புகளை உருவாக்குதல் மற்றும் " +"விநியோகித்தல்; இதர தலைப்புகள்." + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "விளக்கங்கள் மற்றும் விவாதங்கள்" + +#: ../source/index.rst:82 +#, fuzzy +#| msgid "" +#| "The :doc:`discussions/index` section for in-depth explanations and " +#| "discussion about topics, such as:" +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" +"தி: டாக்: `விவாதங்கள்/குறியீட்டு` பிரிவு போன்ற தலைப்புகள் பற்றிய விவாதங்களுக்கான " +"பிரிவு: போன்றவை:" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr ": டாக்: `விவாதங்கள்/வரிசைப்படுத்தல்-பைதான்-பயன்பாடுகள்`" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr ": டாக்: `விவாதங்கள்/பிஐபி-விஎச்-ஈசி-இன்ச்டால்`" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "குறிப்பு" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" +"தி: டாக்: `விவரக்குறிப்புகள்/குறியீட்டு` பிரிவு இயங்கக்கூடிய விவரக்குறிப்புகளை " +"பேக்கேசிங் செய்வதற்கான பிரிவு." + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" +"பட்டியல்: DOC: `பிற திட்டங்கள் ` பைதான் பேக்கேசிங் அதிகாரசபையின் " +"உறுப்பினர்களால் பராமரிக்கப்படுகிறது." + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" +"தி: டாக்: `சொற்களஞ்சியம்` பைதான் பேக்கேசிங்கில் பயன்படுத்தப்படும் சொற்களின் வரையறைகளுக்கு." + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "திட்ட சுருக்கங்கள்" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" +"பைதான் நிறுவல் மற்றும் பேக்கேசிங் இடைவெளியில் மிகவும் பொருத்தமான திட்டங்களுக்கான " +"சுருக்கங்கள் மற்றும் இணைப்புகள்." + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "பைபா திட்டங்கள்" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "bandersnatch" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`டாக்ச் ` __ | `சிக்கல்கள் __ | `Github ` __ | `Pypi ____" + +#: ../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 இன் உள்ளடக்க விநியோக நெட்வொர்க்கை (சி.டி.என்) பெரிதும் " +"ஏற்றுவதைத் தடுக்கவும். கோப்புகளை உள்ளக கோப்பகத்திலிருந்து அல்லது `AWS S3`_ இலிருந்து " +"வழங்கலாம்." + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "உருவாக்கு" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +": ஏதேனும்: `டாக்ச் <உருவாக்க: குறியீட்டு>` | `சிக்கல்கள் ` __ | `Github ` __ | `Pypi " +"` __" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" +"`` பில்ட்`` என்பது ஒரு: பெப்: `517` இணக்கமான பைதான் தொகுப்பு பில்டர். இது தொகுப்புகளை " +"உருவாக்க ஒரு சி.எல்.ஐ மற்றும் ஒரு பைதான் பநிஇ ஆகியவற்றை வழங்குகிறது." + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "cibuildwheel" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" +"`டாக்ச் ` __ | `சிக்கல்கள் ` __ | `Github __ | `Pypi ` __ | " +"`விவாதங்கள் ` __ | `டிச்கார்ட் " +"#cibuildwheel ` __" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" +"`` cibuildwheel`` என்பது ஒரு பைதான் தொகுப்பாகும்: கால: `சக்கரங்கள் ` அனைத்து " +"பொதுவான தளங்களுக்கும் பெரும்பாலான தொஒ அமைப்புகளில் பைதான் பதிப்புகளுக்கும். மேலும் " +"காண்க: குறிப்பு: `மல்டிபில்ட்`." + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "தொலைதூர" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +": டாக்: `டாக்ச் <டிச்ட்லிப்: குறியீட்டு>` | `சிக்கல்கள் __ | `Github ` __ | `Pypi " +"` __" + +#: ../source/key_projects.rst:73 +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." +msgstr "" +"`` டிச்ட்லிப்`` என்பது பைதான் மென்பொருளின் பேக்கேசிங் மற்றும் விநியோகத்துடன் தொடர்புடைய " +"குறைந்த அளவிலான செயல்பாடுகளை செயல்படுத்தும் ஒரு நூலகம். `` டிச்ட்லிப்`` பல தொடர்புடைய " +"PEP களை (பைதான் மேம்பாட்டு முன்மொழிவு தரநிலைகள்) செயல்படுத்துகிறது மற்றும் மூன்றாம் " +"தரப்பு பேக்கேசிங் கருவிகளை உருவாக்கி பைனரி மற்றும் மூலத்தை உருவாக்குவதற்கும் " +"பதிவேற்றுவதற்கும் இது பயனுள்ளதாக இருக்கும்: கால: `விநியோகங்கள் <விநியோக தொகுப்பு>`, " +"இயங்குதளங்களை அடையலாம், சார்புகளைத் தீர்க்கவும், தொகுப்பு வளங்களை நிர்வகிக்கவும், பிற ஒத்த " +"செயல்பாடுகளைச் செய்யவும்." + +#: ../source/key_projects.rst:82 +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." +msgstr "" +"நவீன பைதான் பேக்கேசிங் இயங்குதள தரங்களை குறிப்பாக செயல்படுத்தும் கடுமையான: ref: " +"`பேக்கேசிங்` திட்டம் (கீழே) போலல்லாமல், நவீன இயங்குதன்மை தரநிலைகள் மற்றும் மரபு தொகுப்புகள் " +"மற்றும் மெட்டாடேட்டாவைக் கையாளும்படி கேட்கும்போது நியாயமான குறைவடையும் நடத்தைகளை வழங்க " +"முயற்சிக்கிறது. அந்த தரங்களுடன் பொருந்தாத தொகுப்புகளின் துணைக்குழுவில் விழுங்கள்." + +#: ../source/key_projects.rst:93 +msgid "distutils" +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 "" +"அசல் பைதான் பேக்கேசிங் அமைப்பு, பைதான் 2.0 இல் உள்ள நிலையான நூலகத்தில் சேர்க்கப்பட்டு 3.12 " +"இல் அகற்றப்பட்டது." + +#: ../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 "" +"அம்ச புதுப்பிப்புகள் மொழி இயக்க நேர புதுப்பிப்புகளுடன் இறுக்கமாக இணைக்கப்படும் ஒரு " +"பேக்கேசிங் முறையை பராமரிப்பதில் உள்ள சவால்கள் காரணமாக, நேரடி பயன்பாடு: ref: " +"`தொலைதூரங்கள்` தீவிரமாக ஊக்கமளிக்கப்பட்டுள்ளன, இதனுடன்: குறிப்பு:` செடிப்டூல்ச்` " +"விருப்பமான மாற்றாக இருப்பது. ." + +#: ../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 "" +"இதன் விளைவாக, குறிப்பு: `தொலைதூரங்கள்` பைத்தானில் 3.10 இல் நீக்கப்பட்டன: PEP: `632` " +"மற்றும் உள்ளது: DOC:` அகற்றப்பட்டது <பைத்தான்: வாட்ச்நியூ/3.12> `பைத்தானில் உள்ள நிலையான " +"நூலகத்திலிருந்து 3.12. Setuptools டிச்டிடில்களின் முழுமையான நகலை மூட்டுகிறது, " +"மேலும் நீங்கள் முதலில் செட்டப்டூல்களை இறக்குமதி செய்தால் அல்லது PIP ஐப் பயன்படுத்தினால் இது " +"பைதான் <3.12 இல் கூட செலுத்தப்படுகிறது." + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "ஃபிளிட்" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" +"`டாக்ச் __ | `சிக்கல்கள் ` __ | `Pypi ` __" + +#: ../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 "" +"தூய பைதான் தொகுப்புகள் மற்றும் தொகுதிகளை PYPI க்கு உருவாக்கி பதிவேற்ற ஒரு எளிய வழியை " +"FLIT வழங்குகிறது. இது `எளிதான விசயங்களை எளிதாக்குவதில் கவனம் செலுத்துகிறது <ஃபிளிட்-" +"ரேசன்_>` _ பேக்கேசிங்கிற்கு. ஒரு எளிய திட்டத்தை விரைவாக அமைக்கவும், மூல விநியோகங்கள் " +"மற்றும் சக்கரங்களை உருவாக்கவும், அவற்றை PYPI இல் பதிவேற்றவும் ஃபிளிட் ஒரு உள்ளமைவு கோப்பை " +"உருவாக்க முடியும்." + +#: ../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`` ஐப் பயன்படுத்துகிறது. ஃபிளிட் போன்ற " +"கருவிகளை நம்பவில்லை: குறிப்பு: விநியோகங்களை உருவாக்க `செடிப்டூல்ச்`, அல்லது: ref:` " +"ட்வைன்` அவற்றை பைபியில் பதிவேற்ற. ஃப்ளிட்டுக்கு பைதான் 3 தேவைப்படுகிறது, ஆனால் பைதான் 2 " +"க்கான தொகுதிகளை விநியோகிக்க நீங்கள் அதைப் பயன்படுத்தலாம், அவை பைதான் 3 இல் இறக்குமதி " +"செய்யப்படும் வரை." + +#: ../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 "" +"ஃபிளிட் தொகுப்பு `மத்தியாச் புச்சன்னியர் ` __ அக்டோபர் " +"2023 முதல் `டிடெலிஃப்ட் இயங்குதளத்தில் __, மற்றும் பி.எச்.எஃப் -க்கு அனுப்பப்பட்ட பொருள் மற்றும் பைபா பயன்பாட்டிற்காக " +"ஒதுக்கப்பட்டுள்ளது." + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "அட்ச்" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`டாக்ச் ` __ | `Github ` __ | `Pypi ____" + +#: ../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 "" +"அட்ச் என்பது ஒரு ஒருங்கிணைந்த கட்டளை-வரி கருவியாகும், அதாவது பைதான் டெவலப்பர்களுக்கான " +"சார்புநிலைகள் மற்றும் சுற்றுச்சூழல் தனிமைப்படுத்தலை வசதியாக நிர்வகிப்பதாகும். பைதான் " +"தொகுப்பு உருவாக்குபவர்கள் அட்ச் மற்றும் அதன்: காலத்தைப் பயன்படுத்துகிறார்கள்: `பின்தளத்தில் " +"உருவாக்கு <பின்தளத்தில் உருவாக்கு>` கட்டமைக்க, பதிப்பு, சார்புநிலைகளை குறிப்பிடுதல் " +"மற்றும் PYPI க்கு தொகுப்புகளை வெளியிடுவது. அதன் சொருகி அமைப்பு செயல்பாட்டை எளிதில் " +"நீட்டிக்க அனுமதிக்கிறது." + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "பொதியாக்கம்" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +": டாக்: `டாக்ச் <பேக்கேசிங்: குறியீட்டு>` | `சிக்கல்கள் ` __ | `Github ` __ | " +"`Pypi ` __" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" +"பயன்படுத்திய பைதான் பேக்கேசிங்கிற்கான முக்கிய பயன்பாடுகள்: ref: `பிப்` மற்றும்: " +"குறிப்பு:` செட்ப்டூல்ச்`." + +#: ../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 "" +"பேக்கேசிங் நூலகத்தில் உள்ள முக்கிய பயன்பாடுகள் பதிப்பு கையாளுதல், குறிப்பான்கள், " +"குறிப்பான்கள், தேவைகள், குறிச்சொற்கள் மற்றும் பைதான் தொகுப்புகளுக்கான ஒத்த பண்புக்கூறுகள் " +"மற்றும் பணிகள். பெரும்பாலான பைதான் பயனர்கள் இந்த நூலகத்தை வெளிப்படையாக அழைக்கத் " +"தேவையில்லாமல் நம்பியுள்ளனர்; இங்கே பட்டியலிடப்பட்டுள்ள பிற பைதான் பேக்கேசிங், வழங்கல் மற்றும் " +"நிறுவல் கருவிகளின் உருவாக்குபவர்கள் பெரும்பாலும் அதன் செயல்பாட்டைப் பயன்படுத்துகிறார்கள், " +"இது சார்பு பண்புகளை அலசவும், கண்டறியவும், கையாளவும் பயன்படுத்துகிறது." + +#: ../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: `பேக்கேசிங்-குறிப்பிட்டவை`, மேலும் அந்த தரங்களுடன் " +"பொருந்தாத போதுமான பழைய மரபு தொகுப்புகளுக்கான பிழைகளை புகாரளிக்கும். இதற்கு " +"நேர்மாறாக,: ref: `Distlib` திட்டம் என்பது மிகவும் அனுமதிக்கப்பட்ட நூலகமாகும், இது " +"தெளிவற்ற மெட்டாடேட்டாவை நம்பத்தகுந்த வாசிப்பை வழங்க முயற்சிக்கிறது: ref:` பேக்கேசிங்` " +"அதற்கு பதிலாக பிழையைப் புகாரளிக்கும்." + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "பிப்" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`டாக்ச் __ | `சிக்கல்கள் ` __ | `Github ` __ | `Pypi ____" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" +"பைதான் தொகுப்புகளை நிறுவுவதற்கான மிகவும் பிரபலமான கருவி, மற்றும் பைதானின் நவீன " +"பதிப்புகளுடன் சேர்க்கப்பட்டுள்ளது." + +#: ../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 "" +"இது PYPI மற்றும் பிற பைதான் தொகுப்பு குறியீடுகளிலிருந்து தொகுப்புகளைக் கண்டறிதல், " +"பதிவிறக்கம் செய்தல் மற்றும் நிறுவுவதற்கான அத்தியாவசிய முக்கிய அம்சங்களை வழங்குகிறது, " +"மேலும் அதன் கட்டளை-வரி இடைமுகம் (CLI) வழியாக பரந்த அளவிலான மேம்பாட்டு பணிப்பாய்வுகளில் " +"இணைக்கப்படலாம்." + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "பைபென்வ்" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +msgstr "" +": டாக்: `டாக்ச் <பைபென்வி: குறியீட்டு>` | `மூல ` " +"__ | `சிக்கல்கள் __ | `Pypi ____" + +#: ../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 "" +"பைபென்வி என்பது ஒரு திட்டமாகும், இது அனைத்து பேக்கேசிங் உலகங்களையும் பைதான் உலகிற்கு " +"கொண்டு வருவதை நோக்கமாகக் கொண்டுள்ளது. இது பயன்படுத்துகிறது: ref: `பிப்ஃபைல்`,: " +"குறிப்பு:` பிப்`, மற்றும்: ref: `Virtualenv` ஒரு ஒற்றை கருவித்தொகுப்பில். இது `` " +"தேவைகள்." + +#: ../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 "" +"கட்டளை வரியில் சூழல்கள், சார்புநிலைகள் மற்றும் இறக்குமதி செய்யப்பட்ட தொகுப்புகளை நிர்வகிக்க " +"பயனர்களுக்கு உதவுவதை பைபென்வி நோக்கமாகக் கொண்டுள்ளது. ஆச்-பூட்டப்பட்ட சார்பு " +"குறிப்பான்களுடன் இணங்குவதை உறுதிசெய்ய, இது விண்டோசிலும் (பிற கருவிகள் பெரும்பாலும் " +"அடிக்கோடிட்டுக் காட்டும்), கோப்பு ஆச்களை உருவாக்கி சரிபார்க்கிறது, மேலும் தொகுப்புகள் " +"மற்றும் சார்புகளை நிறுவல் நீக்குவதை எளிதாக்குகிறது." + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "பிப்ஃபைல்" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "`ஆதாரம் ` __" + +#: ../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` and its sister :file:`Pipfile.lock` அரே a higher-level " +"application-centric alternative பெறுநர் :ref:`pip`'s lower-" +"level :file:`requirements.txt` file." + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "PIPX" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" +"`டாக்ச் __ | `Github ` " +"__ | `Pypi ____" + +#: ../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 என்பது ஒரு கருவியாகும்." + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" +": டாக்: `டாக்ச் <குறியீட்டு>` | `சிக்கல்கள் ` __ | `Github __ __ __" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "இந்த வழிகாட்டி!" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "README_RENDER" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" +"`கிதுப் மற்றும் டாக்ச் __ | `Pypi " +" __ __ __" + +#: ../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`` என்பது ஒரு நூலகம் ஆகும், இது தொகுப்பு உருவாக்குபவர்கள் தங்கள் " +"பயனர் ஆவணங்களை (README) கோப்புகளை உஉகுமொ இல் மார்க்அப் மொழிகளான மார்க் பேரூர் அல்லது " +"மறுசீரமைப்பது போன்றவற்றிலிருந்து வழங்க பயன்படுத்தும் ஒரு நூலகமாகும். உருவாக்குபவர்கள் அதை " +"சொந்தமாக அல்லது வழியாக அழைக்கிறார்கள்: ref: `கயிறு`, அவர்களின் வெளியீட்டு மேலாண்மை " +"செயல்முறையின் ஒரு பகுதியாக, அவர்களின் தொகுப்பு விளக்கங்கள் PYPI இல் சரியாகக் " +"காண்பிக்கப்படும் என்பதை சரிபார்க்க." + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "Setuptools" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`டாக்ச் __ | `சிக்கல்கள் ` __ | `Github ` __ | `Pypi ` __" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" +"Setuptools (இதில் `` Ease_install`` ஐ உள்ளடக்கியது) என்பது பைத்தான் தொலைதூரங்களுக்கு " +"மேம்பாடுகளின் தொகுப்பாகும், இது பைத்தானை எளிதாக உருவாக்கவும் விநியோகிக்கவும் உங்களை " +"அனுமதிக்கிறது: கால: `விநியோகம் <விநியோக தொகுப்பு>`, குறிப்பாக பிற தொகுப்புகளைச் " +"சார்ந்திருக்கும்." + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "ட்ரோவ்-கிளாசிஃபையர்கள்" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" +"`சிக்கல்கள் ` __ | `Github " +"` __ | `Pypi ____ __ __" + +#: ../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 "" +"Pypi _ _, இது திட்ட பராமரிப்பாளர்கள் பயன்படுத்தும்: " +"ref: `அவர்களின் திட்டங்களை முறையாக விவரிக்கவும் <கோர்-மெட்டாடேட்டா-கிளாசிஃபையர்> " +"பயனர்கள் தங்கள் தேவைகளுக்கு பொருந்தக்கூடிய திட்டங்களை PYPI இல் சிறப்பாகக் காணலாம்." + +#: ../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 "" +"ட்ரோவ்-கிளாசிஃபியர்ச் தொகுப்பில் செல்லுபடியாகும் வகைப்படுத்திகள் மற்றும் நீக்கப்பட்ட " +"வகைப்படுத்திகளின் பட்டியல் உள்ளது (அவை அவற்றை மாற்றும் வகைப்படுத்திகளுடன் " +"இணைக்கப்பட்டுள்ளன). PYPI இல் பதிவேற்றுவதற்காக வடிவமைக்கப்பட்ட தொகுப்புகளில் " +"பயன்படுத்தப்படும் வகைப்படுத்திகளை சரிபார்க்க இந்த தொகுப்பைப் பயன்படுத்தவும். " +"வகைப்படுத்திகளின் இந்த பட்டியல் குறியீடாக வெளியிடப்படுவதால், நீங்கள் அதை நிறுவி இறக்குமதி " +"செய்யலாம், இது பைபி `_ இல் வெளியிடப்பட்ட` " +"பட்டியலைக் குறிப்பிடுவதை ஒப்பிடும்போது மிகவும் வசதியான பணிப்பாய்வுகளை உங்களுக்கு " +"வழங்குகிறது. `வெளியீடு டிராக்கர் ` _ திட்டத்திற்கு முன்மொழியப்பட்ட வகைப்படுத்திகள் பற்றிய விவாதங்கள் மற்றும் புதிய " +"வகைப்படுத்திகளுக்கான கோரிக்கைகள்." + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "கயிறு" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`டாக்ச் __ | `சிக்கல்கள் ` __ | `Github ` " +"__ | `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 "" +"பைதான் தொகுப்பு குறியீட்டு அல்லது பிற பைதான் தொகுப்பு குறியீடுகளுக்கு தொகுப்புகளை " +"பதிவேற்ற உருவாக்குபவர்கள் பயன்படுத்தும் முதன்மை கருவி உருவாக்குபவர்கள் கயிறு. இது ஒரு " +"கட்டளை-வரி நிரலாகும், இது நிரல் கோப்புகள் மற்றும் மெட்டாடேட்டாவை ஒரு வலை பநிஇ க்கு " +"அனுப்பும். உருவாக்குபவர்கள் இதைப் பயன்படுத்துகிறார்கள், ஏனெனில் இது அதிகாரப்பூர்வ PYPI " +"பதிவேற்ற கருவி, இது வேகமாகவும் பாதுகாப்பாகவும் இருக்கிறது, அது பராமரிக்கப்படுகிறது, " +"மேலும் இது நம்பத்தகுந்த வகையில் செயல்படுகிறது." + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "மெய்நிகர்இன்" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`டாக்ச் __ | `சிக்கல்கள் " +" __ | `Github ` __ | `Pypi ____ __" + +#: ../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 "" +"மெய்நிகர் ஈன்வ் என்பது தனிமைப்படுத்தப்பட்ட பைத்தானை உருவாக்குவதற்கான ஒரு கருவியாகும்: " +"கால: `மெய்நிகர் சூழல்கள் <மெய்நிகர் சூழல்>`, போன்றவை: குறிப்பு: `வெவி`. போலியானது: " +"ref: `vev`, மலைப்பாம்பின் பிற பதிப்புகளுக்கு மெய்நிகர் சூழல்களை உருவாக்க முடியும், இது " +"பாதை சூழல் மாறியைப் பயன்படுத்தி கண்டுபிடிக்கும். மெய்நிகர் சூழல்களை கட்டமைத்தல், " +"பராமரித்தல், நகல் செய்தல் மற்றும் சரிசெய்தல் ஆகியவற்றிற்கான வசதியான அம்சங்களையும் இது " +"வழங்குகிறது. மேலும் தகவலுக்கு, பகுதியைப் பார்க்கவும்: ref: `மெய்நிகர் சூழல்களை " +"உருவாக்குதல் மற்றும் பயன்படுத்துதல்`." + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "கிடங்கு" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" +"`டாக்ச் __ | `சிக்கல்கள் ` __ | `Github ____ __" + +#: ../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 "" +"தற்போதைய குறியீட்டு தளத்தை இயக்குகிறது: கால: `பைதான் தொகுப்பு அட்டவணை (PYPI)`. இது " +"`pypi.org ` _ இல் வழங்கப்படுகிறது. இதற்கான இயல்புநிலை ஆதாரம்: " +"குறிப்பு: `பிப்` பதிவிறக்கங்கள்." + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "சக்கரம்" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`டாக்ச் __ | `சிக்கல்கள் ` __ | `Github ` " +"__ | `Pypi ____" + +#: ../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 "" +"முதன்மையாக, சக்கர திட்டம் `` bdist_wheel``: ref: `setuptools` நீட்டிப்பை " +"உருவாக்குகிறது: கால:` சக்கர வழங்கல் `. கூடுதலாக, இது சக்கரங்களை " +"உருவாக்குவதற்கும் நிறுவுவதற்கும் அதன் சொந்த கட்டளை வரி பயன்பாட்டை வழங்குகிறது." + +#: ../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 "" +"`Utidwheel __, பைனான் சக்கர வடிவத்தில் " +"அவர்கள் உருவாக்கும் பைதான் தொகுப்புகளை சரிபார்த்து சரிசெய்ய உருவாக்குபவர்கள் பயன்படுத்தும் " +"ஒரு கருவி. சார்புகளைக் கண்டறியவும், இணக்கத்திற்கான மெட்டாடேட்டாவை சரிபார்க்கவும், " +"சக்கரத்தையும் மெட்டாடேட்டாவையும் சரிசெய்யவும், வெளிப்புற பகிரப்பட்ட நூலகங்களை ஒரு " +"தொகுப்பில் சேர்க்கவும் இது செயல்பாட்டை வழங்குகிறது." + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "பைபா அல்லாத திட்டங்கள்" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "உருவாக்க" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" +"`டாக்ச் ` __ | `சிக்கல்கள் ` __ | `Pypi __ | `Github ____" + +#: ../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 "" +"பில்ட்அவுட் என்பது பல பகுதிகளிலிருந்து பயன்பாடுகளை உருவாக்குவதற்கும், ஒன்றுகூடுவதற்கும், " +"வரிசைப்படுத்துவதற்கும் ஒரு பைதான் அடிப்படையிலான பில்ட் சிச்டம் ஆகும், அவற்றில் சில பைதான் " +"அல்லாதவை அல்ல. இது ஒரு கட்டமைப்பை உருவாக்கவும் அதே மென்பொருளை பின்னர் மீண்டும் " +"உருவாக்கவும் உங்களை அனுமதிக்கிறது." + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "காண்டா" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr ": டாக்: `டாக்ச் <காண்டா: குறியீட்டு>`" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" +"காண்டா என்பது எந்தவொரு மொழிக்கும் ஒரு தொகுப்பு, சார்பு மற்றும் சுற்றுச்சூழல் மேலாண்மை " +"அமைப்பு - பைதான், ஆர், ரூபி, சி/சி ++, ஃபோர்ட்ரான் மற்றும் பல. இது பைத்தானில் " +"எழுதப்பட்டுள்ளது மற்றும் பைதான் சயின்டிஃபிக் கம்ப்யூட்டிங் சமூகத்தில் பரவலாகப் " +"பயன்படுத்தப்படுகிறது, பைதான் அல்லாத தொகுக்கப்பட்ட நூலகங்கள் மற்றும் நீட்டிப்புகளுக்கு அதன் " +"உதவி காரணமாக. இது `அனகோண்டா ` __ " +"அனகோண்டா, இன்க் நிறுவனத்திடமிருந்து பைதான் வழங்கல் ஆகியவற்றின் அடிப்படையாகப் " +"பயன்படுத்தப்படுகிறது. இது முதலில் விஞ்ஞான சமூகத்தை இலக்காகக் கொண்டது, ஆனால் அதன் " +"சொந்தத்திலும் பயன்படுத்தப்படலாம் , or with the :doc:`miniconda `, " +"`miniforge `_ அல்லது` pixi " +" _ அமைப்புகள். இது சாளரங்கள், மேக் மற்றும் லினக்ச் அமைப்புகளுக்கு " +"கிடைக்கிறது." + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" +"காண்டா என்பது முற்றிலும் தனித்தனி கருவியாகும்: ref: `பிப்`, மெய்நிகர் மற்றும் சக்கரம், " +"ஆனால் அவற்றின் ஒருங்கிணைந்த பல அம்சங்களான தொகுப்பு மேலாண்மை, மெய்நிகர் சுற்றுச்சூழல் " +"மேலாண்மை மற்றும் பைனரி நீட்டிப்புகள் மற்றும் பிற பைனரி குறியீட்டைப் பயன்படுத்துதல் போன்ற பல " +"அம்சங்களை வழங்குகிறது." + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" +"காண்டா PYPI இலிருந்து தொகுப்புகளை நிறுவாது - இது கான்டாவிற்காக கட்டப்பட்ட தொகுப்புகளை " +"மட்டுமே நிர்வகிக்க முடியும், இது `anaconda.org ` " +"`anaconda.org __ __, சமூகத்திலிருந்து பலவிதமான " +"தொகுப்புகள் உள்ளன` கான்டா-ஃபார்ச் திட்டம் `__" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" +"குறிப்பு: குறிப்பு: `பிஐபி` இல் நிறுவப்படலாம், மேலும் நிர்வகிப்பதற்காக கான்டாவுடன் " +"பக்கவாட்டாக வேலை செய்ய முடியும்: கால:` வழங்கல் <விநியோக தொகுப்பு> `பைபி. `காண்டா " +"எலும்புக்கூடு `__: பைதான் தொகுப்புகளிலிருந்து காண்டா " +"தொகுப்புகளை தானாகவே உருவாக்க ஒரு கருவி கிடைக்கிறது பைபி." + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "தேவ்பி" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" +"`டாக்ச் ` __ | : GH: `சிக்கல்கள் ` | `Pypi ____" + +#: ../source/key_projects.rst:441 +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." +msgstr "" +"பைதானுடன் பேக்கேசிங், சோதனை மற்றும் வெளியீட்டு நடவடிக்கைகளை இயக்க ஒரு நிரப்பு கட்டளை " +"வரி கருவியுடன் டெவிபிஐ ஒரு சக்திவாய்ந்த பைபி-இணக்கமான சேவையகம் மற்றும் பைபி பதிலாள் " +"கேச் ஆகியவற்றைக் கொண்டுள்ளது. DEVPI உலாவக்கூடிய மற்றும் தேடக்கூடிய வலை இடைமுகத்தையும் " +"வழங்குகிறது. DEVPI பிரதிபலிக்கும் PYPI, பல: சொல்: `தொகுப்பு குறியீடுகள் <தொகுப்பு " +"குறியீட்டு>` பரம்பரை, இந்த குறியீடுகளுக்கு இடையில் ஒத்திசைவு, குறியீட்டு பிரதி மற்றும் " +"தோல்வி மற்றும் தொகுப்பு பதிவேற்றம்." + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "ஊமை-பைபி" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" +"`Github ` __ | `Pypi ____" + +#: ../source/key_projects.rst:457 +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 "" +"டம்ப்-பைபி ஒரு எளிய: சொல்: `தொகுப்பு குறியீட்டு <தொகுப்பு குறியீட்டு>` நிலையான கோப்பு " +"தள செனரேட்டர், பின்னர் தொகுப்பு குறியீடாக மாற நிலையான கோப்பு வெப்சர்வர் வழங்க வேண்டும். " +"இது ஆச், கோர்-மெட்டாடேட்டா மற்றும் யாங்க்-ச்டாட்டசுக்கு பணி செய்வதை ஆதரிக்கிறது." + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "என்கான்ச்" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" +": சி.எச்: `மூல <தோல்ட்/என்ச்கான்ச்>` | : சி.எச்: `சிக்கல்கள் <தோல்ட்/என்ச்கான்ச்/சிக்கல்கள்>` | " +"`Pypi ____" + +#: ../source/key_projects.rst:470 +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 "" +"என்ச்கான்ச் என்பது `ச்கான்ச்`_ ஐ அடிப்படையாகக் கொண்ட பைதான் பேக்கேசிங் கருவியாகும். இது " +"உருவாக்குகிறது: குறிப்பு: சி நீட்டிப்புகளுடன் விநியோகங்கள் உட்பட தொலைதூரங்கள் அல்லது " +"செட்டுப்டூல்களைப் பயன்படுத்தாமல் `பிப்`-இணக்கமான மூல வழங்கல் மற்றும் சக்கரங்கள். என்கான்ச் " +"வேறுபட்ட கட்டிடக்கலை மற்றும் தத்துவத்தைக் கொண்டுள்ளது: ref: `distutils`. பைதான் " +"பேக்கேசிங் அமைப்பில் உருவாக்க அம்சங்களைச் சேர்ப்பதற்குப் பதிலாக, என்கான்ச் ஒரு பொது நோக்கத்தை " +"உருவாக்கும் அமைப்பில் பைதான் பேக்கேசிங் சேர்க்கிறது. தானாகவே கட்டமைக்கக்கூடிய SDIST களை " +"உருவாக்க என்கான்ச் உங்களுக்கு உதவுகிறது: குறிப்பு: `பிப்`, மற்றும் என்ச்கான்களிலிருந்து " +"சுயாதீனமான சக்கரங்கள்." + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "பிளாச்க்-பைபி-ப்ராக்சி" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" +"`டாக்ச் __ | :gh:`GitHub ` | `Pypi ____ " +"__ __" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "பராமரிக்கப்படவில்லை, திட்ட காப்பகப்படுத்தப்பட்டது" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" +"பிளாச்க்-பைபி-ப்ராக்சி என்பது ஒரு: கால: `தொகுப்பு குறியீட்டு <தொகுப்பு அட்டவணை>` " +"பைபிக்கு ஒரு தற்காலிக சேமிப்பு ப்ராக்சியாக." + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "ஆச்டிச்ட்" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" +"`டாக்ச் __ | `Github ____ __" + +#: ../source/key_projects.rst:504 +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 "" +"ஆச்டிச்ட் என்பது ரூட் அல்லாத மென்பொருள் விநியோகங்களை உருவாக்குவதற்கான ஒரு நூலகமாகும். " +"ஆச்டிச்ட் \"டெபியன் தொழில்நுட்பம் வேலை செய்யாத நிகழ்வுகளுக்கான தேர்வுக்கான டெபியன்\" ஆக " +"முயற்சிக்கிறார். பைத்தோனிச்டாக்கள் ஆச்டிச்ட்டைப் பற்றி சிந்திக்க சிறந்த வழி மிகவும் " +"சக்திவாய்ந்த கலப்பினமாக இருக்கலாம்: குறிப்பு: `மெய்நிகர்என்வ்` மற்றும்: குறிப்பு:` " +"பில்ட்அவுட்`. இது விஞ்ஞான மென்பொருளை நிறுவுவதில் சிக்கலைத் தீர்ப்பதையும், தொகுப்பு " +"விநியோகத்தை நிலையற்ற, தற்காலிக சேமிப்பு மற்றும் கிளைத்தன்மையடிப்பதையும் நோக்கமாகக் " +"கொண்டுள்ளது. இது சில ஆராய்ச்சியாளர்களால் பயன்படுத்தப்படுகிறது, ஆனால் 2016 முதல் " +"பராமரிப்பு குறைவு." + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "Maturin" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" +"`டாக்ச் __ | `Github ` __" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" +"மாதுரின் என்பது துரு நீட்டிப்பு தொகுதிகளுக்கான ஒரு கட்டமைப்பை உருவாக்குகிறது, இது " +"துருவில் எழுதப்பட்டுள்ளது. இது சாளரங்கள், லினக்ச், மேகோச் மற்றும் ஃப்ரீ.பி.எச்.டி " +"ஆகியவற்றில் பைதான் 3.7+ க்கான சக்கரங்களை உருவாக்குகிறது, அவற்றை பைபியில் பதிவேற்றலாம் " +"மற்றும் அடிப்படை பைபி மற்றும் கிரால்பி ஆதரவைக் கொண்டுள்ளது." + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "மெசன்-பைதான்" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" +"`டாக்ச் ` __ | `Github " +" ____ __ __" + +#: ../source/key_projects.rst:534 +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 "" +"`` மீசன்-பைதான்`` என்பது மீசான்_ உருவாக்க முறையைப் பயன்படுத்தும் ஒரு கட்டமைப்பை " +"உருவாக்குகிறது. இது பைதான் தொகுப்பு ஆசிரியர்கள் தங்கள் தொகுப்புக்கான உருவாக்க அமைப்பாக " +"மீசான்_ ஐப் பயன்படுத்த உதவுகிறது. இது சி உள்ளிட்ட பல்வேறு வகையான மொழிகளை ஆதரிக்கிறது, " +"மேலும் மிகவும் சிக்கலான கட்டமைப்பின் தேவைகளை நிறைவு செய்ய முடியும்." + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "மல்டிபில்ட்" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "`Ginsub ` __" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" +"மல்டிபில்ட் என்பது பைத்தானை உருவாக்குவதற்கும் சோதிப்பதற்கும் தொஒ ச்கிரிப்ட்களின் " +"தொகுப்பாகும்: கால: `சக்கரங்கள் ` லினக்ச், மேகோச் மற்றும் (குறைவான நெகிழ்வான) " +"விண்டோசிற்கான. மேலும் காண்க: குறிப்பு: `cibuildwheel`." + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "nginx_pypi_cache" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr ":gh:`GitHub `" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" +"nginx_pypi_cache என்பது ஒரு: சொல்: `தொகுப்பு குறியீட்டு <தொகுப்பு குறியீட்டு>` " +"`nginx _ _ ஐப் பயன்படுத்தி ப்ராக்சியை கேச்சிங் செய்யும் " +"ப்ராக்சியை." + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "பி.டி.எம்" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`டாக்ச் __ | `Github __ | `Pypi ____" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" +"பி.டி.எம் ஒரு நவீன பைதான் தொகுப்பு மேலாளர். இது பயன்படுத்துகிறது: கால: " +"`pyproject.toml` திட்ட மெட்டாடேட்டாவை வரையறுக்கப்பட்டுள்ளபடி சேமிக்க: PEP:` 621`." + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`டாக்ச் __ | `Github __ | `Pypi ____" + +#: ../source/key_projects.rst:582 +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`. PEX கோப்புகள்: DOC: `zipapps ` அவை பைதான் பயன்பாடுகளை `` cp`` போன்ற எளிமையாக பயன்படுத்துகின்றன. ஒரு ஒற்றை " +"PEX கோப்பு பல இலக்கு தளங்களை ஆதரிக்கலாம் மற்றும் தரநிலையிலிருந்து உருவாக்கப்படலாம்: " +"ref: `PIP`-தீர்க்கக்கூடிய தேவைகள்,` `PEX3 பூட்டு ...` `அல்லது மற்றொரு PEX உடன் " +"உருவாக்கப்பட்ட ஒரு பூட்டுப் கோப்பை. PEX கோப்புகளை விருப்பமாக உட்பொதித்த கருவிகள் " +"இருக்கலாம், அவை PEX கோப்பை ஒரு நிலையான WENV ஆக மாற்றுவது, வரைபட சார்புகளை " +"வரைபடமாக்குகின்றன." + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "குழாய்-கருவிகள்" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`டாக்ச் __ | `Github __ | `Pypi ____ __" + +#: ../source/key_projects.rst:600 +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." +msgstr "" +"பிப்-டூல்ச் என்பது பைதான் சிச்டம் நிர்வாகிகளுக்கான கருவிகளின் தொகுப்பாகும், குறிப்பாக " +"தங்கள் கட்டடங்களை நிர்ணயிக்க விரும்பும் மேலாளர்களுக்கான வெளியீட்டு மேலாளர்கள், ஆனால் " +"அவர்களின் சார்புகளின் புதிய பதிப்புகளுடன் புதுப்பித்த நிலையில் இருங்கள். பயனர்கள் தங்கள் " +"சார்புகளின் குறிப்பிட்ட வெளியீட்டை ஆச் வழியாக குறிப்பிடலாம், அவற்றின் திட்டத்தின் பிற " +"பகுதிகளில் உள்ள தகவல்களிலிருந்து ஒழுங்காக வடிவமைக்கப்பட்ட தேவைகளின் பட்டியலை வசதியாக " +"உருவாக்கலாம், எல்லா சார்புகளையும் புதுப்பிக்கவும் (ஒரு அம்சம்: `பிப்` தற்போது வழங்கவில்லை) " +"மற்றும் அடுக்குகளை உருவாக்கவும் நிரலுக்குக் கீழ்ப்படியும் தடைகள்." + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "Pip2pi" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +": GH: `github ` | `Pypi " +"____ __" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" +"PIP2PI என்பது ஒரு: கால: `தொகுப்பு குறியீட்டு <தொகுப்பு குறியீட்டு>` குறிப்பிட்ட " +"தொகுப்புகள் கைமுறையாக ஒத்திசைக்கப்படும் சேவையகம்." + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "பிவீல்ச்" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" +"`வலைத்தளம் ` __ | : டாக்: `டாக்ச் ` | " +"`Github ____ __" + +#: ../source/key_projects.rst:629 +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 "" +"பிவீல்ச் என்பது ஒரு வலைத்தளம், மற்றும் மென்பொருள் அதை அடிப்படையாகக் கொண்டது, இது PYPI " +"இலிருந்து மூலக் குறியீடு விநியோக தொகுப்புகளைப் பெற்று அவற்றை பைனரி சக்கரங்களில் " +"தொகுக்கிறது, அவை ராச்பெர்ரி பை கணினிகளில் நிறுவ உகந்ததாக இருக்கும். ராச்பெர்ரி பை ஓஎச் " +"ப்ரீ-இன்ஃபிகர்ச் பிஐபிஐக்கு கூடுதல் குறியீடாக piwheels.org ஐப் பயன்படுத்த PIP." + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "பா" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`டாக்ச் __ | `Github ` __ | `Pypi ____ __" + +#: ../source/key_projects.rst:644 +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." +msgstr "" +"பா என்பது சார்பு நிறுவல் மற்றும் தனிமைப்படுத்தல் மற்றும் பைதான் தொகுப்புகளை " +"கட்டியெழுப்புதல் மற்றும் பேக்கேசிங் ஆகியவற்றைக் கையாள ஒரு கட்டளை-வரி கருவியாகும். இது " +"`` pyproject.toml`` ஐப் பயன்படுத்துகிறது, மேலும், தீர்க்கும் செயல்பாட்டைப் பொறுத்து: " +"ref: `PIP`, அதன் சொந்த சார்பு தீர்வை வழங்குகிறது. சார்புகளைப் பற்றி உள்நாட்டில் கேச்சிங் " +"மேனிலை தரவு மூலம் பயனர்களின் நிறுவல் மற்றும் சார்பு தீர்மானத்தை விரைவுபடுத்த " +"முயற்சிக்கிறது." + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "ப்ராக்ச்பி" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +":gh:`GitHub ` | `Pypi " +"____ __" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" +"ப்ராக்ச்பி ஒரு எளிய: சொல்: `தொகுப்பு குறியீட்டு <தொகுப்பு குறியீட்டு>` இது பைபி மற்றும் " +"பிற குறியீடுகளை கேச்சிங் மூலம் பிரதிநிதித்துவப்படுத்துகிறது." + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "கூழ்-பின்னான்" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" +"`டாக்ச் __ | :gh:`GitHub ` | `Pypi __ __ __" + +#: ../source/key_projects.rst:671 +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." +msgstr "" +"கூழ்-பைதான் பைதான்: சொல்: `தொகுப்பு குறியீட்டு <தொகுப்பு குறியீட்டு>` கூழ் _ _ க்கான சொருகி. புல்ப்-பைதான் உள்ளக அல்லது `AWS S3`_, தொகுப்பு " +"பதிவேற்றம் மற்றும் பல தொகுப்பு குறியீடுகளுக்கு ப்ராக்சிங் ஆகியவற்றின் ஆதரவுடன் கண்ணாடியை " +"ஆதரிக்கிறது." + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "பைபி முகில்" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" +"`டாக்ச் \\ ______________. : \\ ght: `github " +" `Pypi pypicloud/>` " +"____" + +#: ../source/key_projects.rst:687 +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." +msgstr "" +"PYPI முகில் ஒரு: கால: `தொகுப்பு குறியீட்டு <தொகுப்பு குறியீட்டு>` சேவையகம், `AWS " +"S3`_ அல்லது மற்றொரு முகில் ச்டோரேச் பணி அல்லது உள்ளக கோப்புகளால் ஆதரிக்கப்படுகிறது. " +"PYPI முகில் PYPI க்கான வழிமாற்ற/தற்காலிக சேமிப்பு ப்ராக்சை ஆதரிக்கிறது, அத்துடன் ஏற்பு " +"மற்றும் அங்கீகாரத்தை ஆதரிக்கிறது." + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "pypiprivate" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +": சி.எச்: `கிதுப் <எல்ப்சிஃப்ட்/பைபிப்ரிவேட்>` | `Pypi ____ __" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" +"Pypiprivate தொகுப்புகளின் உள்ளக (அல்லது `AWS S3`_- ஓச்ட்) கோப்பகத்தை A: கால:` " +"தொகுப்பு குறியீட்டு <தொகுப்பு குறியீட்டு> `." + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "பைபர்வர்" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" +"`Github ` __ | `Pypi ____ __" + +#: ../source/key_projects.rst:711 +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." +msgstr "" +"பைபிசெவர் என்பது ஒரு தனியார் பைதானாக செயல்படும் ஒரு குறைந்தபட்ச பயன்பாடாகும்: கால: " +"`தொகுப்பு குறியீட்டு <தொகுப்பு குறியீட்டு>` (உள்ளூர் கோப்பகத்திலிருந்து) " +"நிறுவனங்களுக்குள், ஒரு எளிய பநிஇ மற்றும் உலாவி இடைமுகத்தை செயல்படுத்துகிறது. நிலையான " +"பதிவேற்ற கருவிகளைப் பயன்படுத்தி நீங்கள் தனிப்பட்ட தொகுப்புகளை பதிவேற்றலாம், மேலும் பயனர்கள் " +"அவற்றை பதிவிறக்கம் செய்து நிறுவலாம்: Ref: `Pip`, அவற்றை பகிரங்கமாக வெளியிடாமல். " +"பைபிசெவரைப் பயன்படுத்தும் நிறுவனங்கள் பொதுவாக பைபிசெவரிலிருந்து மற்றும் பைபி ஆகிய " +"இரண்டிலிருந்தும் தொகுப்புகளைப் பதிவிறக்குகின்றன." + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "PysCaplold" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`டாக்ச் ` __ | `Github ` __ | `Pypi ____ __" + +#: ../source/key_projects.rst:728 +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 "" +"பைதான் தொகுப்புகளுக்கான திட்ட செனரேட்டர் பைதான் தொகுப்புகளுக்கான திட்ட செனரேட்டர் ஆகும், " +"இது பைபியில் பகிரத் தயாராக உள்ளது மற்றும் வழியாக நிறுவக்கூடியது: குறிப்பு: `பிப்`. " +"இது ஒரு விளைவாக்கம் சூழலை வழங்குவதற்காக நிறுவப்பட்ட கருவிகளுக்கான விவேகமான " +"இயல்புநிலை உள்ளமைவுகளின் தொகுப்பை நம்பியுள்ளது (போன்றவை: ref: `setuptools`, pytest_ " +"மற்றும் sphinx_), எனவே உருவாக்குபவர்கள் இப்போதே குறியீட்டு முறையைத் தொடங்கலாம். " +"பேக்கேசிங்கை எளிதாக்குவதற்கு பைச்கோகால்ட் ஏற்கனவே உள்ள திட்டங்களுடன் பயன்படுத்தப்படலாம்." + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "பைவார்" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +":gh:`GitHub ` | `Pypi " +"____" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" +"Pywharf என்பது ஒரு: சொல்: `தொகுப்பு அட்டவணை <தொகுப்பு குறியீட்டு>` சேவையகம், " +"உள்நாட்டில் அல்லது `github _ _." + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "சிக்கிட்-கட்டிடம்" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`டாக்ச் ` __ | `Github " +"` __ | `Pypi ` __" + +#: ../source/key_projects.rst:758 +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 "" +"ச்கிகிட்-பில்ட் ஒரு: ref: `செடிப்டூல்ச்` சிபிதானுக்கான ரேப்பர் சி/சி ++/ஃபோர்ட்ரான்/சைடான் " +"நீட்டிப்புகளை உருவாக்குகிறது, இது` cmake __ " +"(பைபி இல் கிடைக்கிறது) கூடுதல் கம்பைலர்கள், உருவாக்க அமைப்புகள், குறுக்கு தொகுப்பு " +"மற்றும் சார்புகளைக் கண்டறிதல் மற்றும் அவற்றுடன் தொடர்புடைய கட்டடத் தேவைகளுக்கு சிறந்த உதவி. " +"பெரிய திட்டங்களின் கட்டமைப்பை விரைவுபடுத்தவும் இணையாகவும், பயனர் `நிஞ்சா __ (பைபியில் கிடைக்கிறது) நிறுவலாம்." + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "ச்கிகிட்-பில்ட்-கோர்" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" +"`டாக்ச் ` __ | `Github " +" __ | `Pypi __ __ __" + +#: ../source/key_projects.rst:775 +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." +msgstr "" +"ச்கிகிட்-பில்ட்-கோர் என்பது CPython C/C ++/Fortran/Cython நீட்டிப்புகளுக்கான கட்டமைப்பை " +"உருவாக்கும் பின்தளத்தில் உள்ளது. இது பயனர்கள் `cmake __ (PYPI இல் கிடைக்கிறது) உடன் நீட்டிப்புகளை எழுத உதவுகிறது, கூடுதல் " +"கம்பைலர்களுக்கு சிறந்த ஆதரவை வழங்க, அமைப்புகள், குறுக்கு தொகுப்பு மற்றும் அவற்றுடன் " +"தொடர்புடைய கட்டமைப்பைக் கண்டறிதல் தேவைகள். கணினியில் கிடைக்காவிட்டால் Cmake/Nygaa " +"தானாகவே PYPI இலிருந்து பதிவிறக்கம் செய்யப்படும்." + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "சிவ்" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`டாக்ச் __ | `Github ` __ | `Pypi ____ " +"__" + +#: ../source/key_projects.rst:791 +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." +msgstr "" +"SHIV என்பது ஒரு கட்டளை வரி பயன்பாடாகும், இது கோடிட்டுக் காட்டப்பட்டுள்ளபடி முழுமையாக " +"சுயமாக இருக்கும் பைதான் சிபாப்சை உருவாக்குகிறது: PEP: `441`, ஆனால் அவற்றின் அனைத்து " +"சார்புகளும் சேர்க்கப்பட்டுள்ளன. அதன் முதன்மை குறிக்கோள் பைதான் பயன்பாடுகள் மற்றும் கட்டளை வரி " +"கருவிகளை விரைவாகவும் எளிதாகவும் விநியோகிப்பதாகும்." + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "எளிய இந்தெக்ச்" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +": GH: `github ` | `Pypi ____ __" + +#: ../source/key_projects.rst:804 +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." +msgstr "" +"சிம்பிள்இண்டெக்ச் ஒரு: சொல்: `தொகுப்பு குறியீட்டு <தொகுப்பு குறியீட்டு>` இது முகவரி களை " +"பல தொகுப்பு குறியீடுகளுக்கு (PYPI உட்பட) வழிநடத்துகிறது, உள்ளக (அல்லது கிளவுட்-ஓச்ட், " +"எடுத்துக்காட்டாக `AWS S3`_, தனிப்பயன் சொருகி) தொகுப்புகளின் கோப்பகங்கள் , மற்றும் " +"தனிப்பயன் செருகுநிரல்களை ஆதரிக்கிறது." + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" +": டாக்: `டாக்ச் <ச்பேக்: குறியீட்டு>` | `Github ` " +"__ | `Paper `__ | `ச்லைடுகள் ____ __ __" + +#: ../source/key_projects.rst:819 +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 "" +"பல பதிப்புகள், உள்ளமைவுகள், தளங்கள் மற்றும் கம்பைலர்களை ஆதரிக்க வடிவமைக்கப்பட்ட ஒரு " +"நெகிழ்வான தொகுப்பு மேலாளர். ச்பேக் ஓம்பிரூ போன்றது, ஆனால் தொகுப்புகள் பைத்தானில் " +"எழுதப்பட்டவை மற்றும் கம்பைலர்கள், நூலக பதிப்புகள், உருவாக்க விருப்பங்கள் போன்றவற்றை எளிதாக " +"மாற்ற அனுமதிக்க அளவுருவாக்கப்பட்டுள்ளன. தன்னிச்சையாக பல தொகுப்புகள் ஒரே அமைப்பில் " +"ஒன்றிணைந்திருக்க முடியும். கொத்துகள் மற்றும் சூப்பர் கம்ப்யூட்டர்களில் உயர் செயல்திறன் கொண்ட " +"விஞ்ஞான பயன்பாடுகளை விரைவாக உருவாக்குவதற்காக ச்பேக் வடிவமைக்கப்பட்டுள்ளது." + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" +"ச்பேக் பைபியில் இல்லை (இன்னும்), ஆனால் இதற்கு எந்த நிறுவலும் தேவையில்லை, மேலும் " +"கிட்அப்பிலிருந்து நகலி செய்த உடனேயே பயன்படுத்தலாம்." + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "zest.relases" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`டாக்ச் ` __ | `Github " +" __ | `Pypi ____ __" + +#: ../source/key_projects.rst:839 +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." +msgstr "" +"`` zest.Releaser`` என்பது ஒரு பைதான் தொகுப்பு வெளியீட்டு கருவியாகும்: மேலே ஒரு " +"சுருக்க அடுக்கை வழங்கும்: குறிப்பு: `ட்வைன்`. பைதான் உருவாக்குபவர்கள் தொகுப்பு பதிப்பு " +"எண்களை அதிகரிக்க, சேஞ்ச்லாக்சைப் புதுப்பித்தல், மூலக் கட்டுப்பாட்டில் வெளியீடுகளைக் குறித்தல் " +"மற்றும் புதிய தொகுப்புகளை PYPI இல் பதிவேற்றுதல் ஆகியவற்றை தானியக்கமாக்க `` " +"zest.releaser`` ஐப் பயன்படுத்துகின்றனர்." + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "நிலையான நூலக திட்டங்கள்" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "உறுதிப்படுத்தவும்" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" +"`டாக்ச் __ | `சிக்கல்கள் " +" ____ __" + +#: ../source/key_projects.rst:856 +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." +msgstr "" +"பூட்ச்ட்ராப்பிங்கிற்கு ஆதரவை வழங்கும் பைதான் நிலையான நூலகத்தில் ஒரு தொகுப்பு: குறிப்பு: " +"`பிப்` ஏற்கனவே இருக்கும் பைதான் நிறுவல் அல்லது மெய்நிகர் சூழலில். பெரும்பாலான " +"சந்தர்ப்பங்களில், இறுதி பயனர்கள் இந்த தொகுதியைப் பயன்படுத்த மாட்டார்கள், மாறாக இது பைதான் " +"விநியோகத்தின் போது பயன்படுத்தப்படும்." + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "http.server" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" +": டாக்: `டாக்ச் <பைதான்: நூலகம்/http.server>` | : GH: `சிக்கல்கள் <பைதான்/சிபிதான்/" +"சிக்கல்கள்>`" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" +"ஒரு வலைத்தளமாக ஒரு கோப்பகத்தை புரவலன் செய்யக்கூடிய ஒரு தொகுப்பு மற்றும் கட்டளை-வரி " +"இடைமுகம், எடுத்துக்காட்டாக ஒரு: கால: `தொகுப்பு குறியீட்டு <தொகுப்பு குறியீட்டு>` " +"(பார்க்க: குறிப்பு: `உங்கள் சொந்த எளிய களஞ்சியத்தை புரவலன் செய்தல்`)." + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "vev" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" +"`டாக்ச் __ | `சிக்கல்கள் ____ __" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" +"பைதான் நிலையான நூலகத்தில் ஒரு தொகுப்பு (பைதான் 3.3 உடன் தொடங்கி) உருவாக்க: கால: " +"`மெய்நிகர் சூழல்கள் <மெய்நிகர் சூழல்>`. மேலும் தகவலுக்கு, பகுதியைப் பார்க்கவும்: ref: " +"`மெய்நிகர் சூழல்களை உருவாக்குதல் மற்றும் பயன்படுத்துதல்`." + +#: ../source/news.rst:2 +msgid "News" +msgstr "செய்தி" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" +"இந்த ஆவணம் தற்போது புதுப்பிக்கப்படவில்லை. முன்னதாக, ஆவணம் பைதான் பேக்கேசிங்கில் ஏற்படும் " +"மாற்றங்களை எடுத்துக்காட்டுகிறது." + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "செப்டம்பர் 2019" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" +"அறிவிலிமையம் செயல்கள் வழியாக தொலைதூரங்களை வெளியிடுவது பற்றிய வழிகாட்டியைச் சேர்த்தது. " +"(: பி.ஆர்: `647`)" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "ஆகச்ட் 2019" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" +"பயன்படுத்த புதுப்பிக்கப்பட்டது: கோப்பு: `python3 -m` PIPX ஐ நிறுவும் போது. (: பி.ஆர்: " +"`631`)" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "சூலை 2019" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "அனைத்து PEP எண்களையும் குறிக்கப்பட்டுள்ளது: PEP: பங்கு. (: பி.ஆர்: `629`)" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" +"மேம்படுத்தப்பட்ட சூரரிமாச்சிலை பதிப்பு மற்றும் அகற்றப்பட்டது pypa.io இன்டர்ச்பிங்க்ச். (: " +"பி.ஆர்: `625`)" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "குறிப்பிடப்பட்டுள்ளது: கோப்பு: `find_namespace_packages`. (: பி.ஆர்: `622`)" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" +"நிலைத்தன்மைக்கு புதுப்பிக்கப்பட்ட அடைவு தளவமைப்பு எடுத்துக்காட்டுகள். (: பி.ஆர்: `611`)" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "கிட்அப்பிற்கு பேண்டர்ச்நாட்ச் இணைப்பு புதுப்பிக்கப்பட்டது. (: பி.ஆர்: `623`)" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "சூன் 2019" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "சில எழுத்துப்பிழைகள் சரி செய்யப்பட்டன. (: பி.ஆர்: `620`)" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "மே 2019" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" +"சேர்க்கப்பட்டது: கோப்பு: பேக்கேசிங் டுடோரியலுக்கான பயன்பாடு `பைதான்_ரொக்வைர்ச். (: பி.ஆர்: " +"`613`)" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "ஒரு manifest.in வழிகாட்டி பக்கத்தைச் சேர்த்தது. (: பி.ஆர்: `609`)" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "ஏப்ரல் 2019" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" +"இதற்கான குறிப்பைச் சேர்த்தது: கோப்பு: `சிவ்` முக்கிய திட்டங்கள் பிரிவில். (: பி.ஆர்: " +"`608`)" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "மெய்நிகர் ஈன்விக்கு முக்கியத்துவம் குறைக்கப்பட்டுள்ளது. (: பி.ஆர்: `606`)" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "மார்ச் 2019" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "பைதானுக்கு ஒற்றை-மூல வழிகாட்டி பதிப்பு விருப்பத்தை நகர்த்தியது. (: Pr: `605`)" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "பங்களிப்பதற்கான ஆர்டிடி விவரங்கள். (: பி.ஆர்: `600`)" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "பிப்ரவரி 2019" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" +"டுடோரியலுக்கும் உண்மையான பேக்கேசிங் செயல்முறைக்கும் இடையிலான வேறுபாடுகளை விரிவாகக் " +"கூறுங்கள். (: பி.ஆர்: `602`)" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "பைதான் சி.எல்.ஐ பயன்பாடுகளை நிறுவ வழிமுறைகளைச் சேர்த்தது. (: பி.ஆர்: `594`)" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "சனவரி 2019" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "சேர்க்கப்பட்டது: கோப்பு: பேக்கேசிங் டுடோரியலுக்கு `-நோ-டெப்ச்`. (: பி.ஆர்: `593`)" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "புதுப்பிக்கப்பட்ட சூரரிமாச்சிலை மற்றும் நோக்ச். (: பி.ஆர்: `591`)" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "பைதான் 3 இலிருந்து குறிப்பிடப்பட்ட கயிறு. (: பி.ஆர்: `581`)" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "டிசம்பர் 2018" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "அலுவலகத்தில் புரோகிராமர்கள் இல்லை!" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "நவம்பர் 2018" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" +"அகற்றப்பட்ட இறங்கும் பக்க பைபி இடம்பெயர்வு வழிகாட்டிக்கு இணைப்பு. (: பி.ஆர்: `575`)" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "பம்ப் 2 பவர்சனுக்கு மாற்றப்பட்டது. (: பி.ஆர்: `572`)" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "ஒற்றை-சோர்சிங் தொகுப்பு பதிப்பு எடுத்துக்காட்டு சேர்க்கப்பட்டது. (: பி.ஆர்: `573`)" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "ஆவணங்களை உருவாக்குவதற்கான வழிகாட்டியைச் சேர்த்தது. (: பி.ஆர்: `568`)" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "அக்டோபர் 2018" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "புதுப்பிக்கப்பட்ட NOX தொகுப்பு பெயர். (: பி.ஆர்: `566`)" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "வழிகாட்டிகளில் சூரரிமாச்சிலை நீட்டிப்புகள் குறிப்பிடப்பட்டுள்ளன. (: பி.ஆர்: `562`)" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "செப்டம்பர் 2018" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "RST மார்க்அப்பைச் சரிபார்க்க ஒரு பகுதியைச் சேர்த்தது. (: பி.ஆர்: `554`)" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "புதுப்பிக்கப்பட்ட பயனர் பக்கத்தை நிறுவுகிறது. (: பி.ஆர்: `558`)" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "Google Bigquery முகவரி கள் புதுப்பிக்கப்பட்டது. (: பி.ஆர்: `556`)" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "தார் கட்டளையை வேலை கட்டளையுடன் மாற்றியது. (: பி.ஆர்: `552`)" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" +"PIP இல் இரட்டை மேற்கோள்களாக மாற்றப்பட்டது சில திட்டங்கள் == 1.4. (: பி.ஆர்: `550`)" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "ஆகச்ட் 2018" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" +"கடவுச்சொற்களை ClearText இல் சேமிப்பதற்கான பரிந்துரையை நீக்கியது. (: பி.ஆர்: `546`)" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" +"கண்ணோட்டத்தை மற்றவர்களுடன் சேர்ந்து ஒரு பணி அடிப்படையிலான முன்னணிக்கு நகர்த்தியது. (: " +"பி.ஆர்: `540`)" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "மெய்நிகர்இன்வி ஆதரிக்கும் பைதான் பதிப்பு புதுப்பிக்கப்பட்டது. (: பி.ஆர்: `538`)" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" +"புதிய கண்ணோட்டம் பக்கத்தின் அவுட்லைன்/தோராயமான வரைவு சேர்க்கப்பட்டது. (: பி.ஆர்: `519`)" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "சூலை 2018" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "மேம்படுத்தப்பட்ட பைனரி நீட்டிப்பு ஆவணங்கள். (: பி.ஆர்: `531`)" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "முக்கிய திட்டங்களுக்கு சிக்கிட்-கட்டிடம் சேர்க்கப்பட்டது. (: பி.ஆர்: `530`)" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "சூன் 2018" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "Pypa.io க்கான இன்டர்பிராப் PEP இன் நிலையான வகைகள். (: பி.ஆர்: `527`)" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "புதுப்பிக்கப்பட்ட மார்க் பேரூர் விளக்கங்கள் விளக்கம். (: பி.ஆர்: `522`)" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "மே 2018" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" +"வழங்கும்-தூர மற்றும் வழக்கற்றுப் போகும்-டிச்ட்டுடன் குறிப்பிடத்தக்க சிக்கல்கள். (: பி.ஆர்: " +"`513`)" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" +"பைதான் பதிப்பு பைபென்வியுடன் கலப்பதைப் பற்றிய காலாவதியான எச்சரிக்கையை அகற்றியது. (: " +"பி.ஆர்: `501`)" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "எளிமைப்படுத்தப்பட்ட பேக்கேசிங் பயிற்சி. (: பி.ஆர்: `498`)" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "தெளிவுக்கான சாளரங்கள் பயனர்களின் வழிமுறைகளைப் புதுப்பித்தது. (: பி.ஆர்: `493`)" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "உரிமத்திற்கு உரிமப் பிரிவு விளக்கத்தை புதுப்பித்தது. (: பி.ஆர்: `492`)" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "பங்களிப்பு பிரிவில் விவரக்குறிப்பு-பாணி ஆவணத்தை சேர்த்தது. (: பி.ஆர்: `489`)" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "பங்களிப்பு வழிகாட்டிக்கு ஆவணப்படுத்தல் வகைகள் சேர்க்கப்பட்டன. (: பி.ஆர்: `485`)" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "ஏப்ரல் 2018" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "README வழிகாட்டி சேர்க்கப்பட்டது. (: பி.ஆர்: `461`)" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "புதுப்பிக்கப்பட்ட வழிமுறைகள் மற்றும் PYPI துவக்கத்திற்கான நிலை. (: பி.ஆர்: `475`)" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "கிடங்கிற்கான வழிமுறைகள் சேர்க்கப்பட்டன. (: பி.ஆர்: `471`)" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" +"வெளியீட்டு டுடோரியலில் இருந்து சிபிசி குறிப்புகள் அகற்றப்பட்டன. (: பி.ஆர்: `466`)" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "'எந்த பைதான் 3.4–3.6?' (: பி.ஆர்: `468`)" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "பைதான் பதிப்புகளை கட்டியெழுப்ப ஒரு வழிகாட்டியைச் சேர்த்தது. (: பி.ஆர்: `459`)" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "இயல்புநிலை விளக்கம்-உள்ளடக்க வகை மாறுபாடு சி.எஃப்.எம். (: பி.ஆர்: `462`)" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "மார்ச் 2018" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "புதுப்பிக்கப்பட்டது \"அறிவியல் தொகுப்புகளை நிறுவுதல்\". (: பி.ஆர்: `455`)" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" +"சேர்க்கப்பட்டது: கோப்பு: பெப் 556 ஐப் பின்பற்ற `long_description_content_type`. (: " +"Pr:` 457`)" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" +"Pypi.org இல் ஒரு நீண்ட விளக்க வகைப்படுத்தியை தெளிவுபடுத்தியது. (: பி.ஆர்: `456`)" + +#: ../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" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" +"டெபியன் நிறுவல் வழிமுறைகளில் பைதான் 3-வென்வ் மற்றும் பைதான் 3-பிஐபி சேர்க்கப்பட்டது. (: " +"பி.ஆர்: `445`)" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "புதுப்பிக்கப்பட்ட PYPI இடம்பெயர்வு செய்தி. (: பி.ஆர்: `439`)" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" +"பைபன்வி உடன் பல பதிப்புகளை நிர்வகிப்பது பற்றிய எச்சரிக்கையைச் சேர்த்தது. (: பி.ஆர்: " +"`430`)" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" +"கோர் மெட்டாடேட்டாவுக்கு பல மின்னஞ்சல்களின் எடுத்துக்காட்டு சேர்க்கப்பட்டது. (: பி.ஆர்: `429`)" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" +"Test.pypi.org/legacy இல் \"மரபு\" பற்றிய விளக்கம் சேர்க்கப்பட்டது. (: பி.ஆர்: `426`)" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "சனவரி 2018" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "பைபியின் வகைப்படுத்திகளின் பட்டியலுக்கு இணைப்பைச் சேர்த்தது. (: பி.ஆர்: `425`)" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "புதுப்பிக்கப்பட்ட README.RST விளக்கம். (: பி.ஆர்: `419`)" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "டிசம்பர் 2017" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" +"மாற்றப்பட்டது: கோப்பு: `~` உடன்: கோப்பு: `$ வீடு` வழிகாட்டிகள் மற்றும் பயிற்சிகளில். (: " +"பி.ஆர்: `418`)" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" +"சுற்றுச்சூழல் குறிப்பான்களுடன் எந்த புலங்களைப் பயன்படுத்தலாம் என்பதைக் குறிப்பிட்டார். (: " +"பி.ஆர்: `416`)" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "புதுப்பிக்கப்பட்ட பைதான் பிரிவு தேவை. (: பி.ஆர்: `414`)" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "செய்தி பக்கம் சேர்க்கப்பட்டது. (: பி.ஆர்: `404`)" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "நவம்பர் 2017" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" +"பைபென்வியை அடிப்படையாகக் கொண்ட புதிய சார்பு மேலாண்மை டுடோரியலை அறிமுகப்படுத்தியது. " +"(: பி.ஆர்: `402`)" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" +"பைப்பின் தற்போதைய மூலோபாயத்தை பிரதிபலிக்க * ஒற்றை மூல தொகுப்பு பதிப்பு * டுடோரியலைப் " +"புதுப்பித்தது. (: பி.ஆர்: `400`)" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" +"`` Py_modules`` உரையாடல் பற்றிய ஆவணங்களை `` அமைவு`` சேர்த்தது. (: பி.ஆர்: `398`)" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" +": கோப்பு: `manifest.in` பிரிவுக்கான சொற்களை எளிமைப்படுத்தியது. (: பி.ஆர்: `395`)" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "அக்டோபர் 2017" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" +"இதற்கு ஒரு விவரக்குறிப்பைச் சேர்த்தது: கோப்பு: `entry_points.txt` கோப்பு. (: பி.ஆர்: " +"`398`)" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" +"`` பிப்`` மற்றும் `` மெய்நிகர்என்.வி`` ஐப் பயன்படுத்தி தொகுப்புகளை நிர்வகிப்பதற்கான புதிய " +"வழிகாட்டியை உருவாக்கியது. (: பி.ஆர்: `385`)" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "விவரக்குறிப்புகள் பக்கத்தை பல பக்கங்களாக பிரிக்கவும். (: பி.ஆர்: `386`)" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "செப்டம்பர் 2017" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" +"சரிபார்க்க `` ReadMe_Renderer`` ஐப் பயன்படுத்தி ஊக்குவிக்கப்பட்டது: கோப்பு: " +"`ReadMe.rst`. (: பி.ஆர்: `379`)" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" +"`` --User-base`` விருப்பத்தைப் பயன்படுத்தி பரிந்துரைக்கப்படுகிறது. (: பி.ஆர்: `374`)" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "ஆகச்ட் 2017" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" +"`` பைபென்வ்`` ஐப் பயன்படுத்தி தொகுப்புகளை நிறுவுவதில் புதிய, சோதனை டுடோரியலைச் " +"சேர்த்தது. (: பி.ஆர்: `369`)" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" +"`` TestPypi`` ஐ எவ்வாறு பயன்படுத்துவது என்பதற்கான புதிய வழிகாட்டியைச் சேர்த்தது. (: " +"பி.ஆர்: `366`)" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "சேர்க்கப்பட்டது: கோப்பு: `pypi.org` ஒரு காலமாக. (: பி.ஆர்: `365`)" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "சூலை 2017" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "முக்கிய திட்ட பட்டியலில் `` ஃபிளிட்`` சேர்க்கப்பட்டது. (: பி.ஆர்: `358`)" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "முக்கிய திட்டங்களின் பட்டியலில் `` என்கான்ச்`` சேர்க்கப்பட்டது. (: பி.ஆர்: `357`)" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" +"வழிகாட்டியை உள்நாட்டில் எவ்வாறு உருவாக்குவது என்பதற்கான வழிமுறைகளுடன் இந்த வழிகாட்டியின் " +"`` ரீட்மே`` புதுப்பிக்கப்பட்டது. (: பி.ஆர்: `356`)" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" +"புதிய `` டெச்ட்பை`` முகவரி ஐ மேலும் புலம்பும், pypi.org பற்றிய முகப்புப்பக்கத்தில் " +"குறிப்பைச் சேர்த்தது. (: பி.ஆர்: `354`)" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" +"வெளிப்படையான பதிவு பநிஇ ஐ அகற்றுவது குறித்த குறிப்பைச் சேர்த்தது. (: பி.ஆர்: `347`)" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "சூன் 2017" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" +"பதிவேற்றங்களை இடம்பெயர ஒரு ஆவணத்தைச் சேர்த்தது: கோப்பு: `pypi.org`. (: பி.ஆர்: `339`)" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "`` பைதான்_ரொக்வைர்ச்`` க்கான ஆவணங்களைச் சேர்த்தது. (: பி.ஆர்: `338`)" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" +"* கருவி பரிந்துரைகள் * டுடோரியலில் PYPI இடம்பெயர்வு பற்றிய குறிப்பைச் சேர்த்தது. (: " +"பி.ஆர்: `335`)" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" +"ஒரு குறிப்பைச் சேர்த்தது: கோப்பு: `manifest.in` சக்கரங்களை பாதிக்காது. (: பி.ஆர்: " +"`332`)" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "விநியோக வழிகாட்டியில் உரிமப் பிரிவைச் சேர்த்தது. (: பி.ஆர்: `331`)" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "`` பெயர்`` வாதத்தில் உள்ள பகுதியை விரிவுபடுத்தியது. (: பி.ஆர்: `329`)" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "இறங்கும் பக்கத்தை சரிசெய்தது. ." + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "சூரரிமாச்சிலை 1.6.2 க்கு புதுப்பிக்கப்பட்டது. (: பி.ஆர்: `323`)" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "PYPA கருப்பொருளுக்கு மாறியது. (: பி.ஆர்: `305`)" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "புதிய கட்டமைப்பில் ஆவணங்களை மீண்டும் ஒழுங்கமைத்தது. (: பி.ஆர்: `318`)" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "மே 2017" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "`` விளக்கம்-உள்ளடக்க வகை`` துறைக்கான ஆவணங்கள் சேர்க்கப்பட்டன. (: பி.ஆர்: `258`)" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "கூடுதல் பங்களிப்பாளர் மற்றும் பாணி வழிகாட்டி. (: பி.ஆர்: `307`)" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" +"ஆவணப்படுத்தப்பட்ட `` பிப்`` மற்றும் `` ஈசி_இன்ச்டால்`` இன் வேறுபாடுகள். (: பி.ஆர்: `233`)" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "ஏப்ரல் 2017" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "புல் கோரிக்கைகளை சோதிக்க டிராவிச் உள்ளமைவு சேர்க்கப்பட்டது. (: பி.ஆர்: `300`)" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" +"சக்கரங்களை உருவாக்குவதற்கான `` சக்கரம்`` தொகுப்பின் தேவையைக் குறிப்பிட்டுள்ளார் (: Pr: " +"`299`)" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" +"* விநியோகிக்கும் தொகுப்புகளில் * டுடோரியலில் `` ட்வைன் பதிவு` `குறிப்பை அகற்றியது. (: " +"பி.ஆர்: `271`)" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "சொருகி கண்டுபிடிப்பில் ஒரு தலைப்பைச் சேர்த்தது. (: pr: `294`,: pr:` 296`)" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "பெயர்வெளி தொகுப்புகளில் ஒரு தலைப்பைச் சேர்த்தது. (: பி.ஆர்: `290`)" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" +"``/Usr/local`` இல் `` பிப்`` ஐ எவ்வாறு நிறுவுவது என்பதை முக்கியமாக விளக்கும் ஆவணங்கள் " +"சேர்க்கப்பட்டன. (: பி.ஆர்: `230`)" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" +"புதுப்பிக்கப்பட்ட மேம்பாட்டு முறை ஆவணங்கள் உள்ளக தொகுப்புகளின் வரிசை விசயங்களைக் " +"குறிப்பிட. (: பி.ஆர்: `208`)" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" +"புரவலன் செய்யப்பட்ட திட்டங்களுக்கான `` .org`` -> `` .io`` இடம்பெயர்வு (: Pr: `239`) " +"க்கான READTHEDOCS இணைப்பை மாற்றவும்" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" +"இடமாற்றம் செய்யப்பட்ட ஆர்டர்: கோப்பு: பதிவேற்ற கட்டளைக்கான `setup.py` வாதங்கள் " +"குறிப்பிடத்தக்கவை. (: பி.ஆர்: `260`)" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" +"உதவி பயன்பாட்டைப் பயன்படுத்தி ஆதரிக்கப்படாத மூலங்களிலிருந்து எவ்வாறு நிறுவுவது என்பதை " +"விளக்கினார். (: பி.ஆர்: `289`)" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "மார்ச் 2017" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "இயங்குதள சக்கரங்களில் *`` மேனிலினக்ச் 1`` உள்ளடக்கியது. (: பி.ஆர்: `283`)" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "பிப்ரவரி 2017" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "சேர்க்கப்பட்டது: PEP: `518`. (: பி.ஆர்: `281`)" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "பைதான் பேக்கேசிங்கின் கண்ணோட்டம்" + +#: ../source/overview.rst:7 +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." +msgstr "" +"ஒரு பொது நோக்கம் கொண்ட நிரலாக்க மொழியாக, பைதான் பல வழிகளில் பயன்படுத்த " +"வடிவமைக்கப்பட்டுள்ளது. வலைத்தளங்கள் அல்லது தொழில்துறை ரோபோக்கள் அல்லது உங்கள் நண்பர்கள் " +"விளையாடுவதற்கான ஒரு விளையாட்டை நீங்கள் உருவாக்கலாம், மேலும் பலவற்றை ஒரே முக்கிய " +"தொழில்நுட்பத்தைப் பயன்படுத்தலாம்." + +#: ../source/overview.rst:12 +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." +msgstr "" +"பைதானின் நெகிழ்வுத்தன்மை என்னவென்றால், ஒவ்வொரு பைதான் திட்டத்தின் முதல் படி திட்டத்தின் " +"பார்வையாளர்களைப் பற்றியும், திட்டம் இயங்கும் அதனுடன் தொடர்புடைய சூழலைப் பற்றியும் சிந்திக்க " +"வேண்டும். குறியீட்டை எழுதுவதற்கு முன்பு பேக்கேசிங் பற்றி சிந்திப்பது விசித்திரமாகத் " +"தோன்றலாம், ஆனால் இந்த செயல்முறை எதிர்கால தலைவலியைத் தவிர்ப்பதற்கு அதிசயங்களை செய்கிறது." + +#: ../source/overview.rst:18 +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." +msgstr "" +"இந்த கண்ணோட்டம் பைத்தானின் ஏராளமான பேக்கேசிங் விருப்பங்களைப் பற்றிய பகுத்தறிவுக்காக ஒரு " +"பொது நோக்க முடிவான மரத்தை வழங்குகிறது. உங்கள் அடுத்த திட்டத்திற்கான சிறந்த " +"தொழில்நுட்பத்தைத் தேர்வுசெய்ய படிக்கவும்." + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "வரிசைப்படுத்தல் பற்றி சிந்திப்பது" + +#: ../source/overview.rst:25 +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:" +msgstr "" +"தொகுப்புகள் நிறுவப்பட வேண்டும் (அல்லது *பயன்படுத்தப்பட்டவை *), எனவே நீங்கள் எதையும் தொகுக்க " +"முன், கீழே உள்ள வரிசைப்படுத்தல் கேள்விகளுக்கு சில பதில்களை நீங்கள் பெற விரும்புவீர்கள்:" + +#: ../source/overview.rst:29 +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?" +msgstr "" +"உங்கள் மென்பொருளின் பயனர்கள் யார்? மென்பொருள் மேம்பாடு, டேட்டாசென்டரில் செயல்படும் நபர்கள் " +"அல்லது குறைவான மென்பொருள் ஆர்வமுள்ள குழு ஆகியவற்றைச் செய்யும் பிற டெவலப்பர்களால் உங்கள் " +"மென்பொருள் நிறுவப்படுமா?" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" +"உங்கள் மென்பொருள் தனித்தனியாக நிறுவப்பட்டுள்ளதா, அல்லது பெரிய வரிசைப்படுத்தல் தொகுதிகளில் " +"உள்ளதா?" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "பேக்கேசிங் பைதான் நூலகங்கள் மற்றும் கருவிகள்" + +#: ../source/overview.rst:45 +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`." +msgstr "" +"பைபி, `` setup.py``, மற்றும் `` வீல்`` கோப்புகளைப் பற்றி நீங்கள் கேள்விப்பட்டிருக்கலாம். " +"டெவலப்பர்களுக்கு பைதான் குறியீட்டை விநியோகிக்க பைதானின் சுற்றுச்சூழல் அமைப்பு வழங்கும் சில " +"கருவிகள் இவை: நீங்கள் இதைப் படிக்கலாம்: DOC: `வழிகாட்டிகள்/விநியோகித்தல்-தொகுப்புகள்-" +"பயன்படுத்தும்-செட்டப்டூல்ச்`." + +#: ../source/overview.rst:50 +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`." +msgstr "" +"பேக்கேசிங் செய்வதற்கான பின்வரும் அணுகுமுறைகள் ஒரு மேம்பாட்டு அமைப்பில் தொழில்நுட்ப " +"பார்வையாளர்களால் பயன்படுத்தப்படும் நூலகங்கள் மற்றும் கருவிகளுக்கானவை. தொழில்நுட்பமற்ற " +"பார்வையாளர்கள் மற்றும்/அல்லது ஒரு தயாரிப்பு அமைப்பிற்காக பைத்தானை தொகுக்க வழிகளை நீங்கள் " +"தேடுகிறீர்கள் என்றால், இதற்கு முன்னால் தவிர்க்கவும்: குறிப்பு: `பேக்கேசிங்-பயன்பாடுகள்`." + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "பைதான் தொகுதிகள்" + +#: ../source/overview.rst:58 +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." +msgstr "" +"ஒரு பைதான் கோப்பு, நிலையான நூலகத்தை மட்டுமே நம்பியிருந்தால், மறுபகிர்வு செய்யப்பட்டு " +"மீண்டும் பயன்படுத்தப்படலாம். பைத்தானின் சரியான பதிப்பிற்காக இது எழுதப்பட்டிருப்பதை நீங்கள் " +"உறுதிப்படுத்த வேண்டும், மேலும் நிலையான நூலகத்தை மட்டுமே நம்பியுள்ளது." + +#: ../source/overview.rst:63 +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 " +"`." +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 "" +"இருப்பினும், பல கோப்புகளைக் கொண்ட, கூடுதல் நூலகங்கள் தேவைப்படும் அல்லது பைத்தானின் " +"குறிப்பிட்ட பதிப்பு தேவைப்படும் திட்டங்களுக்கு இந்த முறை அளவிடாது, எனவே கீழே உள்ள " +"விருப்பங்கள்." + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" +"உங்கள் குறியீடு பல பைதான் கோப்புகளைக் கொண்டிருந்தால், அது வழக்கமாக ஒரு அடைவு கட்டமைப்பாக " +"ஒழுங்கமைக்கப்படுகிறது. பைதான் கோப்புகளைக் கொண்ட எந்த கோப்பகமும் ஒரு: கால: `இறக்குமதி " +"தொகுப்பு` ஐக் கொண்டிருக்கலாம்." + +#: ../source/overview.rst:81 +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." +msgstr "" +"தொகுப்புகள் பல கோப்புகளைக் கொண்டிருப்பதால், அவை விநியோகிக்க கடினமாக உள்ளன. பெரும்பாலான " +"நெறிமுறைகள் ஒரு நேரத்தில் ஒரு கோப்பை மட்டுமே மாற்றுவதை ஆதரிக்கின்றன (கடைசியாக நீங்கள் " +"ஒரு இணைப்பைக் சொடுக்கு செய்து பல கோப்புகளை பதிவிறக்கம் செய்தது எப்போது?). முழுமையற்ற " +"இடமாற்றங்களைப் பெறுவது எளிதானது, மேலும் இலக்கை நோக்கி குறியீடு ஒருமைப்பாட்டை பொறுப்பு " +"செய்வது கடினம்." + +#: ../source/overview.rst:87 +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." +msgstr "" +"உங்கள் குறியீட்டில் தூய பைதான் குறியீட்டைத் தவிர வேறு எதுவும் இல்லை, மேலும் உங்கள் " +"வரிசைப்படுத்தல் சூழல் உங்கள் பைத்தானின் பதிப்பை ஆதரிக்கிறது என்பது உங்களுக்குத் தெரியும், " +"பின்னர் நீங்கள் ஒரு *மூலத்தை உருவாக்க பைத்தானின் சொந்த பேக்கேசிங் கருவிகளைப் பயன்படுத்தலாம் " +"*: கால: `விநியோக தொகுப்பு`, அல்லது *SDIST * சுருக்கமாக." + +#: ../source/overview.rst:92 +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." +msgstr "" +"பைதானின் * Sdists * ஒன்று அல்லது அதற்கு மேற்பட்ட தொகுப்புகள் அல்லது தொகுதிகள் கொண்ட " +"சுருக்கப்பட்ட காப்பகங்கள் (`.tar.gz`` கோப்புகள்) ஆகும். உங்கள் குறியீடு தூய-பைதான் என்றால், " +"நீங்கள் மற்ற பைதான் தொகுப்புகளை மட்டுமே சார்ந்து இருந்தால், நீங்கள்: ref: `மூல-விநியோக-" +"வடிவ விவரக்குறிப்பு` மேலும் அறியச் செல்லலாம்." + +#: ../source/overview.rst:97 +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." +msgstr "" +"நீங்கள் ஏதேனும் பைதான் அல்லாத குறியீடு அல்லது பைதான் அல்லாத தொகுப்புகளை நம்பினால் " +"(`libxml2 ` _ _ lxml `_, அல்லது பிளாச் நூலகங்கள் `numpy ` _), அடுத்த பகுதியில் விவரிக்கப்பட்டுள்ள வடிவமைப்பை நீங்கள் " +"பயன்படுத்த வேண்டும், இது தூய-பைத்தான் நூலகங்களுக்கு பல நன்மைகளையும் கொண்டுள்ளது." + +#: ../source/overview.rst:104 +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!" +msgstr "" +"பைதான் மற்றும் பைபி ஆகியவை ஒரே தொகுப்பின் வெவ்வேறு செயலாக்கங்களை வழங்கும் பல " +"விநியோகங்களை ஆதரிக்கின்றன. உதாரணமாக, செயல்படாத-பட்-செமினல் `பைல் வழங்கல் ` _ PIL தொகுப்பை வழங்குகிறது, எனவே `தலையணை `_, பில் தீவிரமாக பராமரிக்கப்படும் முட்கரண்டி!" + +#: ../source/overview.rst:111 +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``." +msgstr "" +"இந்த பைதான் பேக்கேசிங் சூப்பர் பவர் உங்கள் திட்டத்தின் `` install_requires`` அல்லது `` " +"தேவைகள். Txt`` ஐ மாற்றுவதன் மூலம், PIL க்கு ஒரு டிராப்-இன் மாற்றாக தலையணைக்கு " +"சாத்தியமாக்குகிறது." + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "பைதான் பைனரி விநியோகங்கள்" + +#: ../source/overview.rst:118 +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." +msgstr "" +"சி, சி ++, ஃபோர்டிரான், ரச்ட் மற்றும் பிற மொழிகளில் எழுதப்பட்ட குறிப்பாக நூலகங்களில், " +"மென்பொருள் சுற்றுச்சூழல் அமைப்புடன் ஒருங்கிணைக்கும் திறனில் இருந்து பைத்தானின் நடைமுறை " +"ஆற்றல் அதிகம்." + +#: ../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." +msgstr "" +"இந்த தொகுக்கப்பட்ட மொழிகளில் எழுதப்பட்ட இந்த கூறுகளை உருவாக்க எல்லா டெவலப்பர்களுக்கும் " +"சரியான கருவிகள் அல்லது அனுபவங்கள் இல்லை, எனவே பைதான் உருவாக்கியது: கால: `வீல்`, " +"தொகுக்கப்பட்ட கலைப்பொருட்களுடன் நூலகங்களை அனுப்ப வடிவமைக்கப்பட்ட ஒரு தொகுப்பு வடிவமாகும். " +"உண்மையில், பைத்தானின் தொகுப்பு நிறுவி, `` பிப்``, எப்போதும் சக்கரங்களை விரும்புகிறது, " +"ஏனெனில் நிறுவல் எப்போதும் வேகமாக இருக்கும், எனவே தூய-பைதான் தொகுப்புகள் கூட " +"சக்கரங்களுடன் சிறப்பாக செயல்படுகின்றன." + +#: ../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 "" +"பொருந்தக்கூடிய மூல விநியோகங்களுடன் வரும்போது பைனரி விநியோகங்கள் சிறந்தவை. ஒவ்வொரு " +"இயக்க முறைமைக்கும் உங்கள் குறியீட்டின் சக்கரங்களை நீங்கள் பதிவேற்றாவிட்டாலும், SDIST ஐப் " +"பதிவேற்றுவதன் மூலம், பிற தளங்களின் பயனர்களை தங்களைத் தாங்களே உருவாக்கிக் கொள்ள " +"உதவுகிறீர்கள். SDIST மற்றும் சக்கர காப்பகங்கள் இரண்டையும் ஒன்றாக வெளியிடுவதற்கான " +"இயல்புநிலை, * இல்லையென்றால் * நீங்கள் ஒரு குறிப்பிட்ட பயன்பாட்டு வழக்குக்கு கலைப்பொருட்களை " +"உருவாக்குகிறீர்கள், அங்கு பெறுநருக்கு ஒன்று அல்லது மற்றொன்று மட்டுமே தேவை என்பதை நீங்கள் " +"அறிவீர்கள்." + +#: ../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." +msgstr "" +"பைதான் மற்றும் பைபி சக்கரங்கள் மற்றும் எச்.டிச்ட்ச் இரண்டையும் ஒன்றாக பதிவேற்றுவதை " +"எளிதாக்குகின்றன. பின்வருமாறு: டாக்: `டுடோரியல்கள்/பேக்கேசிங்-திட்டங்கள்` டுடோரியல்." + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "கருவிகள் மற்றும் நூலகங்களுக்கான பைத்தானின் பேக்கேசிங் திறன்களின் சுருக்கம்." + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" +"பைத்தானின் பரிந்துரைக்கப்பட்ட உள்ளமைக்கப்பட்ட நூலகம் மற்றும் கருவி பேக்கேசிங் தொழில்நுட்பங்கள். " +"`தி பேக்கேசிங் சாய்வு (2017) ` _ " +"இலிருந்து எடுக்கப்பட்டது." + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "பைதான் பயன்பாடுகள் பேக்கேசிங்" + +#: ../source/overview.rst:154 +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." +msgstr "" +"இதுவரை நாங்கள் பைத்தானின் சொந்த விநியோக கருவிகளைப் பற்றி மட்டுமே விவாதித்தோம். எங்கள் " +"அறிமுகத்தின் அடிப்படையில், இந்த உள்ளமைக்கப்பட்ட அணுகுமுறைகளை பைதான் கொண்ட இலக்கு " +"சூழல்களையும், பைதான் தொகுப்புகளை எவ்வாறு நிறுவுவது என்று தெரிந்த பார்வையாளர்களையும் " +"ஊகிப்பது சரியானதாக இருக்கும்." + +#: ../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/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 "" +"டெவலப்பர்களுக்கு இடையில் நூலகங்கள் எனப்படும் மறுபயன்பாட்டு குறியீட்டை விநியோகிப்பதற்காக " +"பைதானின் சொந்த பேக்கேசிங் பெரும்பாலும் கட்டப்பட்டுள்ளது. பைத்தானின் நூலக பேக்கேசிங்கின் " +"மேல், டெவலப்பர்களுக்கான அடிப்படை பயன்பாடுகளை நீங்கள் பிக்பேக் ** கருவிகள் ** அல்லது " +"டெவலப்பர்களுக்கான அடிப்படை பயன்பாடுகள், இது போன்ற தொழில்நுட்பங்களைப் பயன்படுத்தலாம்: டாக்: " +"`செட்டப்டூல்ச் என்ட்ரிச் <செட்டப்டூல்ச்: யூசர்சூட்/என்ட்ரி_போன்ட்>`." + +#: ../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." +msgstr "" +"நூலகங்கள் கட்டும் தொகுதிகள், முழுமையான பயன்பாடுகள் அல்ல. பயன்பாடுகளை விநியோகிக்க, " +"தொழில்நுட்பங்களின் புதிய உலகம் அங்கே உள்ளது." + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "ஒரு கட்டமைப்பைப் பொறுத்து" + +#: ../source/overview.rst:180 +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." +msgstr "" +"வலைத்தள பின்தளத்தில் மற்றும் பிற பிணையம் சேவைகள் போன்ற சில வகையான பைதான் பயன்பாடுகள் " +"அவற்றின் வளர்ச்சி மற்றும் பேக்கேசிங் செயல்படுத்த கட்டமைப்பைக் கொண்டிருக்கும் அளவுக்கு " +"பொதுவானவை. மாறும் வெப் ஃபிரண்டண்ட்ச் மற்றும் மொபைல் கிளையண்டுகள் போன்ற பிற வகையான " +"பயன்பாடுகள், ஒரு கட்டமைப்பை ஒரு வசதியை விட அதிகமாக மாறுகின்றன என்பதை குறிவைக்க " +"போதுமான சிக்கலானவை." + +#: ../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." +msgstr "" +"இந்த எல்லா சந்தர்ப்பங்களிலும், கட்டமைப்பின் பேக்கேசிங் மற்றும் வரிசைப்படுத்தல் கதையிலிருந்து " +"பின்னோக்கி வேலை செய்வது அர்த்தமுள்ளதாக இருக்கிறது. சில கட்டமைப்புகளில் ஒரு " +"வரிசைப்படுத்தல் அமைப்பு அடங்கும், இது வழிகாட்டியின் மற்ற பகுதிகளில் கோடிட்டுக் காட்டப்பட்ட " +"தொழில்நுட்பங்களை மூடுகிறது. இந்த சந்தர்ப்பங்களில், உங்கள் கட்டமைப்பின் பேக்கேசிங் வழிகாட்டியை " +"எளிதான மற்றும் மிகவும் நம்பகமான விளைவாக்கம் அனுபவத்திற்காக ஒத்திவைக்க விரும்புவீர்கள்." + +#: ../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." +msgstr "" +"இந்த தளங்களும் கட்டமைப்புகளும் பேட்டைக்கு அடியில் எவ்வாறு செயல்படுகின்றன என்பதை நீங்கள் " +"எப்போதாவது ஆச்சரியப்படுகிறீர்கள் என்றால், நீங்கள் எப்போதும் அப்பால் உள்ள பிரிவுகளை படிக்கலாம்." + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "பணி தளங்கள்" + +#: ../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 "" +"நீங்கள் ஒரு \"இயங்குதள-அச்-அச்-எ-சர்வீச் ` _ \"அல்லது\" பாச் \"க்கு வளர்ந்து வருகிறீர்கள் என்றால், நீங்கள் " +"அந்தந்த பேக்கேசிங் வழிகாட்டிகளைப் பின்பற்ற விரும்புகிறீர்கள் . இந்த வகையான தளங்கள் நீங்கள் " +"அவற்றின் வடிவங்களைப் பின்பற்றும் வரை, பேக்கேசிங் மற்றும் வரிசைப்படுத்தலை " +"கவனித்துக்கொள்கின்றன. பெரும்பாலான மென்பொருள்கள் இந்த வார்ப்புருக்களில் ஒன்றுக்கு பொருந்தாது, " +"எனவே கீழே உள்ள மற்ற எல்லா விருப்பங்களின் இருப்பு." + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" +"பைத்தானின் நிலையான முன்னேற்றங்கள் அதை புதிய இடங்களுக்கு இட்டுச் செல்கின்றன. இந்த நாட்களில் " +"நீங்கள் பைத்தானில் மொபைல் பயன்பாடு அல்லது வலை பயன்பாட்டு முன்பக்கத்தை எழுதலாம். மொழி " +"தெரிந்திருக்கலாம் என்றாலும், பேக்கேசிங் மற்றும் வரிசைப்படுத்தல் நடைமுறைகள் புத்தம் புதியவை." + +#: ../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/overview.rst:220 +msgid "`Kivy `_" +msgstr "" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "`Beeware ` _" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "`பிரைதான் ` _" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "முன்பே நிறுவப்பட்ட பைத்தானைப் பொறுத்து" + +#: ../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 "" +"ஒரு தன்னிச்சையான கணினியைத் தேர்ந்தெடுத்து, சூழலைப் பொறுத்து, பைதான் ஏற்கனவே நிறுவப்பட்ட " +"ஒரு நல்ல வாய்ப்பு உள்ளது. இப்போது பல ஆண்டுகளாக பெரும்பாலான லினக்ச் மற்றும் மேக் இயக்க " +"முறைமைகளில் இயல்பாகவே சேர்க்கப்பட்டுள்ளது, உங்கள் தரவு மையங்களில் அல்லது உருவாக்குபவர்கள் " +"மற்றும் தரவு விஞ்ஞானிகளின் தனிப்பட்ட இயந்திரங்களை முன்கூட்டியே முன்கூட்டியே நீங்கள் " +"நியாயமான முறையில் சார்ந்து இருக்க முடியும்." + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "இந்த மாதிரியை ஆதரிக்கும் தொழில்நுட்பங்கள்:" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr ":gh:`PEX ` (Python EXecutable)" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" +":doc:`zipapp ` (does not உதவி manage dependencies, " +"requires பைதான் 3.5+)" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr ":gh:`shiv ` (requires பைதான் 3)" + +#: ../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 "" +"இங்குள்ள அனைத்து அணுகுமுறைகளிலும், முன்பே நிறுவப்பட்ட பைத்தானைப் பொறுத்து இலக்கு சூழலை " +"மிகவும் நம்பியுள்ளது. நிச்சயமாக, இது ஒற்றை இலக்க மெகாபைட்டுகள் அல்லது கிலோபைட்டுகள் " +"போன்ற சிறிய தொகுப்பையும் உருவாக்குகிறது." + +#: ../source/overview.rst:249 +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 "" +"பொதுவாக, இலக்கு அமைப்பின் சார்புநிலையைக் குறைப்பது எங்கள் தொகுப்பின் அளவை " +"அதிகரிக்கிறது, எனவே இங்குள்ள தீர்வுகள் வெளியீட்டின் அளவை அதிகரிப்பதன் மூலம் தோராயமாக " +"ஏற்பாடு செய்யப்படுகின்றன." + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "ஒரு தனி மென்பொருள் விநியோக சுற்றுச்சூழல் அமைப்பைப் பொறுத்து" + +#: ../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 "" +"மேக் மற்றும் சாளரங்கள் உள்ளிட்ட பல இயக்க முறைமைகள் நீண்ட காலமாக உள்ளமைக்கப்பட்ட தொகுப்பு " +"மேலாண்மை இல்லை. அண்மைக் காலத்தில் தான் இந்த OS கள் \"பயன்பாட்டுக் கடைகள்\" என்று " +"அழைக்கப்படுவதைப் பெற்றன, ஆனால் அவை நுகர்வோர் பயன்பாடுகளில் கவனம் செலுத்துகின்றன, மேலும் " +"டெவலப்பர்களுக்கு சிறிதளவே வழங்குகின்றன." + +#: ../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 "" +"உருவாக்குபவர்கள் நீண்டகாலமாக தீர்வுகளைத் தேடினர், இந்த போராட்டத்தில், `ஓம் ப்ரூ ` _ போன்ற தங்கள் சொந்த தொகுப்பு மேலாண்மை தீர்வுகளுடன் வெளிப்பட்டனர். பைதான் " +"டெவலப்பர்களுக்கு மிகவும் பொருத்தமான மாற்று `அனகோண்டா ` _. அனகோண்டா பைத்தானைச் சுற்றி கட்டப்பட்டுள்ளது " +"மற்றும் கல்வி, பகுப்பாய்வு மற்றும் பிற தரவு சார்ந்த சூழல்களில் பெருகிய முறையில் " +"பொதுவானது, சேவையக சார்ந்த சூழல்களில் கூட அதன் வழியை உருவாக்குகிறது `_" +msgstr "" +"`காண்டாவுடன் நூலகங்கள் மற்றும் பயன்பாடுகளை உருவாக்குதல் ` _" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" +"`ஒரு சொந்த பைதான் தொகுப்பை அனகோண்டா ` _" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" +"இதேபோன்ற மாதிரி மாற்று பைதான் விநியோகத்தை நிறுவுவதை உள்ளடக்கியது, ஆனால் தன்னிச்சையான " +"இயக்க முறைமை-நிலை தொகுப்புகளை ஆதரிக்காது:" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" +"`ஆக்டிவ்ச்டேட் ஆக்டிவ் பைதான் ` _" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "`Winpython ` _" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "உங்கள் சொந்த பைதான் இயங்கக்கூடியது" + +#: ../source/overview.rst:290 +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." +msgstr "" +"கணக்கிடுவது எங்களுக்குத் தெரியும், இது நிரல்களை இயக்கும் திறனால் வரையறுக்கப்படுகிறது. " +"ஒவ்வொரு இயக்க முறைமையும் அவர்கள் சொந்தமாக செயல்படுத்தக்கூடிய திட்டங்களின் ஒன்று அல்லது " +"அதற்கு மேற்பட்ட வடிவங்களை ஆதரிக்கிறது." + +#: ../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 "" +"உங்கள் பைதான் திட்டத்தை இந்த வடிவங்களில் ஒன்றாக மாற்றும் பல நுட்பங்கள் மற்றும் தொழில்நுட்பங்கள் " +"உள்ளன, அவற்றில் பெரும்பாலானவை பைதான் மொழிபெயர்ப்பாளர் மற்றும் வேறு எந்த சார்புகளையும் " +"ஒற்றை இயங்கக்கூடிய கோப்பில் உட்பொதிப்பது அடங்கும்." + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "பைதான் உறைவிப்பான் தேர்வு:" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" +"`pyinstaller ` _ - குறுக்கு " +"-தளம்" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" +"`cx_freeze ` _ - குறுக்கு -தளம்" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" +"கட்டளை -வரி நிறுவிகளுக்கு `கட்டமைப்பாளர் ` " +"_ -" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "`py2exe ` _ - சாளரங்கள் மட்டும்" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "`py2app ` _ - மேக் மட்டும்" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "`osnap ` _ - சாளரங்கள் மற்றும் மேக்" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "`pynsist ` _ - சாளரங்கள் மட்டும்" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" +"மேலே உள்ள பெரும்பாலானவை ஒற்றை-பயனர் வரிசைப்படுத்தல்களைக் குறிக்கின்றன. பல-கூறு சேவையக " +"பயன்பாடுகளுக்கு, காண்க: GH: `செஃப் ஆம்னிபச் <செஃப்/ஓம்னிபச்#பயனர்-உள்ளடக்கம்-ஓம்னிபச்>`." + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "உங்கள் சொந்த பயனர்களைக் கொண்டுவருகிறது" + +#: ../source/overview.rst:321 +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*." +msgstr "" +"லினக்ச், மேக் ஓஎச் மற்றும் சாளரங்கள் உள்ளிட்ட இயக்க முறைமைகளின் எண்ணிக்கை அதிகரித்து " +"வருகிறது-இலகுரக படங்களாக தொகுக்கப்பட்ட பயன்பாடுகளை இயக்க அமைக்கலாம், ஒப்பீட்டளவில் நவீன " +"ஏற்பாட்டைப் பயன்படுத்தி பெரும்பாலும் `இயக்க-அமைப்பு-நிலை மெய்நிகராக்கம் `_" +msgstr "`அபிமேச் ` _" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "`டோக்கர் ` _" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "`Flatpak _" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "`Snapcract ` _" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "உங்கள் சொந்த கர்னலைக் கொண்டுவருகிறது" + +#: ../source/overview.rst:342 +#, fuzzy +#| 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." +msgid "" +"Most desktop 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 "" +"பெரும்பாலான இயக்க முறைமைகள் சில வகையான பாரம்பரிய மெய்நிகராக்கத்தை ஆதரிக்கின்றன, " +"இயங்கும் பயன்பாடுகள் அவற்றின் சொந்த முழு இயக்க முறைமையைக் கொண்ட படங்களாக " +"தொகுக்கப்பட்டுள்ளன. இந்த மெய்நிகர் இயந்திரங்கள் அல்லது விஎம்எச் இயக்குவது ஒரு முதிர்ந்த " +"அணுகுமுறையாகும், இது தரவு மைய சூழல்களில் பரவலாக உள்ளது." + +#: ../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:" +msgstr "" +"இந்த நுட்பங்கள் பெரும்பாலும் தரவு மையங்களில் பெரிய அளவிலான வரிசைப்படுத்தலுக்காக " +"ஒதுக்கப்பட்டுள்ளன, இருப்பினும் சில சிக்கலான பயன்பாடுகள் இந்த பேக்கேசிங்கிலிருந்து " +"பயனடையக்கூடும். தொழில்நுட்பங்கள் பைதான் அஞ்ஞானவாதிகள், மேலும் பின்வருவன அடங்கும்:" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"<ஓபன்ச்டாக்: பயனர்/வடிவங்கள்> `" + +#: ../source/overview.rst:356 +#, fuzzy +#| msgid "" +#| "`OpenStack `_ - A cloud " +#| "management system in Python, with extensive VM support" +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" +"`OpenStack ` _ - பைத்தானில் ஒரு " +"முகில் மேனேச்மென்ட் சிச்டம், விரிவான விஎம் ஆதரவுடன்" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "உங்கள் சொந்த வன்பொருளைக் கொண்டு வருகிறது" + +#: ../source/overview.rst:362 +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." +msgstr "" +"உங்கள் மென்பொருளை அனுப்புவதற்கான அனைத்தையும் உள்ளடக்கிய வழி, ஏற்கனவே நிறுவப்பட்ட சில " +"வன்பொருள்களில் அனுப்பப்படுவதாகும். இந்த வழியில், உங்கள் மென்பொருளின் பயனருக்கு மின்சாரம் " +"மட்டுமே தேவைப்படும்." + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" +"உங்கள் குறியீட்டை AN: GH: `adafruit `, `மைக்ரோபிதான் " +"` _, அல்லது பைத்தானில் இயங்கும் அதிக சக்திவாய்ந்த வன்பொருள் " +"' வீடுகள். அவை செருகப்பட்டு விளையாடுகின்றன, நீங்கள் அதை ஒரு நாளைக்கு அழைக்கலாம்." + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "பைதான் பயன்பாடுகளை தொகுக்கப் பயன்படுத்தப்படும் தொழில்நுட்பங்களின் சுருக்கம்." + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" +"பைதான் பயன்பாடுகளை தொகுக்கப் பயன்படுத்தப்படும் தொழில்நுட்பங்களின் எளிமைப்படுத்தப்பட்ட வரம்பு." + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "என்ன ..." + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "இயக்க முறைமை தொகுப்புகள்" + +#: ../source/overview.rst:390 +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: `மேலே-பிரிக்கப்படாத-சுற்றுச்சூழல் அமைப்பைப் பொறுத்து, சில இயக்க " +"முறைமைகள் தங்கள் சொந்த தொகுப்பு மேலாளர்களைக் கொண்டுள்ளன. நீங்கள் குறிவைக்கும் இயக்க " +"முறைமையைப் பற்றி நீங்கள் மிகவும் உறுதியாக இருந்தால், `டெப் ` _ (டெபியனைப் பொறுத்தவரை, உபுண்டு , முதலியன) அல்லது " +"`ஆர்.பி.எம் `_ (Red Hat, " +"Fedora போன்றவற்றுக்கு), மற்றும் அந்த உள்ளமைக்கப்பட்ட தொகுப்பு மேலாளரை நிறுவலை " +"கவனித்துக்கொள்வதற்கும், வரிசைப்படுத்துவதையும் பயன்படுத்தவும். ஒரே மூலத்திலிருந்து DEB " +"மற்றும் RPMS இரண்டையும் உருவாக்க `FPM ` 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 "" +". குறிப்பாக பேக்கேசிங் மூலம், மெய்நிகர்இன்வி கள் ஒரு பழமையானதாகப் பயன்படுத்தப்படுகின்றன: " +"டாக்: `டிஎச்ச்டுவல்என்வ் கருவி ` மற்றும் `osnap ` _, இரண்டும் இது மெய்நிகர்என்வ்சை ஒரு தன்னிறைவான முறையில் " +"போர்த்தி விடுகிறது." + +#: ../source/overview.rst:416 +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." +msgstr "" +"விளைவாக்கம் வரிசைப்படுத்தல்களைப் பொறுத்தவரை, ஒரு மேம்பாட்டு சூழலில் ஒருவர் " +"செய்யக்கூடியபடி, இணையத்திலிருந்து `பைதான் -எம் பிஐபி நிறுவலை` `பைதான் -எம் பிஐபி " +"நிறுவலை ஒரு மெய்நிகர் ஈவுக்குள் இயக்குவதை நம்ப வேண்டாம். மேலே உள்ள கண்ணோட்டம் மிகச் சிறந்த " +"தீர்வுகள் நிறைந்தது." + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "பாதுகாப்பு" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" +"நீங்கள் வரும் சாய்வு மேலும் கீழே, உங்கள் தொகுப்பின் கூறுகளைப் புதுப்பிப்பது கடினம். எல்லாம் " +"மிகவும் இறுக்கமாக ஒன்றாக பிணைக்கப்பட்டுள்ளது." + +#: ../source/overview.rst:426 +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 `_." +msgstr "" +"எடுத்துக்காட்டாக, ஒரு கர்னல் பாதுகாப்பு சிக்கல் வெளிவந்தால், நீங்கள் கொள்கலன்களைப் " +"பயன்படுத்தினால், பயன்பாட்டின் சார்பாக புதிய கட்டிடம் தேவையில்லாமல் புரவலன் அமைப்பின் கர்னலை " +"புதுப்பிக்க முடியும். நீங்கள் விஎம் படங்களை வரிசைப்படுத்தினால், உங்களுக்கு புதிய உருவாக்கம் " +"தேவை. இந்த மாறும் ஒரு விருப்பத்தை மிகவும் பாதுகாப்பாக ஆக்குகிறதா இல்லையா என்பது இன்னும் " +"பழைய விவாதமாக உள்ளது, இது `நிலையான மற்றும் மாறும் இணைக்கும் `_." + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "மடக்கு" + +#: ../source/overview.rst:437 +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." +msgstr "" +"பைத்தானில் பேக்கேசிங் ஒரு சமதள சவாரி என்ற நற்பெயரைக் கொண்டுள்ளது. இந்த எண்ணம் பெரும்பாலும் " +"பைத்தானின் பல்துறைத்திறனின் துணை தயாரிப்பு ஆகும். ஒவ்வொரு பேக்கேசிங் தீர்வுக்கும் இடையிலான " +"இயற்கை எல்லைகளை நீங்கள் புரிந்துகொண்டவுடன், மாறுபட்ட நிலப்பரப்பு ஒரு சிறிய விலை பைதான் " +"புரோகிராமர்கள் மிகவும் சீரான, நெகிழ்வான மொழிகளில் ஒன்றைப் பயன்படுத்துவதற்கு செலுத்தும் " +"ஒரு சிறிய விலை என்பதை நீங்கள் உணரத் தொடங்குகிறீர்கள்." + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "பைனரி விநியோக வடிவம்" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" +"இந்த பக்கம் பைதான் தொகுப்புகளுக்கான பைனரி விநியோக வடிவமைப்பைக் குறிப்பிடுகிறது, இது " +"சக்கர வடிவம் என்றும் அழைக்கப்படுகிறது." + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" +"ஒரு சக்கரம் என்பது விசேசமாக வடிவமைக்கப்பட்ட கோப்பு பெயர் மற்றும் `` .Whl`` நீட்டிப்பு " +"கொண்ட ஒரு சிப் வடிவ காப்பகம். ஒரு குறிப்பிட்ட நிறுவல் திட்டத்துடன் PEP 376 இன் படி " +"நிறுவப்படும் என்பதால் இது ஒரு விநியோகத்தைக் கொண்டுள்ளது. ஒரு சிறப்பு நிறுவி " +"பரிந்துரைக்கப்பட்டாலும், நிலையான 'அன்சிப்' கருவியுடன் தளத் தொகுப்புகளைத் திறப்பதன் மூலம் " +"ஒரு சக்கர கோப்பு நிறுவப்படலாம், அதே நேரத்தில் அதன் உள்ளடக்கங்களை எந்த நேரத்திலும் அவற்றின் " +"இறுதி பாதைகளில் பரப்புவதற்கு போதுமான தகவல்களைப் பாதுகாக்கிறது." + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "விவரங்கள்" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "ஒரு சக்கரத்தை நிறுவுதல்" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "சக்கர நிறுவல் இரண்டு கட்டங்களைக் கொண்டுள்ளது:" + +#: ../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 "`` வழங்கல் -1.0.dist-info/wheel``." + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" +"நிறுவி சக்கர அழுத்தத்துடன் இணக்கமானது என்பதை சரிபார்க்கவும். சிறிய பதிப்பு அதிகமாக " +"இருந்தால் எச்சரிக்கவும், முக்கிய பதிப்பு அதிகமாக இருந்தால் கைவிடவும்." + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" +"ரூட்-ஐச்-பூரெலிப் == 'உண்மை' என்றால், காப்பகத்தை பியூரிலிப்பில் (தள-பேக்கேச்கள்) திறக்கவும்." + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "பிளாட்ட்லிபில் (தள-பேக்கேச்கள்) காப்பகத்தைத் திறக்கவும்." + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "பரவுதல்." + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" +"தொகுக்கப்படாத காப்பகத்தில் `` வழங்கல் -1.0.dist-info/`` மற்றும் (தரவு இருந்தால்) `` " +"வழங்கல் -1.0.data/`` ஆகியவை அடங்கும்." + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" +"`` வழங்கல் -1.0.data/`` இன் ஒவ்வொரு துணைக்குழுவையும் அதன் இலக்கு பாதையில் நகர்த்தவும். " +"`` வழங்கல் -1.0.data/`` இன் ஒவ்வொரு துணை அடைவுகளும், `` விநியோக -1.0.data/ " +"(PURELIB | PLATLIB | தலைப்புகள் | ச்கிரிப்டுகள் | தரவு) `` போன்ற இலக்கு கோப்பகங்களின் " +"கட்டளைக்கு ஒரு முக்கியமாகும். இந்த துணை அடைவுகள்: குறிப்பு: `சிச்கான்ஃபிக் <பைதான்: " +"நிறுவல்_பாத்ச்> ஆல் வரையறுக்கப்பட்ட நிறுவல் பாதைகள்>`." + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" +"பொருந்தினால், சரியான மொழிபெயர்ப்பாளரை சுட்டிக்காட்ட ``#! பைதான்`` உடன் தொடங்கி " +"ச்கிரிப்ட்களைப் புதுப்பிக்கவும்." + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "நிறுவப்பட்ட பாதைகளுடன் `` வழங்கல் -1.0.dist-info/பதிவு`` புதுப்பிக்கவும்." + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "வெற்று `` வழங்கல் -1.0.data`` கோப்பகத்தை அகற்று." + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" +"நிறுவப்பட்ட .py பெறுநர் .pyc க்கு தொகுக்கவும். (நிறுவல் நீக்குபவர்கள் .pyc ஐ அகற்றும் " +"அளவுக்கு புத்திசாலித்தனமாக இருக்க வேண்டும்." + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "பரிந்துரைக்கப்பட்ட நிறுவி நற்பொருத்தங்கள்" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "``#! பைதான்`` மீண்டும் எழுதவும்." + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" +"சக்கரத்தில், ச்கிரிப்ட்கள் `` {distribution}-{version} .data/ச்கிரிப்டுகள்/`` " +"ஆகியவற்றில் தொகுக்கப்பட்டுள்ளன. `` ச்கிரிப்டுகள்/`` இல் உள்ள ஒரு கோப்பின் முதல் வரி சரியாக " +"`` பி '#! பைதான்'ஆ'` உடன் தொடங்கினால், சரியான மொழிபெயர்ப்பாளரை சுட்டிக்காட்ட மீண்டும் " +"எழுதவும். சாளரங்களில் காப்பகம் உருவாக்கப்பட்டால் யுனிக்ச் நிறுவிகள் இந்த கோப்புகளில் +எக்ச் " +"பிட் சேர்க்க வேண்டியிருக்கலாம்." + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" +"`` B '#! பைதன்வ்'` மண்டலத்தை அனுமதிக்கிறது. `` பி '#! பைதன்வ்'`` ஒரு கன்சோல் " +"ச்கிரிப்ட்டுக்கு பதிலாக ஒரு சி.யு.ஐ ச்கிரிப்டைக் குறிக்கிறது." + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "ச்கிரிப்ட் ரேப்பர்களை உருவாக்குங்கள்." + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" +"சக்கரத்தில், யூனிக்ச் அமைப்புகளில் தொகுக்கப்பட்ட ச்கிரிப்ட்கள் நிச்சயமாக .exe ரேப்பர்களைக் " +"கொண்டிருக்காது. சாளரங்கள் நிறுவிகள் நிறுவலின் போது அவற்றைச் சேர்க்க விரும்பலாம்." + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "பரிந்துரைக்கப்பட்ட காப்பக நற்பொருத்தங்கள்" + +#: ../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 "" +"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 "" +"காப்பகத்தின் முடிவில் `` .டிச்ட்-இன்ஃபோ`` கோப்புகளை உடல் ரீதியாக வைக்க காப்பகர்கள் " +"ஊக்குவிக்கப்படுகிறார்கள். முழு காப்பகத்தையும் மீண்டும் எழுதாமல் மெட்டாடேட்டாவை " +"திருத்துவதற்கான திறன் உள்ளிட்ட சில சுவையான சிப் தந்திரங்களை இது செயல்படுத்துகிறது." + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "கோப்பு வடிவம்" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "கோப்பு பெயர் மாநாடு" + +#: ../source/specifications/binary-distribution-format.rst:92 +msgid "" +"The wheel filename is ``{distribution}-{version}(-{build tag})?-{python tag}-" +"{abi tag}-{platform tag}.whl``." +msgstr "சக்கர கோப்பு பெயர் `{distribution}-{version} (-{{build tag})?" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "distribution" +msgstr "பரவல்" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "விநியோக பெயர், எ.கா. 'சாங்கோ', 'பிரமிட்'." + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../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 "" +"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 "" +"விருப்ப உருவாக்க எண். ஒரு இலக்கத்துடன் தொடங்க வேண்டும். மற்ற எல்லா விசயங்களிலும் (அதாவது " +"பெயர், பதிப்பு மற்றும் பிற குறிச்சொற்கள்) இரு சக்கர கோப்பு பெயர்கள் ஒரே மாதிரியாக " +"இருந்தால் டை-பிரேக்கராக செயல்படுகிறது. குறிப்பிடப்படாவிட்டால் வெற்று டப்பிள் என " +"வரிசைப்படுத்தவும், இல்லையெனில் இரண்டு-உருப்படி டப்பிள் என வரிசைப்படுத்தவும் முதல் உருப்படி " +"ஆரம்ப இலக்கங்களை `` int`` ஆகவும், இரண்டாவது உருப்படி குறிச்சொல்லின் எஞ்சியதான் `` str`` " +"ஆகவும் இருக்கும்." + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" +"உருவாக்க எண்களுக்கான பொதுவான பயன்பாட்டு வழக்கு, உருவாக்கும் சூழலில் ஏற்பட்ட மாற்றத்தின் " +"காரணமாக பைனரி விநியோகத்தை மீண்டும் கட்டியெழுப்புவதாகும், இது மேனிலினக்ச் படத்தைப் " +"பயன்படுத்தும் போது, முன் வெளியீட்டுக்கு முன் சிபிதான் பதிப்புகளைப் பயன்படுத்தி " +"விநியோகங்களை உருவாக்குகிறது." + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" +"உருவாக்க எண்கள் விநியோக பதிப்பின் ஒரு பகுதியாக இல்லை, இதனால் வெளிப்புறமாகக் " +"குறிப்பிடுவது கடினம், குறிப்பாக கருவிகள் மற்றும் தரங்களின் பைதான் சுற்றுச்சூழல் " +"அமைப்புக்கு வெளியே. பாதுகாப்பு பாதிப்பைத் தீர்க்கும்போது ஒரு வழங்கல் வெளிப்புறமாகக் " +"குறிப்பிட வேண்டிய ஒரு பொதுவான வழக்கு." + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" +"இந்த வரம்பு காரணமாக, புதிய விநியோகத்தை உருவாக்கும் போது வெளிப்புறமாக குறிப்பிட " +"வேண்டிய புதிய விநியோகங்கள் ** ** உருவாக்க எண்களைப் பயன்படுத்தக்கூடாது. அதற்கு பதிலாக " +"** புதிய விநியோக பதிப்பு ** இதுபோன்ற நிகழ்வுகளுக்கு உருவாக்கப்பட வேண்டும்." + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "மொழி செயல்படுத்தல் மற்றும் பதிப்பு குறிச்சொல்" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "எ.கா. 'PY27', 'PY2', 'PY3'." + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "அபி நாள்" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "எ.கா. 'cp33m', 'abi3', 'எதுவுமில்லை'." + +#: ../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 "எ.கா. 'லினக்ச்_எக்ச் 86_64', 'ஏதேனும்'." + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" +"எடுத்துக்காட்டாக, `` வழங்கல் -1.0-1-PY27-NONE-Any.Whl`` என்பது 'வழங்கல்' என்று " +"அழைக்கப்படும் ஒரு தொகுப்பின் முதல் கட்டமைப்பாகும், மேலும் இது பைதான் 2.7 (எந்த பைத்தான் " +"2.7 அமலாக்கமும்) உடன் இணக்கமானது, பநிஇ இல்லாமல் (தூய்மையானது பைதான்), எந்த சிபியு " +"கட்டிடக்கலையிலும்." + +#: ../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/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "தப்பித்தல் மற்றும் யூனிகோட்" + +#: ../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 "" +"கோப்பு பெயரின் கூறுகள் ஒரு கோடு (`` -``, ஐபன்-மைனச்) மூலம் பிரிக்கப்படுவதால், இந்த " +"பாத்திரம் எந்த கூறுகளிலும் தோன்ற முடியாது. இது பின்வருமாறு கையாளப்படுகிறது:" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" +"விநியோக பெயர்களில், `` -_. . இது வழக்கமானதாகும்: ref: `பெயர் இயல்பாக்கம் <பெயர்-" +"இயல்பாக்கம்>` தொடர்ந்து `` -`` ஐ `` _`` உடன் மாற்றுவதன் மூலம். `` .` (முழு நிறுத்தம்) " +"மற்றும் பெரிய எழுத்துக்களை ஏற்றுக்கொள்ள கருவிகள் எடுக்கும் சக்கரங்கள் தயாராக இருக்க " +"வேண்டும், இருப்பினும், இந்த விவரக்குறிப்பின் முந்தைய பதிப்பால் இவை அனுமதிக்கப்பட்டன." + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" +"பதிப்பு எண்களை இயல்பாக்க வேண்டும்: ref: `பதிப்பு விவரக்குறிப்பு விவரக்குறிப்பு <பதிப்பு-" +"விவரக்குறிப்புகள்>`. இயல்பாக்கப்பட்ட பதிப்பு எண்களில் `` -`` இருக்க முடியாது." + +#: ../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: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 "" +"சக்கரங்களை உருவாக்கும் கருவிகள் கோப்பு பெயர் கூறுகளில் `` -`` ஐக் கொண்டிருக்கவில்லை " +"என்பதை சரிபார்க்க வேண்டும், ஏனெனில் அவை செய்தால் அவை சரியாக செயலாக்கப்படாது." + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" +"காப்பக கோப்பு பெயர் யூனிகோட். ASCII அல்லாத கோப்பு பெயர்களை ஆதரிப்பதற்காக கருவிகள் " +"புதுப்பிக்கப்படுவதற்கு சில காலம் ஆகும், ஆனால் அவை இந்த விவரக்குறிப்பில் ஆதரிக்கப்படுகின்றன." + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" +"கோப்பு பெயர்கள் * உள்ளே * காப்பகம் யுடிஎஃப் -8 என குறியாக்கம் செய்யப்படுகிறது. பொதுவான " +"பயன்பாட்டில் உள்ள சில சிப் வாடிக்கையாளர்கள் யுடிஎஃப் -8 கோப்பு பெயர்களைக் சரியாகக் " +"காட்டவில்லை என்றாலும், குறியாக்கம் சிப் விவரக்குறிப்பு மற்றும் பைதானின் `` சிப்ஃபைல்`` " +"ஆகிய இரண்டாலும் ஆதரிக்கப்படுகிறது." + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "கோப்பு உள்ளடக்கங்கள்" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" +"ஒரு சக்கர கோப்பின் உள்ளடக்கங்கள், அங்கு {distribution} மாற்றப்படுகிறது: ref: " +"`இயல்பாக்கப்பட்ட பெயர் <பெயர்-இயல்பாக்கம்>` தொகுப்பின், எ.கா. `` பீக்லெவோட்`` மற்றும் " +"{version} அதன் மூலம் மாற்றப்படுகிறது: குறிப்பு: `இயல்பாக்கப்பட்ட பதிப்பு <பதிப்பு-" +"விவரக்குறிப்புகள்-இயல்பாக்கம்>`, எ.கா. `` 1.0.0``, (கோடு/`` -`` எழுத்துக்கள் " +"அடிக்கோடிட்டுக் காட்டுகின்றன/`` _`` இரு துறைகளிலும் எழுத்துக்கள்) பின்வருமாறு:" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" +"``/``, காப்பகத்தின் வேர், `` வீல்`` இல் குறிப்பிடப்பட்டுள்ளபடி `` பியூரிலிப்` அல்லது `` " +"பிளாட்ட்லிப்`` இல் நிறுவப்பட வேண்டிய அனைத்து கோப்புகளையும் கொண்டுள்ளது. `` purelib`` " +"மற்றும் `` பிளாட்ட்லிப்`` ஆகியவை வழக்கமாக `` தள-பேக்கேச்கள்`." + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "`{distribution}-{version} .dist-info/` `மெட்டாடேட்டாவைக் கொண்டுள்ளது." + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" +": கோப்பு: `{distribution}-{version} .dist-info/உரிமங்கள்/` உரிமக் கோப்புகளைக் " +"கொண்டுள்ளது." + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" +"`{distribution}-{version} .data/` `என்பது காலியாக இல்லாத நிறுவல் அல்லாத திட்ட " +"விசைக்கு ஒரு துணை அடைவைக் கொண்டுள்ளது, அங்கு துணை அடைவு பெயர் நிறுவல் பாதைகளின் " +"அகராதியாக ஒரு குறியீடாகும் (எ.கா.` தரவு`, `` ச்கிரிப்ட்கள்``, `` தலைப்புகள்``, `` " +"பியூரிலிப்``, `` பிளாட்ட்லிப்``)." + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" +"பைதான் ச்கிரிப்ட்கள் `` ச்கிரிப்ட்கள்`` இல் தோன்ற வேண்டும், மேலும் ச்கிரிப்ட் ரேப்பர் தலைமுறையை " +"அனுபவிப்பதற்காக சரியாக `` பி '#! அவர்களுக்கு ஏதேனும் அல்லது நீட்டிப்பு இல்லை. `` " +"ச்கிரிப்ட்கள்` `கோப்பகத்தில் வழக்கமான கோப்புகள் மட்டுமே இருக்கலாம்." + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater வடிவம் metadata." + +#: ../source/specifications/binary-distribution-format.rst:199 +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/binary-distribution-format.rst:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "`` சக்கர-பதிப்பு`` என்பது சக்கர விவரக்குறிப்பின் பதிப்பு எண்." + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" +"`` செனரேட்டர்`` என்பது காப்பகத்தை தயாரித்த மென்பொருளின் பெயர் மற்றும் விருப்பமாக " +"பதிப்பாகும்." + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" +"`` ரூட்-ஐச்-பூரெலிப்`` வட்டத்தின் உயர் மட்ட அடைவு பியூரிலிப்பில் நிறுவப்பட வேண்டும் என்றால் " +"உண்மைதான்; இல்லையெனில் ரூட் பிளாட்லிபில் நிறுவப்பட வேண்டும்." + +#: ../source/specifications/binary-distribution-format.rst:215 +msgid "" +"``Tag`` is the wheel's expanded compatibility tags; in the example the " +"filename would contain ``py2.py3-none-any``." +msgstr "" +"`` குறிச்சொல்`` என்பது சக்கரத்தின் விரிவாக்கப்பட்ட பொருந்தக்கூடிய குறிச்சொற்கள்; " +"எடுத்துக்காட்டில் கோப்பு பெயரில் `` py2.py3-none-any-`` இருக்கும்." + +#: ../source/specifications/binary-distribution-format.rst:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" +"`` பில்ட்`` என்பது உருவாக்க எண் மற்றும் உருவாக்க எண் இல்லாவிட்டால் தவிர்க்கப்படுகிறது." + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" +"ஒரு சக்கர நிறுவி அது ஆதரிக்கும் பதிப்பை விட சக்கர-பதிப்பு அதிகமாக இருக்கிறதா என்று " +"எச்சரிக்க வேண்டும், மேலும் சக்கர-பதிப்பு அது ஆதரிக்கும் பதிப்பை விட பெரிய பெரிய " +"பதிப்பைக் கொண்டிருந்தால் தோல்வியடைய வேண்டும்." + +#: ../source/specifications/binary-distribution-format.rst:221 +msgid "" +"Wheel, being an installation format that is intended to work across multiple " +"versions of Python, does not generally include .pyc files." +msgstr "" +"சக்கரம், பைத்தானின் பல பதிப்புகளில் வேலை செய்ய நோக்கம் கொண்ட ஒரு நிறுவல் வடிவமாக " +"இருப்பதால், பொதுவாக .pyc கோப்புகளை சேர்க்காது." + +#: ../source/specifications/binary-distribution-format.rst:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "சக்கரத்தில் setup.py அல்லது setup.cfg இல்லை." + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" +"சக்கர விவரக்குறிப்பின் இந்த பதிப்பு தொலைதூர நிறுவல் திட்டங்களை அடிப்படையாகக் கொண்டது " +"மற்றும் பிற இடங்களுக்கு கோப்புகளை எவ்வாறு நிறுவுவது என்பதை வரையறுக்கவில்லை. இந்த " +"தளவமைப்பு தற்போதுள்ள வினின்ச்ட் மற்றும் முட்டை பைனரி வடிவங்களால் வழங்கப்பட்ட செயல்பாட்டின் " +"ஒரு சூப்பர்செட்டை வழங்குகிறது." + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr ".டிச்ட்-இன்ஃபோ அடைவு" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" +"வீல் .டிச்ட்-இன்ஃபோ கோப்பகங்கள் குறைந்தபட்ச மேனிலை தரவு, சக்கரம் மற்றும் பதிவில் அடங்கும்." + +#: ../source/specifications/binary-distribution-format.rst:236 +msgid "" +"METADATA is the package metadata, the same format as PKG-INFO as found at " +"the root of sdists." +msgstr "" +"மேனிலை தரவு என்பது தொகுப்பு மேனிலை தரவு ஆகும், இது SDISTS இன் வேரில் காணப்படும் " +"பி.கே.சி-இன்ஃபோ போன்ற வடிவமாகும்." + +#: ../source/specifications/binary-distribution-format.rst:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "சக்கரம் என்பது தொகுப்பின் கட்டமைப்பிற்கு குறிப்பிட்ட சக்கர மேனிலை தரவு ஆகும்." + +#: ../source/specifications/binary-distribution-format.rst:239 +#, fuzzy +#| 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." +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." +msgstr "" +"பதிவு என்பது சக்கரத்தில் உள்ள அனைத்து கோப்புகளையும் அவற்றின் பாதுகாப்பான ஆச்களின் " +"(கிட்டத்தட்ட) பட்டியல். PEP 376 ஐப் போலன்றி, பதிவைத் தவிர ஒவ்வொரு கோப்பும், தன்னைத்தானே " +"ஒரு ஆசைக் கொண்டிருக்க முடியாது, அதன் ஆசைக் கொண்டிருக்க வேண்டும். ஆச் வழிமுறை SHA256 " +"அல்லது அதற்கு மேற்பட்டதாக இருக்க வேண்டும்; குறிப்பாக, MD5 மற்றும் SHA1 அனுமதிக்கப்படாது, " +"ஏனெனில் கையொப்பமிடப்பட்ட சக்கர கோப்புகள் காப்பகத்தின் ஒருமைப்பாட்டை சரிபார்க்க பதிவில் உள்ள " +"வலுவான ஆச்களை நம்பியுள்ளன." + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "PEP 376 இன் நிறுவி மற்றும் கோரப்பட்டவை காப்பகத்தில் சேர்க்கப்படவில்லை." + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +#, fuzzy +#| 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." +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" +"பிரித்தெடுக்கும் போது, சக்கர நிறுவிகள் கோப்பு உள்ளடக்கங்களுக்கு எதிராக பதிவுசெய்யப்பட்ட " +"அனைத்து ஆச்களையும் சரிபார்க்கின்றன. பதிவு மற்றும் அதன் கையொப்பங்களைத் தவிர, காப்பகத்தில் " +"உள்ள எந்தவொரு கோப்பும் குறிப்பிடப்படவில்லை மற்றும் பதிவில் சரியாக ஏச் செய்யப்பட்டால் நிறுவல் " +"தோல்வியடையும்." + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +#, fuzzy +#| msgid "Project name" +msgid "Subdirectory name" +msgstr "திட்ட பெயர்" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#, fuzzy +#| msgid "``license``" +msgid "``licenses``" +msgstr "`` உரிமம்``" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +#, fuzzy +#| msgid "``license-files``" +msgid "``license_files``" +msgstr "`` உரிம-கோப்புகள்``" + +#: ../source/specifications/binary-distribution-format.rst:266 +#, fuzzy +#| msgid "``LIB``" +msgid "``LICENSES``" +msgstr "`` லிப்``" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "தி: கோப்பு: `.டிச்ட்-இன்ஃபோ/உரிமங்கள்/` அடைவு" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" +"மேனிலை தரவு பதிப்பு 2.4 அல்லது அதற்கு மேற்பட்டது மற்றும் ஒன்று அல்லது அதற்கு மேற்பட்ட `` " +"உரிம-கோப்பு`` புலங்கள் குறிப்பிடப்பட்டால்,: கோப்பு: `.டிச்ட்-இன்ஃபோ/` கோப்பகத்தில் ஒரு: " +"கோப்பு: `உரிமங்கள்/` துணை அடைவு இருக்க வேண்டும், அதில் இருக்க வேண்டும் `` உரிமம்-" +"கோப்பு`` புலங்களில் பட்டியலிடப்பட்டுள்ள கோப்புகள்: கோப்பு: `மெட்டாடேட்டா` அந்தந்த பாதைகளில் " +"கோப்பு : கோப்பு: `உரிமங்கள்/` அடைவு." + +#: ../source/specifications/binary-distribution-format.rst:280 +#, fuzzy +#| msgid "The :file:`.dist-info/licenses/` directory" +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "தி: கோப்பு: `.டிச்ட்-இன்ஃபோ/உரிமங்கள்/` அடைவு" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr ".டேட்டா அடைவு" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" +"தள-தொகுப்புகளுக்குள் பொதுவாக நிறுவப்படாத எந்த கோப்பும் .data கோப்பகத்திற்குள் செல்கிறது, " +"இது .dist-info கோப்பகமாக பெயரிடப்பட்டது, ஆனால் .டேட்டா/ நீட்டிப்பு ::" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" +".டேட்டா கோப்பகத்தில் ச்கிரிப்ட்கள், தலைப்புகள், ஆவணங்கள் மற்றும் பலவற்றைக் கொண்ட துணை அடைவுகள் " +"உள்ளன. நிறுவலின் போது இந்த துணை அடைவுகளின் உள்ளடக்கங்கள் அவற்றின் இலக்கு பாதைகளில் " +"நகர்த்தப்படுகின்றன." + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "கேள்விகள்" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" +"சக்கரம் ஒரு .டேட்டா கோப்பகத்தை வரையறுக்கிறது. எனது எல்லா தரவையும் நான் அங்கு வைக்க " +"வேண்டுமா?" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" +"உங்கள் குறியீட்டை எவ்வாறு ஒழுங்கமைக்க வேண்டும் என்பது குறித்து இந்த விவரக்குறிப்புக்கு ஒரு " +"கருத்து இல்லை. .Data அடைவு என்பது பொதுவாக `` தள-பேக்கேச்கள்`` அல்லது பைதன்பாத்தில் " +"நிறுவப்படாத எந்த கோப்புகளுக்கும் ஒரு இடம். வேறு வார்த்தைகளில் கூறுவதானால், நீங்கள் " +"தொடர்ந்து `` pkgutil.get_data (தொகுப்பு, வளம்) `` அந்த * கோப்புகள் வழக்கமாக * " +"சக்கரத்தின் * `` .data`` கோப்பகத்தில் விநியோகிக்கப்படாது என்றாலும் தொடர்ந்து பயன்படுத்தலாம்." + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "\"பியூரிலிப்\" வெர்சச் \"பிளாட்ட்லிப்\" உடன் என்ன ஒப்பந்தம்?" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" +"சக்கரம் \"பியூரிலிப்\" எதிராக \"பிளாட்ட்லிப்\" வேறுபாட்டைப் பாதுகாக்கிறது, இது சில " +"தளங்களில் குறிப்பிடத்தக்கதாகும். எடுத்துக்காட்டாக, ஃபெடோரா தூய பைதான் தொகுப்புகளை '/usr/" +"lib/pythonx.y/site-packages' மற்றும் இயங்குதள சார்பு தொகுப்புகளை '/usr/lib64/" +"pythonx.y/site-packages' க்கு நிறுவுகிறது." + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" +"`` {name}-{version} .data/purelib`` இல் அதன் அனைத்து கோப்புகளையும் கொண்ட \"ரூட்-ஐச்-" +"பூரலிப்: பொய்\" கொண்ட ஒரு சக்கரம் \"ரூட்-இச்-பூரலிப்: ட்ரூ\" கொண்ட ஒரு சக்கரத்திற்கு சமம் " +"ரூட்டில் உள்ள கோப்புகள், மற்றும் \"பியூரிலிப்\" மற்றும் \"பிளாட்லிப்\" வகைகளில் கோப்புகளை " +"வைத்திருப்பது சட்டபூர்வமானது." + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" +"நடைமுறையில் ஒரு சக்கரத்தில் அது தூய பைத்தான் இல்லையா என்பதைப் பொறுத்து \"பியூரிலிப்\" " +"அல்லது \"பிளாட்லிப்\" ஒன்று மட்டுமே இருக்க வேண்டும், மேலும் அந்த கோப்புகள் \"ரூட்-இச்-" +"பூரெலிப்\" க்கு வழங்கப்பட்ட பொருத்தமான அமைப்போடு வேரில் இருக்க வேண்டும்." + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "சக்கர கோப்பிலிருந்து நேரடியாக பைதான் குறியீட்டை இறக்குமதி செய்ய முடியுமா?" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" +"தொழில்நுட்ப ரீதியாக, எளிய பிரித்தெடுத்தல் வழியாக துணை நிறுவலின் கலவையின் காரணமாகவும், " +"`` சிபிமோர்ட்`` உடன் இணக்கமான காப்பக வடிவமைப்பைப் பயன்படுத்துவதன் மூலமும், சக்கரக் " +"கோப்புகளின் துணைக்குழு * ஆதரவை நேரடியாக `` sys.path`` இல் வைக்கவும். இருப்பினும், " +"இந்த நடத்தை வடிவமைப்பு வடிவமைப்பின் இயல்பான விளைவு என்றாலும், உண்மையில் அதை " +"நம்பியிருப்பது பொதுவாக ஊக்கமளிக்கிறது." + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" +"முதலாவதாக, வீல் * முதன்மையாக ஒரு விநியோக வடிவமாக வடிவமைக்கப்பட்டுள்ளது, எனவே நிறுவல் " +"படியைத் தவிர்ப்பது என்பது முழு நிறுவலைக் கருதும் அம்சங்களை நம்பியிருப்பதை வேண்டுமென்றே " +"தவிர்ப்பது (`` பிப்` மற்றும் `` மெய்நிகர்என்.வி` போன்ற நிலையான கருவிகளைப் பயன்படுத்துவது " +"போன்றவை `தணிக்கை மற்றும் பாதுகாப்பு புதுப்பிப்பு நோக்கங்களுக்காக சரியாகக் " +"கண்காணிக்கக்கூடிய வகையில் சார்புகளை கைப்பற்றி நிர்வகிப்பது அல்லது வெளியீட்டின் மூலம் சி " +"நீட்டிப்புகளுக்கான நிலையான உருவாக்க இயந்திரங்களுடன் முழுமையாக ஒருங்கிணைத்தல் தலைப்பு " +"கோப்புகள் பொருத்தமான இடத்தில்)." + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" +"இரண்டாவதாக, சில பைதான் மென்பொருள்கள் ஒரு சிப் காப்பகத்திலிருந்து நேரடியாக இயங்குவதை " +"ஆதரிக்க எழுதப்பட்டாலும், குறியீடு முழுமையாக நிறுவப்பட்டதாகக் கருதி எழுதப்படுவது இன்னும் " +"பொதுவானது. ஒரு சிப் காப்பகத்திலிருந்து மென்பொருளை இயக்க முயற்சிப்பதன் மூலம் அந்த " +"அனுமானம் உடைக்கப்படும்போது, தோல்விகள் பெரும்பாலும் தெளிவற்றதாகவும், கண்டறிய கடினமாக " +"இருக்கும் (குறிப்பாக அவை மூன்றாம் தரப்பு நூலகங்களில் நிகழும்போது). இதில் உள்ள சிக்கல்களின் " +"இரண்டு பொதுவான ஆதாரங்கள் என்னவென்றால், ஒரு சிப் காப்பகத்திலிருந்து சி நீட்டிப்புகளை " +"இறக்குமதி செய்வது * சிபிதானால் ஆதரிக்கப்படவில்லை (அவ்வாறு செய்வது எந்த தளத்திலும் மாறும் " +"ஏற்றுதல் இயந்திரங்களால் நேரடியாக ஆதரிக்கப்படவில்லை என்பதால்) மற்றும் ஒரு இயங்கும் போது ZIP " +"காப்பகம் `__ __file__`` பண்புக்கூறு இனி ஒரு சாதாரண கோப்பு முறைமை பாதையை " +"குறிக்கவில்லை, ஆனால் கோப்பு முறைமையில் சிப் காப்பகத்தின் இருப்பிடம் மற்றும் உறவினர் " +"இரண்டையும் உள்ளடக்கிய ஒரு சேர்க்கை பாதைக்கு காப்பகத்திற்குள் உள்ள தொகுதிக்கான பாதை. " +"மென்பொருள் சுருக்கமான வள ஏபிஐகளை உள்நாட்டில் சரியாகப் பயன்படுத்தும்போது கூட, வெளிப்புற " +"கூறுகளுடன் இடைமுகப்படுத்த இன்னும் உண்மையான வட்டு கோப்பின் கிடைக்கும் தன்மை தேவைப்படலாம்." + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" +"மெட்டாக்ளாச்கள், குரங்கிபாட்ச் மற்றும் மெட்டாபாத் இறக்குமதியாளர்களைப் போலவே, இந்த அம்சத்தை " +"நீங்கள் பயன்படுத்திக் கொள்ள வேண்டும் என்று நீங்கள் ஏற்கனவே உறுதியாக தெரியவில்லை என்றால், " +"உங்களுக்கு நிச்சயமாக இது தேவையில்லை. நீங்கள் எப்படியாவது இதைப் பயன்படுத்த முடிவு " +"செய்தால், பல திட்டங்களுக்கு உண்மையான பிழையாக ஏற்றுக்கொள்வதற்கு முன்பு முழுமையாக " +"நிறுவப்பட்ட தொகுப்புடன் மீண்டும் உருவாக்கத் தோல்வி தேவைப்படும் என்பதை அறிந்து கொள்ளுங்கள்." + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "வரலாறு" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "பிப்ரவரி 2013: இந்த விவரக்குறிப்பு மூலம் அங்கீகரிக்கப்பட்டது: PEP: `427`." + +#: ../source/specifications/binary-distribution-format.rst:383 +msgid "" +"February 2021: The rules on escaping in wheel filenames were revised, to " +"bring them into line with what popular tools actually do." +msgstr "" +"பிப்ரவரி 2021: சக்கர கோப்பு பெயர்களில் தப்பிப்பது தொடர்பான விதிகள் திருத்தப்பட்டன, " +"பிரபலமான கருவிகள் உண்மையில் என்ன செய்கின்றன என்பதற்கு ஏற்ப அவற்றைக் கொண்டுவருவதற்காக." + +#: ../source/specifications/binary-distribution-format.rst:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" +"டிசம்பர் 2024: `` ச்கிரிப்ட்கள்` கோப்புறையில் வழக்கமான கோப்புகள் மட்டுமே இருக்க வேண்டும் " +"என்று தெளிவுபடுத்தியது (இந்த கோப்புறையில் சிம்லிங்க்கள் அல்லது துணை அடைவுகளை " +"எதிர்கொள்ளும்போது கருவிகளின் எதிர்பார்க்கப்படும் நடத்தை முறையாக வரையறுக்கப்படவில்லை, எனவே " +"கருவிகளுக்கு இடையில் வேறுபடலாம்)." + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" +"டிசம்பர் 2024: தி: கோப்பு: `.டிச்ட்-இன்ஃபோ/உரிமங்கள்/` அடைவு மூலம் குறிப்பிடப்பட்டது: " +"PEP: `639`." + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" +"சனவரி 2025: அந்த பெயர் மற்றும் பதிப்பை தெளிவுபடுத்தியது `` .dist-info`` மற்றும் " +"`.data`` கோப்பகங்களுக்கு இயல்பாக்கப்பட வேண்டும்." + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "பின் இணைப்பு" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "எடுத்துக்காட்டு urlsafe-base64-NOPAD செயல்படுத்தல் ::" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "எடுத்துக்காட்டு" + +#: ../source/specifications/build-details/index.rst:35 +#, fuzzy +#| msgid "``changelog``" +msgid "Changelog" +msgstr "`` சேஞ்ச்லாக்``" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "விவரக்குறிப்பு" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +#, fuzzy +#| msgid "JSON Schema" +msgid "Schema" +msgstr "சாதொபொகு SCHEMA" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Project" +msgid "*object*" +msgstr "திட்டம்" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Semantic versioning" +msgid "Schema version." +msgstr "சொற்பொருள் பதிப்பு" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "enscons" +msgid "const" +msgstr "என்கான்ச்" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Examples" +msgid "examples" +msgstr "எடுத்துக்காட்டுகள்" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "python" +msgid "bin/python" +msgstr "பைதான்" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "platform tag" +msgid "**platform**" +msgstr "இயங்குதள குறிச்சொல்" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "platform tag" +msgid "System platform string." +msgstr "இயங்குதள குறிச்சொல்" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "linux_x86_64" +msgid "linux-x86\\_64" +msgstr "லினக்ச்_எக்ச் 86_64" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Versions" +msgid "**version**" +msgstr "பதிப்புகள்" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Versioning" +msgid "version\\_info" +msgstr "பதிப்பு" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Release" +msgid "releaselevel" +msgstr "வெளியீடு" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Mercurial" +msgid "serial" +msgstr "மெர்குரியல்" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "**Numbers**" +msgid "*number*" +msgstr "** எண்கள் **" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Additional notes" +msgid "additionalProperties" +msgstr "கூடுதல் குறிப்புகள்" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Implementation Notes" +msgid "**implementation**" +msgstr "செயல்படுத்தல் குறிப்புகள்" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "python" +msgid "cpython" +msgstr "பைதான்" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "abi tag" +msgid "abi" +msgstr "அபி நாள்" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "**Headings**" +msgid "**flags**" +msgstr "** தலைப்புகள் **" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Versions" +msgid "extensions" +msgstr "பதிப்புகள்" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "python" +msgid "libpython" +msgstr "பைதான்" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "``dynamic``" +msgid "dynamic" +msgstr "`` டைனமிக்``" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Building binary extensions" +msgid "link\\_extensions" +msgstr "பைனரி நீட்டிப்புகளை உருவாக்குதல்" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "**Numbers**" +msgid "**headers**" +msgstr "** எண்கள் **" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Arbitrary equality" +msgid "arbitrary\\_data" +msgstr "தன்னிச்சையான ஒரு நிகர்" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "கோர் மேனிலை தரவு விவரக்குறிப்புகள்" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" +"பின்வரும் விவரக்குறிப்பில் வரையறுக்கப்பட்ட புலங்கள் செல்லுபடியாகும், முழுமையானவை மற்றும் " +"மாற்றத்திற்கு உட்பட்டவை என்று கருதப்பட வேண்டும். தேவையான புலங்கள்:" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "`` பெயர்``" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "மற்ற அனைத்து புலங்களும் விருப்பமானவை." + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" +"மெட்டாடேட்டாவிற்கான நிலையான கோப்பு வடிவம் (உள்ளிட்டவை: டாக்: `சக்கரங்கள் <பைனரி-விநியோக " +"வடிவங்கள்>` மற்றும்: டாக்: `நிறுவப்பட்ட திட்டங்கள் <பதிவு-நிறுவப்பட்ட-பேக்கேச்கள்>`) " +"மின்னஞ்சல் தலைப்புகளின் வடிவமைப்பை அடிப்படையாகக் கொண்டது. இருப்பினும், மின்னஞ்சல் வடிவங்கள் " +"பல முறை திருத்தப்பட்டுள்ளன, மேலும் பேக்கேசிங் மெட்டாடேட்டாவுக்கு எந்த மின்னஞ்சல் RFC " +"பொருந்தாது என்பது குறிப்பிடப்படவில்லை. ஒரு துல்லியமான வரையறை இல்லாத நிலையில், " +"நிலையான நூலகம்: மோட்: `பைதான்: மின்னஞ்சல்.பார்சர்` தொகுதி: தரவு:` ~ .பிதான்: மின்னஞ்சல்." + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" +"மேனிலை தரவு ஒரு பைட் ச்ட்ரீமுக்கு சீரியலை செய்யும்போதெல்லாம் (எடுத்துக்காட்டாக, ஒரு " +"கோப்பில் சேமிக்க), யுடிஎஃப் -8 குறியாக்கத்தைப் பயன்படுத்தி சரங்களை வரிசைப்படுத்த வேண்டும்." + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" +"இருப்பினும்: PEP: `566` மெட்டாடேட்டாவை JSON- இணக்கமான அகராதியாக மாற்றுவதற்கான வழியை " +"வரையறுத்தது, இது இன்னும் ஒரு நிலையான பரிமாற்ற வடிவமாக பயன்படுத்தப்படவில்லை. பல " +"ஆண்டுகளாக மதிப்புள்ள தொகுப்புகளுடன் பணிபுரிய கருவிகளின் தேவை ஒரு புதிய வடிவத்திற்கு " +"மாற்றுவது கடினம்." + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" +"* பழைய மெட்டாடேட்டாவை விளக்குதல்:* இல்: PEP: `566`, பிரபலமான வெளியீட்டு கருவிகளால் " +"பயன்படுத்தப்படும் தொடரியல் ஏற்றுக்கொள்ள பதிப்பு விவரக்குறிப்பு புலம் வடிவமைப்பு " +"விவரக்குறிப்பு தளர்த்தப்பட்டது (அதாவது பதிப்பு விவரக்குறிப்புகள் அடைப்புக்குறிகளால் " +"சூழப்பட வேண்டும் என்ற தேவையை அகற்ற). மேனிலை தரவு நுகர்வோர் பதிப்பு 2.1 ஐ விட " +"பெயரளவில் குறைவாக இருக்கும் மேனிலை தரவு கோப்புகளுக்கு கூட மிகவும் தளர்வான வடிவமைப்பு " +"விதிகளைப் பயன்படுத்த விரும்பலாம்." + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "மெட்டாடேட்டா-பதிப்பு" + +#: ../source/specifications/core-metadata.rst:52 +#, fuzzy +#| msgid "" +#| "Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +#| "\"2.1\", \"2.2\", \"2.3\", and \"2.4\"." +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" +"கோப்பு வடிவத்தின் பதிப்பு; சட்ட மதிப்புகள் \"1.0\", \"1.1\", \"1.2\", \"2.1\", " +"\"2.2\", \"2.3\" மற்றும் \"2.4\"." + +#: ../source/specifications/core-metadata.rst:55 +#, fuzzy +#| 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)." +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)." +msgstr "" +"மெட்டாடேட்டாவை உட்கொள்ளும் தானியங்கி கருவிகள் `` மெட்டாடேட்டா_்வெர்சன்`` அவர்கள் ஆதரிக்கும் " +"மிக உயர்ந்த பதிப்பை விட அதிகமாக இருந்தால் எச்சரிக்க வேண்டும், மேலும் அவர்கள் ஆதரிக்கும் " +"மிக உயர்ந்த பதிப்பைக் காட்டிலும் அதிக பெரிய பதிப்பைக் கொண்டிருந்தால் `` " +"மெட்டாடேட்டா_்வெர்சன்` என்றால் தோல்வியடைய வேண்டும் (இதில் விவரிக்கப்பட்டுள்ளபடி: ` பதிப்பு " +"விவரக்குறிப்பு விவரக்குறிப்பு <பதிப்பு-விவரக்குறிப்புகள்> `, முக்கிய பதிப்பு முதல் " +"புள்ளிக்கு முந்தைய மதிப்பு)." + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" +"பரந்த பொருந்தக்கூடிய தன்மைக்கு, தேவையான அனைத்து புலங்களையும் உள்ளடக்கிய மிகக் குறைந்த " +"மேனிலை தரவு பதிப்பைப் பயன்படுத்தி விநியோக மெட்டாடேட்டாவை உருவாக்க பில்ட் கருவிகள் " +"தேர்வு செய்யலாம்." + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "எடுத்துக்காட்டு ::" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "வடிவமைப்பில் கட்டுப்பாடுகள் சேர்க்கப்பட்டன: ref: `பெயர் வடிவம் <பெயர்-வடிவ>`." + +#: ../source/specifications/core-metadata.rst:80 +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 "" +"விநியோகத்தின் பெயர். பெயர் புலம் ஒரு விநியோகத்திற்கான முதன்மை அடையாளங்காட்டியாகும். " +"இது: ref: `பெயர் வடிவமைப்பு விவரக்குறிப்பு <பெயர்-வடிவ>` க்கு இணங்க வேண்டும்." + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" +"ஒப்பீட்டு நோக்கங்களுக்காக, பெயர்கள் இருக்க வேண்டும்: குறிப்பு: `இயல்பாக்கப்பட்ட <பெயர்-" +"இயல்பாக்கம்>` ஒப்பிடுவதற்கு முன்." + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" +"விநியோகத்தின் பதிப்பு எண்ணைக் கொண்ட ஒரு சரம். இந்த புலம்: ref: `பதிப்பு விவரக்குறிப்பு " +"விவரக்குறிப்பு <பதிப்பு-விவரக்குறிப்புகள்>` இல் குறிப்பிடப்பட்டுள்ள வடிவத்தில் இருக்க " +"வேண்டும்." + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "மாறும் (பல பயன்பாடு)" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" +"மற்றொரு கோர் மேனிலை தரவு புலத்தின் பெயரைக் கொண்ட ஒரு சரம். புல பெயர்கள் `` பெயர்``, `` " +"பதிப்பு``, மற்றும் `` மெட்டாடேட்டா-பதிப்பு`` இந்த துறையில் குறிப்பிடப்படாமல் இருக்கலாம்." + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "மூல விநியோகத்தின் மெட்டாடேட்டாவில் காணப்படும்போது, பின்வரும் விதிகள் பொருந்தும்:" + +#: ../source/specifications/core-metadata.rst:120 +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 "" +"ஒரு புலம் * `` டைனமிக்`` எனக் குறிக்கப்படவில்லை என்றால், SDIST இலிருந்து கட்டப்பட்ட எந்த " +"சக்கரத்திலும் புலத்தின் மதிப்பு SDIST இல் உள்ள மதிப்புடன் பொருந்த வேண்டும். புலம் SDIST இல் " +"இல்லை என்றால், `` டைனமிக்`` எனக் குறிக்கப்படவில்லை என்றால், அது சக்கரத்தில் இருக்கக்கூடாது." + +#: ../source/specifications/core-metadata.rst:124 +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 "" +"ஒரு புலம் `` டைனமிக்`` எனக் குறிக்கப்பட்டால், அதில் SDIST இலிருந்து கட்டப்பட்ட சக்கரத்தில் " +"எந்த சரியான மதிப்பும் இருக்கலாம் (இல்லை உட்பட)." + +#: ../source/specifications/core-metadata.rst:127 +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 ஐ விட பழையதாக இருந்தால், எல்லா புலங்களும் `` " +"டைனமிக்`` உடன் குறிப்பிடப்பட்டதைப் போல கருதப்பட வேண்டும் (அதாவது, SDIST இலிருந்து " +"கட்டப்பட்ட சக்கரங்களின் மெட்டாடேட்டாவில் சிறப்பு கட்டுப்பாடுகள் எதுவும் இல்லை)." + +#: ../source/specifications/core-metadata.rst:131 +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 "" +"மூல விநியோகத்தைத் தவிர வேறு எந்த சூழலிலும், `` டைனமிக்`` என்பது தகவல்களுக்கு மட்டுமே, " +"மற்றும் புல மதிப்பு சக்கர உருவாக்கும் நேரத்தில் கணக்கிடப்பட்டதைக் குறிக்கிறது, மேலும் இது " +"SDIST இல் உள்ள மதிப்புக்கு அல்லது பிற சக்கரங்களில் இருக்காது திட்டம்." + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" +"`` டைனமிக்`` இன் சொற்பொருளின் முழு விவரங்கள் இதில் விவரிக்கப்பட்டுள்ளன: PEP: `643`." + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "தளம் (பல பயன்பாடு)" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" +"\"இயக்க முறைமை\" ட்ரோவ் வகைப்படுத்திகளில் பட்டியலிடப்படாத விநியோகத்தால் ஆதரிக்கப்படும் " +"இயக்க முறைமையை விவரிக்கும் ஒரு இயங்குதள விவரக்குறிப்பு. கீழே உள்ள \"வகைப்படுத்தி\" ஐப் " +"பார்க்கவும்." + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "எடுத்துக்காட்டுகள் ::" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "ஆதரவு-தளம் (பல பயன்பாடு)" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" +"பி.கே.சி-இன்ஃபோ கோப்பைக் கொண்ட பைனரி விநியோகங்கள் பைனரி வழங்கல் தொகுக்கப்பட்ட OS மற்றும் " +"சிபியு ஐக் குறிப்பிட அவற்றின் மெட்டாடேட்டாவில் ஆதரவு-தளம் புலத்தைப் பயன்படுத்தும். " +"ஆதரிக்கப்பட்ட-தளம் புலத்தின் சொற்பொருள் இந்த PEP இல் குறிப்பிடப்படவில்லை." + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "வழங்கல் என்ன செய்கிறது என்பதற்கான ஒரு வரி சுருக்கம்." + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "இந்த புலம் அதற்கு பதிலாக செய்தி உடலில் குறிப்பிடப்படலாம்." + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" +"பல பத்திகளுக்கு இயங்கக்கூடிய விநியோகத்தின் நீண்ட விளக்கம். மெட்டாடேட்டாவைக் கையாளும் " +"மென்பொருள் இந்தத் துறைக்கு எந்த அதிகபட்ச அளவையும் கருதக்கூடாது, இருப்பினும் மக்கள் தங்கள் " +"அறிவுறுத்தல் கையேட்டை விளக்கமாக சேர்க்கக்கூடாது." + +#: ../source/specifications/core-metadata.rst:217 +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 "" +"இந்த புலத்தின் உள்ளடக்கங்களை மறுசீரமைப்பு மார்க்அப் [1] _ ஐப் பயன்படுத்தி எழுதலாம். " +"மெட்டாடேட்டாவுடன் பணிபுரியும் திட்டங்களுக்கு, மார்க்அப்பை ஆதரிப்பது விருப்பமானது; நிரல்கள் " +"புலத்தின் உள்ளடக்கங்களையும் காண்பிக்க முடியும். இதன் பொருள் ஆசிரியர்கள் அவர்கள் பயன்படுத்தும் " +"மார்க்அப்பில் பழமைவாதமாக இருக்க வேண்டும்." + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" +"RFC 822 வடிவமைப்பைப் பொறுத்து உள்தள்ளலுடன் வெற்று கோடுகள் மற்றும் கோடுகளை ஆதரிக்க, " +"எந்தவொரு சி.ஆர்.எல்.எஃப் எழுத்தும் 7 இடைவெளிகளால் பின்னொட்டு செய்யப்பட வேண்டும், அதைத் " +"தொடர்ந்து குழாய் (\"|\") கரி. இதன் விளைவாக, விளக்க புலம் ஒரு மடிந்த புலத்தில் " +"குறியாக்கம் செய்யப்படுகிறது, இது RFC822 பாகுபடுத்தி [2] _ ஆல் விளக்கப்படலாம்." + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" +"இந்த குறியாக்கம் ஒரு சி.ஆர்.எல்.எஃப் இன் எந்தவொரு நிகழ்வுகளும் 7 இடைவெளிகளும் ஒரு பைப் " +"கரி ஒரு சி.ஆர்.எல்.எஃப் மூலம் மாற்றப்பட வேண்டும், இது ஒரு ஆர்.எஃப்.சி 822 ரீடரைப் " +"பயன்படுத்தி புலம் வெளிவரும் போது." + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" +"மாற்றாக, விநியோகத்தின் விளக்கம் அதற்கு பதிலாக செய்தி உடலில் வழங்கப்படலாம் (அதாவது, " +"தலைப்புகளைப் பின்பற்றி முற்றிலும் வெற்று வரிக்குப் பிறகு, உள்தள்ளல் அல்லது பிற சிறப்பு " +"வடிவங்கள் தேவையில்லை)." + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "விளக்கம்-உள்ளடக்க வகை" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" +"விநியோகத்தின் விளக்கத்தில் பயன்படுத்தப்படும் மார்க்அப் தொடரியல் (ஏதேனும் இருந்தால்) " +"குறிப்பிடும் ஒரு சரம், இதனால் கருவிகள் புத்திசாலித்தனமாக விளக்கத்தை வழங்க முடியும்." + +#: ../source/specifications/core-metadata.rst:260 +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 எளிய உரையில் விளக்கங்களை ஆதரித்தது மற்றும் `மறுசீரமைப்பு (ஓய்வு) " +"` _, " +"மற்றும் உஉகுமொ இல் ஓய்வெடுக்க முடியும். இருப்பினும், விநியோக ஆசிரியர்கள் விளக்கத்தை " +"`மார்க் பேரூர் ` _ (: rfc: " +"`7763`) இல் எழுதுவது பொதுவானது, ஏனெனில் பல குறியீடு ஓச்டிங் தளங்கள் மார்க் பேரூர் " +"வாசிப்புகளை வழங்குகின்றன விளக்கத்திற்கான கோப்பை மீண்டும் பயன்படுத்தும். பைபி வடிவமைப்பை " +"அடையாளம் காணவில்லை, எனவே விளக்கத்தை சரியாக வழங்க முடியவில்லை. இதன் விளைவாக பைபியில் " +"பல தொகுப்புகள் மோசமாக வழங்கப்பட்ட விளக்கங்களுடன் மார்க் பேரூர் எளிய உரையாகவோ அல்லது " +"மோசமாகவோ இருக்கும்போது, ஓய்வாக வழங்க முயற்சிக்கப்பட்டது. இந்த புலம் விநியோக எழுத்தாளரின் " +"விளக்கத்தின் வடிவமைப்பைக் குறிப்பிட அனுமதிக்கிறது, பைபி மற்றும் பிற கருவிகளுக்கான மார்க் " +"பேரூர் மற்றும் பிற வடிவங்களை வழங்குவதற்கான வாய்ப்பைத் திறக்கிறது." + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" +"இந்த புலத்தின் வடிவம் http இல் உள்ள `` உள்ளடக்க-வகை` தலைப்பு (அதாவது: `rfc 1341 " +"` `_) . சுருக்கமாக, " +"இதன் பொருள் இது ஒரு `` வகை/துணை வகை`` பகுதியைக் கொண்டுள்ளது, பின்னர் அது விருப்பமாக " +"பல அளவுருக்களைக் கொண்டிருக்கலாம்:" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "வடிவம் ::" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "`` வகை/துணை வகை`` பகுதியில் சில சட்ட மதிப்புகள் மட்டுமே உள்ளன:" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "`` உரை/வெற்று``" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "`` உரை/x-rst``" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "`` உரை/மார்க் டவுன்``" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" +"விளக்கத்தின் எழுத்துக்குறி குறியாக்கத்தைக் குறிப்பிட `` சார்செட்`` அளவுருவைப் " +"பயன்படுத்தலாம். ஒரே சட்ட மதிப்பு `` UTF-8``. விடுபட்டால், அது `` utf-8`` என்று " +"கருதப்படுகிறது." + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" +"பிற அளவுருக்கள் தேர்ந்தெடுக்கப்பட்ட துணை வகைக்கு குறிப்பிட்டதாக இருக்கலாம். " +"எடுத்துக்காட்டாக, `` மார்க் டவுன்` துணை வகைக்கு, பயன்பாட்டில் உள்ள மார்க் டவுனின் " +"மாறுபாட்டைக் குறிப்பிட அனுமதிக்கும் ஒரு விருப்ப `` மாறுபாடு`` அளவுரு உள்ளது " +"(இயல்புநிலைகள் குறிப்பிடப்படாவிட்டால் `` சி.எஃப்.எம்`` க்கு). தற்போது, இரண்டு வகைகள் " +"அங்கீகரிக்கப்பட்டுள்ளன:" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "`` Gfm`` க்கு: RFC: `Github-சுவை மார்க் பேரூர் <7764#பிரிவு -3.2>`" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "`` காமன்மார்க்``` க்கு: ஆர்.எஃப்.சி: `காமன்மார்க் <7764#பிரிவு -3.5>`" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" +"ஒரு `` விளக்கம்-உள்ளடக்க வகை`` குறிப்பிடப்படவில்லை என்றால், விண்ணப்பங்கள் அதை `` உரை/எக்ச்-" +"ஆர்எச்டி என வழங்க முயற்சிக்க வேண்டும்; charset = utf-8`` மற்றும் `` உரை/வெற்று`` இது " +"செல்லுபடியாகாது என்றால் மீண்டும் விழுங்கள்." + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" +"ஒரு `` விளக்கம்-உள்ளடக்க வகை`` அங்கீகரிக்கப்படாத மதிப்பு என்றால், கருதப்பட்ட உள்ளடக்க வகை " +"`` உரை/வெற்று`` (பைபி அடையாளம் காணப்படாத மதிப்பைக் கொண்ட எதையும் நிராகரிக்கும் " +"என்றாலும்)." + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" +"`` விளக்கம்-உள்ளடக்க வகை`` `` உரை/மார்க் டவுன்`` மற்றும் `` மாறுபாடு`` என்பது " +"குறிப்பிடப்படவில்லை அல்லது அங்கீகரிக்கப்படாத மதிப்புக்கு அமைக்கப்பட்டால், கருதப்பட்ட `` " +"மாறுபாடு`` ." + +#: ../source/specifications/core-metadata.rst:329 +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 "" +"ஆகவே, மேலே உள்ள கடைசி எடுத்துக்காட்டுக்கு, `` சர்செட்`` இயல்புநிலை `` utf-8`` மற்றும் " +"`` மாறுபாடு`` இயல்புநிலை `` gfm`` க்கு இயல்புநிலையாகிறது, இதனால் அது அதற்கு முன் " +"எடுத்துக்காட்டுக்கு சமம்." + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "முக்கிய வார்த்தைகள்" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" +"ஒரு பெரிய பட்டியலில் விநியோகத்தைத் தேட உதவுவதற்கு காற்புள்ளிகளால் பிரிக்கப்பட்ட கூடுதல் " +"முக்கிய வார்த்தைகளின் பட்டியல்." + +#: ../source/specifications/core-metadata.rst:351 +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 "" +"விவரக்குறிப்பு முன்னர் இடைவெளிகளால் பிரிக்கப்பட்ட முக்கிய வார்த்தைகளைக் காட்டியது, ஆனால் " +"தொலைதூரங்கள் மற்றும் செட்டுப்டூல்கள் அதை காற்புள்ளியுடன் செயல்படுத்தின. இந்த கருவிகள் பல " +"ஆண்டுகளாக மிகவும் பரவலாகப் பயன்படுத்தப்படுகின்றன, எனவே உண்மையான தரத்துடன் பொருந்தக்கூடிய " +"விவரக்குறிப்பைப் புதுப்பிப்பது எளிதாக இருந்தது." + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "நூலாசிரியர்" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" +"ஆசிரியரின் பெயரைக் கொண்ட ஒரு சரம் குறைந்தபட்சம்; கூடுதல் தொடர்பு செய்தி வழங்கப்படலாம்." + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "ஆசிரியர்-கடந்த காலம்" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" +"ஆசிரியரின் மின்னஞ்சல் முகவரியைக் கொண்ட ஒரு சரம். இது ஒரு RFC-822 `` என்பதற்கான சட்ட " +"படிவங்களில் ஒரு பெயர் மற்றும் மின்னஞ்சல் முகவரியைக் கொண்டிருக்கலாம்: `` தலைப்பு." + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" +"RFC-822 க்கு, இந்த துறையில் பல கமாவால் பிரிக்கப்பட்ட மின்னஞ்சல் முகவரிகள் இருக்கலாம் ::" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "பராமரிப்பாளர்" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" +"பராமரிப்பாளரின் பெயரைக் கொண்ட ஒரு சரம் குறைந்தபட்சம்; கூடுதல் தொடர்பு செய்தி வழங்கப்படலாம்." + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" +"அசல் எழுத்தாளரைத் தவிர வேறு ஒருவரால் ஒரு திட்டம் பராமரிக்கப்படும்போது இந்த புலம் " +"பயன்படுத்தப்பட வேண்டும் என்பதை நினைவில் கொள்க: இது `` எழுத்தாளர்`` க்கு ஒத்ததாக இருந்தால் " +"அது தவிர்க்கப்பட வேண்டும்." + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "பராமரிப்பாளர்-எமெயில்" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" +"பராமரிப்பாளரின் மின்னஞ்சல் முகவரியைக் கொண்ட ஒரு சரம். இது ஒரு RFC-822 `` என்பதற்கான " +"சட்ட படிவங்களில் ஒரு பெயர் மற்றும் மின்னஞ்சல் முகவரியைக் கொண்டிருக்கலாம்: `` தலைப்பு." + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" +"அசல் எழுத்தாளரைத் தவிர வேறு ஒருவரால் ஒரு திட்டம் பராமரிக்கப்படும்போது இந்த புலம் " +"பயன்படுத்தப்பட வேண்டும் என்பதை நினைவில் கொள்க: இது `` ஆசிரியர்-எமெயில்`` க்கு ஒத்ததாக " +"இருந்தால் அது தவிர்க்கப்பட வேண்டும்." + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "உரிமம்" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "`` உரிம-வெளிப்பாடு`` க்கு ஆதரவாக." + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" +"மேனிலை தரவு 2.4 இன் படி, `` உரிமம்`` மற்றும் `` உரிமம்-வெளிப்பாடு`` இருவழி. இரண்டும் " +"குறிப்பிடப்பட்டால், மேனிலை தரவு பாகுபடுத்தும் கருவிகள் `` உரிமம்`` ஐ புறக்கணிக்கும், " +"மேலும் பதிவேற்றங்களை PYPI நிராகரிக்கும். `PEP 639 ____ ஐப் பார்க்கவும்." + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" +"\"உரிமம்\" ட்ரோவ் வகைப்படுத்திகளிடமிருந்து உரிமம் இல்லாத விநியோகத்தை உள்ளடக்கிய உரிமத்தை " +"குறிக்கும் உரை. காண்க: குறிப்பு: `\" வகைப்படுத்தி \"<மெட்டாடேட்டா-கிளாசிஃபையர்>` கீழே. " +"உரிமத்தின் ஒரு குறிப்பிட்ட பதிப்பைக் குறிப்பிடவும் இந்த புலம் பயன்படுத்தப்படலாம், இது `` " +"வகைப்படுத்தி`` புலம் வழியாக பெயரிடப்பட்டது, அல்லது அத்தகைய உரிமத்திற்கு மாறுபாடு " +"அல்லது விதிவிலக்கைக் குறிக்கலாம்." + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "உரிம-வெளிப்பாடு" + +#: ../source/specifications/core-metadata.rst:482 +#, fuzzy +#| msgid "" +#| "Text string that is a valid SPDX license expression as defined " +#| "in :pep:`639`. Tools SHOULD validate and perform case normalization of " +#| "the expression." +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" +"வரையறுக்கப்பட்டுள்ளபடி செல்லுபடியாகும் SPDX உரிம வெளிப்பாடு உரை சரம்: PEP: `639`. " +"கருவிகள் வெளிப்பாட்டின் வழக்கு இயல்பாக்கலை சரிபார்க்க வேண்டும் மற்றும் செய்ய வேண்டும்." + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "உரிம-கோப்பு (பல பயன்பாடு)" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" +"ஒவ்வொரு நுழைவும் உரிமம் தொடர்பான கோப்பின் பாதையின் சரம் பிரதிநிதித்துவமாகும். திட்ட மூல " +"மரத்திற்குள் இந்த பாதை அமைந்துள்ளது, இது திட்ட ரூட் கோப்பகத்துடன் ஒப்பிடும்போது. " +"விவரங்களுக்கு காண்க: PEP: `639`." + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "வகைப்படுத்தி (பல பயன்பாடு)" + +#: ../source/specifications/core-metadata.rst:532 +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`, மற்றும் பைதான் தொகுப்பு குறியீடு` " +"தற்போது வரையறுக்கப்பட்ட வகைப்படுத்திகள் __ __." + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" +"`` உரிமம் :: `` வகைப்படுத்துபவர்களின் பயன்பாடு மேனிலை தரவு 2.4 இல் நீக்கப்பட்டது, அதற்கு " +"பதிலாக `` உரிம-வெளிப்பாடு` ஐப் பயன்படுத்தவும். `PEP 639 ` _ ஐப் பார்க்கவும்." + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "இந்த புலத்தை ஒரு அரைக்காற்புள்ளிக்குப் பிறகு சுற்றுச்சூழல் குறிப்பான் பின்பற்றலாம்." + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "தேவைப்படும் (பல பயன்பாடு)" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" +"பிரபலமான வெளியீட்டு கருவிகளால் பயன்படுத்தப்படும் தொடரியல் ஏற்றுக்கொள்ள புல வடிவமைப்பு " +"விவரக்குறிப்பு தளர்த்தப்பட்டது." + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" +"ஒவ்வொரு நுழைவுக்கும் இந்த விநியோகத்தால் தேவைப்படும் வேறு சில தொலைதூர திட்டங்களுக்கு " +"பெயரிடும் சரம் உள்ளது." + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "ஒரு தேவை சரத்தின் வடிவம் ஒன்று முதல் நான்கு பகுதிகளைக் கொண்டுள்ளது:" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "ஒரு திட்ட பெயர், `` பெயர்: `` புலம் போன்ற அதே வடிவத்தில். ஒரே கட்டாய பகுதி." + +#: ../source/specifications/core-metadata.rst:567 +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 "" +"'கூடுதல்' பெயர்களின் கமாவால் பிரிக்கப்பட்ட பட்டியல். இவை தேவையான திட்டத்தால் " +"வரையறுக்கப்படுகின்றன, கூடுதல் சார்புகள் தேவைப்படக்கூடிய குறிப்பிட்ட அம்சங்களைக் " +"குறிக்கின்றன. `` வழங்கும்-எக்ச்ட்ரா: `` புலத்தால் குறிப்பிடப்பட்ட கட்டுப்பாடுகளுக்கு பெயர்கள் " +"இணங்க வேண்டும்." + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" +"ஒரு பதிப்பு விவரக்குறிப்பு. வடிவமைப்பை பாகுபடுத்தும் கருவிகள் இதைச் சுற்றியுள்ள விருப்ப " +"அடைப்புக்குறிப்புகளை ஏற்க வேண்டும், ஆனால் அதை உருவாக்கும் கருவிகள் அடைப்புக்குறிகளைப் " +"பயன்படுத்தக்கூடாது." + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" +"அரைக்காற்புள்ளிக்குப் பிறகு ஒரு சுற்றுச்சூழல் குறிப்பான். இதன் பொருள் குறிப்பிட்ட " +"நிபந்தனைகளில் மட்டுமே தேவை தேவைப்படுகிறது." + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "காண்க: PEP: `508` அனுமதிக்கப்பட்ட வடிவமைப்பின் முழு விவரங்களுக்கு." + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" +"திட்ட பெயர்கள் `பைதான் தொகுப்பு குறியீட்டு`_ இல் காணப்படும் பெயர்களுடன் ஒத்திருக்க வேண்டும்." + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" +"பதிப்பு விவரக்குறிப்புகள் விவரிக்கப்பட்டுள்ள விதிகளைப் பின்பற்ற வேண்டும்: DOC: `பதிப்பு-" +"விவரிப்பாளர்கள்`." + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" +"இந்த புலம் வழங்கல் பொருந்தக்கூடிய பைதான் பதிப்பை (களை) குறிப்பிடுகிறது. நிறுவ வேண்டிய " +"திட்டத்தின் எந்த பதிப்பை எடுக்கும்போது நிறுவல் கருவிகள் இதைப் பார்க்கலாம்." + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "மதிப்பு குறிப்பிடப்பட்ட வடிவத்தில் இருக்க வேண்டும்: DOC: `பதிப்பு-விவரிப்பாளர்கள்`." + +#: ../source/specifications/core-metadata.rst:606 +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 ` " +"பின்னர் இது பைதான் <3.6 இல் நிறுவுவதைத் தடுக்கலாம் ::" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "இந்த புலத்தை சுற்றுச்சூழல் குறிப்பானைப் பின்பற்ற முடியாது." + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "தேவை-எக்ச்டெர்னல் (பல பயன்பாடு)" + +#: ../source/specifications/core-metadata.rst:623 +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 "" +"ஒவ்வொரு நுழைவுக்கும் வழங்கல் பயன்படுத்தப்பட வேண்டிய அமைப்பில் சில சார்புநிலையை விவரிக்கும் " +"ஒரு சரம் உள்ளது. இந்த புலம் கீழ்நிலை திட்ட பராமரிப்பாளர்களுக்கு ஒரு குறிப்பாக " +"செயல்படுவதை நோக்கமாகக் கொண்டுள்ளது, மேலும் `` தொலைதூரங்கள்` விநியோகத்திற்கு அர்த்தமுள்ள " +"சொற்பொழிவுகள் இல்லை." + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" +"ஒரு தேவை சரத்தின் வடிவம் வெளிப்புற சார்புநிலையின் பெயர், விருப்பமாக அடைப்புக்குறிக்குள் " +"ஒரு பதிப்பு அறிவிப்பு." + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" +"அவை பைதான் அல்லாத மென்பொருள் வெளியீடுகளைக் குறிப்பிடுவதால், இந்த புலத்திற்கான பதிப்பு " +"எண்கள் ** அல்ல ** இல் குறிப்பிடப்பட்டுள்ள வடிவமைப்பிற்கு இணங்க தேவையில்லை: re: `பதிப்பு " +"விவரக்குறிப்பு விவரக்குறிப்பு <பதிப்பு-விவரக்குறிப்புகள்>`: அவை பதிப்பிற்கு ஒத்ததாக " +"இருக்க வேண்டும் வெளிப்புற சார்பு பயன்படுத்தும் திட்டம்." + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "பயன்படுத்த வேண்டிய சரங்களில் குறிப்பிட்ட விதி எதுவும் இல்லை என்பதைக் கவனியுங்கள்." + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "PROJECT-URL (பல பயன்பாடு)" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" +"திட்டத்திற்கான உலாவக்கூடிய முகவரி மற்றும் அதற்கான சிட்டை கொண்ட ஒரு சரம், கமாவால் " +"பிரிக்கப்பட்டுள்ளது." + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "சிட்டை இலவச உரை 32 எழுத்துகளுக்கு வரையறுக்கப்பட்டுள்ளது." + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" +"தொடங்கி: PEP: `753`, திட்ட மேனிலை தரவு நுகர்வோர் (பைதான் தொகுப்பு குறியீட்டு போன்றவை)" +"\" நன்கு அறியப்பட்ட \"லேபிள்களைக் கண்டறிய ஒரு நிலையான இயல்பாக்கம் செயல்முறையைப் " +"பயன்படுத்தலாம், பின்னர் மனித நுகர்வுக்காக வழங்கப்படும்போது சிறப்பு விளக்கக்காட்சிகள் " +"வழங்கப்படலாம். காண்க: ref: `நன்கு அறியப்பட்ட-திட்ட-urls`." + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "வழங்குகிறது-எக்ச்ட்ரா (பல பயன்பாடு)" + +#: ../source/specifications/core-metadata.rst:677 +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` தடைசெய்யப்பட்ட செல்லுபடியாகும் மதிப்புகள் தெளிவற்றதாக இருக்க வேண்டும் " +"(அதாவது இயல்பாக்கம் தேவையில்லை). பழைய மேனிலை தரவு பதிப்புகளுக்கு, மதிப்பு " +"கட்டுப்பாடுகள் `` பெயர்: `` மற்றும் இயல்பாக்குதல் விதிகள் அறிமுகப்படுத்தப்பட்டன." + +#: ../source/specifications/core-metadata.rst:682 +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/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" +"விருப்ப நற்பொருத்தம் கோரப்பட்டுள்ளதா என்பதைப் பற்றி சார்புநிலையை நிபந்தனை செய்ய குறிப்பிட்ட " +"பெயர் பயன்படுத்தப்படலாம்." + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" +"இரண்டு அம்ச பெயர்கள் `` சோதனை`` மற்றும் `டாக்`` முறையே தானியங்கி சோதனைகளை " +"இயக்குவதற்கும் ஆவணங்களை உருவாக்குவதற்கும் தேவையான சார்புகளுக்கு ஒதுக்கப்பட்டுள்ளன." + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" +"`` வழங்கும்-எக்ச்ட்ரா: `` எந்தவொரு `` தேவைப்படும்-டிச்ட்: `` இல் குறிப்பிடாமல் " +"குறிப்பிடுவது சட்டபூர்வமானது." + +#: ../source/specifications/core-metadata.rst:715 +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 "" +"பழைய மேனிலை தரவு பதிப்புகளுக்கான தரவை எழுதும்போது, `` பெயருக்குப் பயன்படுத்தப்படும் " +"அதே விதிகளைப் பின்பற்றி பெயர்கள் இயல்பாக்கப்பட வேண்டும்: `` ஒப்பீடுகளைச் செய்யும்போது புலம். " +"இரண்டு `` வழங்கும்-எக்ச்ட்ரா: `` இயல்பாக்கப்பட்ட பின்னர் உள்ளீடுகள் மோதினால் மெட்டாடேட்டாவை " +"எழுதும் கருவிகள் பிழையை உயர்த்த வேண்டும்." + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" +"பழைய மேனிலை தரவு பதிப்புகளுக்கான தரவைப் படிக்கும்போது, புதிய மேனிலை தரவு " +"பதிப்புகளின் கீழ் இந்த புலத்திற்கான மதிப்புகள் செல்லாது என்பதை கருவிகள் எச்சரிக்க வேண்டும். " +"`` பெயருக்கான விதிகளைப் பின்பற்றி ஒரு மதிப்பு செல்லாது என்றால்: `` எந்தவொரு முக்கிய " +"மேனிலை தரவு பதிப்பிலும், பயனருக்கு எச்சரிக்கை செய்யப்பட வேண்டும் மற்றும் தெளிவற்ற " +"தன்மையைத் தவிர்க்க மதிப்பு புறக்கணிக்கப்பட வேண்டும். பழைய மேனிலை தரவு பதிப்புகளுக்கு " +"தவறான பெயரைப் படிக்கும்போது பிழையை உயர்த்த கருவிகள் தேர்வு செய்யலாம்." + +#: ../source/specifications/core-metadata.rst:730 +#, fuzzy +#| msgid "Supported-Platform (multiple use)" +msgid "Import-Name (multiple use)" +msgstr "ஆதரவு-தளம் (பல பயன்பாடு)" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +#, fuzzy +#| msgid "Supported-Platform (multiple use)" +msgid "Import-Namespace (multiple use)" +msgstr "ஆதரவு-தளம் (பல பயன்பாடு)" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "அரிதாகவே பயன்படுத்தப்படும் புலங்கள்" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" +"இந்த பிரிவில் உள்ள புலங்கள் தற்போது அரிதாகவே பயன்படுத்தப்படுகின்றன, ஏனெனில் அவற்றின் " +"வடிவமைப்பு லினக்ச் தொகுப்பு மேலாண்மை அமைப்புகளில் ஒப்பிடக்கூடிய வழிமுறைகளால் " +"ஈர்க்கப்பட்டது, மேலும் `பைபி <போன்ற திறந்த குறியீட்டு சேவையகத்தின் சூழலில் கருவிகள் அவற்றை " +"எவ்வாறு விளக்க வேண்டும் என்பது தெளிவாகத் தெரியவில்லை https://pypi.org> ____." + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" +"இதன் விளைவாக, பிரபலமான நிறுவல் கருவிகள் அவற்றை முற்றிலுமாக புறக்கணிக்கின்றன, இதன் " +"பொருள் தொகுப்பு வெளியீட்டாளர்கள் அவற்றை சரியான முறையில் அமைக்க சிறிய ஊக்கத்தொகை இல்லை. " +"இருப்பினும், அவை மேனிலை தரவு விவரக்குறிப்பில் தக்கவைக்கப்பட்டுள்ளன, ஏனெனில் அவை செய்தி " +"நோக்கங்களுக்காக இன்னும் பயனுள்ளதாக இருக்கும், மேலும் அவை ஒரு தொகுக்கப்பட்ட தொகுப்பு " +"களஞ்சியத்துடன் இணைந்து அவற்றின் முதலில் நோக்கம் கொண்ட நோக்கத்திற்காக பயன்படுத்தப்படலாம்." + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "வழங்கும்-டீச்ட் (பல பயன்பாடு)" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" +"ஒவ்வொரு நுழைவுக்கும் இந்த விநியோகத்திற்குள் இருக்கும் ஒரு டிச்டிடில்ச் திட்டத்திற்கு " +"பெயரிடும் சரம் உள்ளது. இந்த புலம் * `` பெயர்`` புலத்தில் அடையாளம் காணப்பட்ட திட்டத்தை " +"சேர்க்க வேண்டும், அதைத் தொடர்ந்து பதிப்பு: பெயர் (பதிப்பு)." + +#: ../source/specifications/core-metadata.rst:852 +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 "" +"ஒரு வழங்கல் கூடுதல் பெயர்களை வழங்கக்கூடும், எ.கா. பல திட்டங்கள் ஒன்றாக தொகுக்கப்பட்டுள்ளன " +"என்பதைக் குறிக்க. உதாரணமாக, `` சோட்பி`` திட்டத்தின் மூல விநியோகங்கள் வரலாற்று ரீதியாக " +"`` பரிவர்த்தனை`` திட்டத்தை உள்ளடக்கியுள்ளன, இது இப்போது ஒரு தனி விநியோகமாக " +"கிடைக்கிறது. அத்தகைய மூல விநியோகத்தை நிறுவுவது `` சோட் பி`` மற்றும் `` பரிவர்த்தனை` " +"ஆகிய இரண்டிற்கும் தேவைகளை நிறைவு செய்கிறது." + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" +"ஒரு வழங்கல் ஒரு \"மெய்நிகர்\" திட்ட பெயரையும் வழங்கக்கூடும், இது தனித்தனியாக " +"விநியோகிக்கப்பட்ட எந்தவொரு திட்டத்திற்கும் பொருந்தாது: பல திட்டங்களில் ஒன்றால் வழங்கக்கூடிய " +"ஒரு சுருக்க திறனைக் குறிக்க அத்தகைய பெயர் பயன்படுத்தப்படலாம். எ.கா., பல திட்டங்கள் " +"கொடுக்கப்பட்ட ORM ஆல் பயன்படுத்த RDBMS பிணைப்புகளை வழங்கக்கூடும்: ஒவ்வொரு திட்டமும் இது " +"`` ORM-பிணைப்புகளை` வழங்குகிறது என்று அறிவிக்கலாம், மற்ற திட்டங்கள் அவற்றில் " +"பெரும்பாலானவற்றில் நிறுவப்பட்டிருப்பதை மட்டுமே சார்ந்து இருக்க அனுமதிக்கிறது." + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" +"ஒரு பதிப்பு அறிவிப்பு வழங்கப்படலாம் மற்றும் விவரிக்கப்பட்டுள்ள விதிகளைப் பின்பற்ற வேண்டும்: " +"DOC: `பதிப்பு-விவரக்குறிப்புகள்`. எதுவும் குறிப்பிடப்படாவிட்டால் விநியோகத்தின் பதிப்பு " +"எண் குறிக்கப்படும்." + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "வழக்கற்றுப் போகும் (பல பயன்பாடு)" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" +"ஒவ்வொரு நுழைவுக்கும் ஒரு டிச்டிடில்ச் திட்டத்தின் விநியோகத்தை விவரிக்கும் ஒரு சரம் உள்ளது, " +"இது இந்த வழங்கல் வழக்கற்றுப் போகிறது, அதாவது இரண்டு திட்டங்களும் ஒரே நேரத்தில் " +"நிறுவப்படக்கூடாது." + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" +"பதிப்பு அறிவிப்புகள் வழங்கப்படலாம். பதிப்பு எண்கள் குறிப்பிடப்பட்ட வடிவத்தில் இருக்க " +"வேண்டும்: DOC: `பதிப்பு-விவரிப்பாளர்கள்`." + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" +"திட்டத்தின் பெயர் மாற்றங்கள் இருந்தால் இந்த துறையின் மிகவும் பொதுவான பயன்பாடு, எ.கா. " +"கோர்கன் 2.3 முறுக்கு பைதான் 1.0 க்குள் நுழைகிறது. நீங்கள் முறுக்கு பைதானை நிறுவும்போது, " +"கோர்கன் விநியோகத்தை அகற்ற வேண்டும்." + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "நீக்கப்பட்ட புலங்கள்" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" +"நீக்கப்பட்ட புலங்கள் தவிர்க்கப்பட வேண்டும், ஆனால் அவை செல்லுபடியாகும் மேனிலை தரவு புலங்கள். " +"கோர் மேனிலை தரவு தரநிலையின் எதிர்கால பதிப்புகளில் அவை அகற்றப்படலாம் (அந்த நேரத்தில் அவை " +"அகற்றப்படுவதற்கு முன்னர் மேனிலை தரவு பதிப்பைக் குறிப்பிடும் கோப்புகளில் மட்டுமே " +"செல்லுபடியாகும்). நீக்கப்பட்ட புலங்கள் பயன்படுத்தப்படும்போது கருவிகள் பயனர்களை எச்சரிக்க " +"வேண்டும்." + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "முகப்பு பக்கம்" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" +"ஒன்றுக்கு: PEP: `753`, பயன்படுத்தவும்: Ref:` கோர்-மெட்டாடேட்டா-திட்ட-உர்எல்` அதற்கு " +"பதிலாக." + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "விநியோகத்தின் முகப்பு பக்கத்திற்கான முகவரி ஐக் கொண்ட ஒரு சரம்." + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "பதிவிறக்க-உல்ல்" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "விநியோகத்தின் இந்த பதிப்பை பதிவிறக்கம் செய்யக்கூடிய முகவரி ஐக் கொண்ட ஒரு சரம். ." + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "தேவை" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "`` தேவை-டிச்ட்`` க்கு ஆதரவாக" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" +"ஒவ்வொரு நுழைவுக்கும் இந்த தொகுப்பால் தேவைப்படும் வேறு சில தொகுதி அல்லது தொகுப்பை " +"விவரிக்கும் ஒரு சரம் உள்ளது." + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" +"ஒரு தேவை சரத்தின் வடிவம் `` இறக்குமதி`` அறிக்கையுடன் பயன்படுத்தக்கூடிய ஒரு தொகுதி " +"அல்லது தொகுப்பு பெயருக்கு ஒத்ததாகும், இது விருப்பப்படி அடைப்புக்குறிக்குள் ஒரு பதிப்பு " +"அறிவிப்பைப் பின்பற்றுகிறது." + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" +"ஒரு பதிப்பு அறிவிப்பு என்பது நிபந்தனை ஆபரேட்டர்கள் மற்றும் பதிப்பு எண்களின் தொடர் ஆகும், " +"இது காற்புள்ளிகளால் பிரிக்கப்பட்டுள்ளது. நிபந்தனை ஆபரேட்டர்கள் \"<\", \">\" ', \"<=\", " +"\"> =\", \"==\", மற்றும் \"! =\" ஆகியவற்றில் ஒன்றாக இருக்க வேண்டும். பதிப்பு எண்கள் `` " +"distutils.version.strictversion` வகுப்பு: இரண்டு அல்லது மூன்று புள்ளி-பிரிக்கப்பட்ட " +"எண் கூறுகள், 'A' அல்லது என்ற எழுத்தை உள்ளடக்கிய ஒரு விருப்பமான \"முன் வெளியீட்டு\" " +"குறிச்சொல்லுடன் ஏற்றுக்கொள்ளப்பட்ட வடிவத்தில் இருக்க வேண்டும் 'பி' அதைத் தொடர்ந்து ஒரு எண். " +"எடுத்துக்காட்டு பதிப்பு எண்கள் \"1.0\", \"2.3A2\", \"1.3.99\"," + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" +"எந்தவொரு நிபந்தனை ஆபரேட்டர்களும் குறிப்பிடப்படலாம், எ.கா. \"> 1.0,! = 1.3.4, <2.0\" " +"என்ற சரம் ஒரு சட்ட பதிப்பு அறிவிப்பாகும்." + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" +"பின்வரும் அனைத்தும் சாத்தியமான தேவை சரங்கள்: \"RFC822\", \"Zlib (> = 1.1.4)\", " +"\"ZOPE\"." + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" +"என்ன சரங்களை பயன்படுத்த வேண்டும் என்பதற்கான நியமன பட்டியல் எதுவும் இல்லை; பைதான் சமூகம் " +"அதன் சொந்த தரங்களைத் தேர்வுசெய்ய உள்ளது." + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "வழங்குகிறது" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "`` வழங்கும்-டிச்ட்`` க்கு ஆதரவாக" + +#: ../source/specifications/core-metadata.rst:999 +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 "" +"ஒவ்வொரு உள்ளீட்டிலும் ஒரு தொகுப்பு அல்லது தொகுதியை விவரிக்கும் ஒரு சரம் உள்ளது, அது " +"நிறுவப்பட்டவுடன் இந்த தொகுப்பு வழங்கப்படும். இந்த சரங்கள் தேவைகள் புலங்களில் " +"பயன்படுத்தப்படும்வற்றுடன் பொருந்த வேண்டும். ஒரு பதிப்பு அறிவிப்பு வழங்கப்படலாம் (ஒப்பீட்டு " +"ஆபரேட்டர் இல்லாமல்); எதுவும் குறிப்பிடப்படவில்லை என்றால் தொகுப்பின் பதிப்பு எண் " +"குறிக்கப்படும்." + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "வழக்கற்றுப்போன" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "`` வழக்கற்றுப் போய்விடும்-டிச்ட்`` க்கு ஆதரவாக" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" +"ஒவ்வொரு உள்ளீட்டிலும் இந்த தொகுப்பு வழக்கற்றுப் போன ஒரு தொகுப்பு அல்லது தொகுதியை " +"விவரிக்கும் ஒரு சரம் உள்ளது, அதாவது இரண்டு தொகுப்புகளும் ஒரே நேரத்தில் " +"நிறுவப்படக்கூடாது. பதிப்பு அறிவிப்புகள் வழங்கப்படலாம்." + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" +"இந்த புலத்தின் மிகவும் பொதுவான பயன்பாடு ஒரு தொகுப்பு பெயர் மாற்றங்கள் இருந்தால், எ.கா. " +"கோர்கன் 2.3 முறுக்கு பைதான் 1.0 க்குள் நுழைகிறது. நீங்கள் முறுக்கு பைதானை நிறுவும்போது, " +"கோர்கன் தொகுப்பு அகற்றப்பட வேண்டும்." + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "மார்ச் 2001: கோர் மேனிலை தரவு 1.0 மூலம் அங்கீகரிக்கப்பட்டது: PEP: `241`." + +#: ../source/specifications/core-metadata.rst:1039 +#, fuzzy +#| msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`:" +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "ஏப்ரல் 2003: கோர் மேனிலை தரவு 1.1 மூலம் அங்கீகரிக்கப்பட்டது: PEP: `314`:" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "பிப்ரவரி 2010: கோர் மேனிலை தரவு 1.2 மூலம் அங்கீகரிக்கப்பட்டது: PEP: `345`." + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "பிப்ரவரி 2018: கோர் மேனிலை தரவு 2.1 மூலம் அங்கீகரிக்கப்பட்டது: PEP: `566`." + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "`` விளக்கம்-உள்ளடக்க-வகை`` மற்றும் `` வழங்குகிறது-எக்ச்ட்ரா``." + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "மெட்டாடேட்டாவை சாதொபொகு ஆக மாற்றுவதற்கான நியமன முறை சேர்க்கப்பட்டது." + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "`` பெயர்` `புலத்தின் இலக்கணத்தை கட்டுப்படுத்தியது." + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "அக்டோபர் 2020: கோர் மேனிலை தரவு 2.2 மூலம் அங்கீகரிக்கப்பட்டது: PEP: `643`." + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "`` டைனமிக்`` புலம் சேர்க்கப்பட்டது." + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "மார்ச் 2022: கோர் மேனிலை தரவு 2.3 மூலம் அங்கீகரிக்கப்பட்டது: PEP: `685`." + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "கூடுதல் பெயர்கள் இயல்பாக்கப்பட வேண்டும்." + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "ஆகச்ட் 2024: கோர் மேனிலை தரவு 2.4 மூலம் அங்கீகரிக்கப்பட்டது: PEP: `639`." + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "`` உரிம-வெளிப்பாடு`` புலத்தை சேர்த்தது." + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "`` உரிம-கோப்பு`` புலத்தை சேர்த்தது." + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +#, fuzzy +#| msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "அக்டோபர் 2020: கோர் மேனிலை தரவு 2.2 மூலம் அங்கீகரிக்கப்பட்டது: PEP: `643`." + +#: ../source/specifications/core-metadata.rst:1068 +#, fuzzy +#| msgid "Added the ``Dynamic`` field." +msgid "Added the ``Import-Name`` field." +msgstr "`` டைனமிக்`` புலம் சேர்க்கப்பட்டது." + +#: ../source/specifications/core-metadata.rst:1069 +#, fuzzy +#| msgid "Added the ``Dynamic`` field." +msgid "Added the ``Import-Namespace`` field." +msgstr "`` டைனமிக்`` புலம் சேர்க்கப்பட்டது." + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "மறுசீரமைக்கப்பட்ட டெக்ச்ட் மார்க்அப்: https://docutils.sourceforge.io/" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "RFC 822 நீண்ட தலைப்பு புலங்கள் :: RFC: `822#பிரிவு -3.1.1`" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "சார்பு குழுக்கள்" + +#: ../source/specifications/dependency-groups.rst:7 +#, fuzzy +#| msgid "" +#| "This specification defines Dependency Groups, a mechanism for storing " +#| "package requirements in ``pyproject.toml`` files such that they are not " +#| "included in project metadata when it is built." +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" +"இந்த விவரக்குறிப்பு சார்பு குழுக்களை வரையறுக்கிறது, இது தொகுப்பு தேவைகளை `` " +"pyproject.toml`` கோப்புகளில் சேமிப்பதற்கான ஒரு வழிமுறையாகும், அவை கட்டமைக்கப்பட்டால் " +"திட்ட மெட்டாடேட்டாவில் சேர்க்கப்படாதவை." + +#: ../source/specifications/dependency-groups.rst:11 +#, fuzzy +#| msgid "" +#| "Dependency Groups are suitable for internal development use-cases like " +#| "linting and testing, as well as for projects which are not built for " +#| "distribution, like collections of related scripts." +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" +"சார்பு குழுக்கள் லின்டிங் மற்றும் சோதனை போன்ற உள் மேம்பாட்டு பயன்பாட்டு-வழக்குகளுக்கு " +"ஏற்றவை, அத்துடன் தொடர்புடைய ச்கிரிப்ட்களின் சேகரிப்புகள் போன்ற விநியோகத்திற்காக கட்டப்படாத " +"திட்டங்களுக்கும் பொருத்தமானவை." + +#: ../source/specifications/dependency-groups.rst:15 +#, fuzzy +#| msgid "" +#| "Fundamentally, Dependency Groups should be thought of as being a " +#| "standardized subset of the capabilities of ``requirements.txt`` files " +#| "(which are ``pip``-specific)." +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" +"அடிப்படையில், சார்பு குழுக்கள் `` தேவைகள். Txt`` கோப்புகளின் திறன்களின் தரப்படுத்தப்பட்ட " +"துணைக்குழு என்று கருதப்பட வேண்டும் (அவை `` பிப்`-குறிப்பிட்டவை)." + +#: ../source/specifications/dependency-groups.rst:25 +#, fuzzy +#| msgid "This is a simple table which shows a ``test`` group::" +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "இது ஒரு எளிய அட்டவணை, இது `` சோதனை`` குழுவைக் காட்டுகிறது ::" + +#: ../source/specifications/dependency-groups.rst:31 +#, fuzzy +#| msgid "and a similar table which defines ``test`` and ``coverage`` groups::" +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "`` சோதனை`` மற்றும் `` கவரேச்`` குழுக்களை வரையறுக்கும் ஒத்த அட்டவணை ::" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "`` [சார்பு-குழுக்கள்] `` அட்டவணை" + +#: ../source/specifications/dependency-groups.rst:41 +#, fuzzy +#| msgid "" +#| "Dependency Groups are defined as a table in ``pyproject.toml`` named " +#| "``dependency-groups``. The ``dependency-groups`` table contains an " +#| "arbitrary number of user-defined keys, each of which has, as its value, a " +#| "list of requirements." +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" +"சார்பு குழுக்கள் `` pyproject.toml`` இல் `` சார்பு-குழுக்கள்`` என்ற அட்டவணையாக " +"வரையறுக்கப்படுகின்றன. `` சார்பு-குழுக்கள்` அட்டவணையில் தன்னிச்சையான எண்ணிக்கையிலான பயனர் " +"வரையறுக்கப்பட்ட விசைகள் உள்ளன, அவை ஒவ்வொன்றும் அதன் மதிப்பாக, தேவைகளின் பட்டியலைக் " +"கொண்டுள்ளன." + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" +"`` [சார்பு-குழுக்கள்] `` விசைகள், சில சமயங்களில் \"குழு பெயர்கள்\" என்றும் அழைக்கப்பட " +"வேண்டும்: குறிப்பு: `செல்லுபடியாகும் இயல்பாக்கப்படாத பெயர்கள் <பெயர்-வடிவ>`. சார்பு " +"குழுக்களைக் கையாளும் கருவிகள் கட்டாயம்: குறிப்பு: `இயல்பாக்குதல் <பெயர்-இயல்பாக்கம்>` " +"ஒப்பீடுகளுக்கு முன் இந்த பெயர்கள்." + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" +"அசல், இயல்பாக்கப்படாத பெயரை பயனர்களுக்கு வழங்க கருவிகள் விரும்ப வேண்டும், மேலும் " +"இயல்பாக்கத்திற்குப் பிறகு நகல் பெயர்கள் கண்டறியப்பட்டால், கருவிகள் பிழையை வெளியிட வேண்டும்." + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" +"தேவை பட்டியல்கள், `` [சார்பு-குழுக்கள்] `` இல் உள்ள மதிப்புகள் சரங்கள், அட்டவணைகள் " +"(பைத்தானில் `டிக்ட்``) அல்லது சரங்கள் மற்றும் அட்டவணைகளின் கலவையைக் கொண்டிருக்கலாம். சரங்கள் " +"செல்லுபடியாகும்: ref: `சார்பு குறிப்பான்கள் <சார்பு-விவரக்குறிப்புகள்>`, மற்றும் " +"அட்டவணைகள் சரியான சார்பு குழு அடங்கும்." + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "சார்பு குழு அடங்கும்" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "ஒரு சார்பு குழுவில் தற்போதைய குழுவில் மற்றொரு சார்பு குழு அடங்கும்." + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" +"அன் என்பது சரியாக ஒரு விசையுடன் கூடிய அட்டவணை, `` \"\" குழுவைச் சேர்க்கவும் \"` `, " +"அதன் மதிப்பு ஒரு சரம், மற்றொரு சார்பு குழுவின் பெயர்." + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" +"பெயரிடப்பட்ட சார்பு குழுவின் உள்ளடக்கங்களுக்கு சமமானதாக அடங்கும், சேர்க்கப்பட்ட இடத்தில் " +"தற்போதைய குழுவில் செருகப்படுகிறது. எடுத்துக்காட்டாக, `` foo = [\"a\", \"b\"] `` " +"ஒரு குழு, மற்றும் `` பார் = [\"சி\", {சேர்க்கவும்-குழு = \"ஃபூ\"}, \"டி\"] `` " +"மற்றொன்று, `` பார்`` `` [\"சி\", \"ஏ\", \"பி\", \"டி\"] `` சார்புடைய குழு " +"சேர்க்கப்படும்போது விரிவாக்கப்படும்போது மதிப்பீடு செய்ய வேண்டும்." + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" +"சார்பு குழு அடங்கும் ஒரே தொகுப்பை பல முறை குறிப்பிடலாம். கருவிகள் தயாரிக்கப்பட்ட " +"பட்டியல் உள்ளடக்கங்களை கைவிடவோ அல்லது மாற்றவோ கூடாது. எடுத்துக்காட்டாக, பின்வரும் " +"அட்டவணையைக் கொடுத்தால்:" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" +"`` அனைத்தையும்`` இன் தீர்க்கப்பட்ட மதிப்பு `` [\"ஃபூ\", \"ஃபூ\", \"ஃபூ> 1.0\", \"ஃபூ " +"<1.0\"] `` ஆக இருக்க வேண்டும். கருவிகள் அத்தகைய பட்டியலை சரியாகக் கையாள வேண்டும், அதே " +"நேரத்தில் வெவ்வேறு பதிப்பு தடைகளுடன் ஒரே தேவையை பல முறை செயலாக்கும்படி கேட்கப்படும் " +"வேறு எந்த வழக்கையும் அவர்கள் கையாளுவார்கள்." + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" +"சார்பு குழு அடங்கும், இது சார்பு குழுவைக் கொண்ட குழுக்கள் அடங்கும், இந்த விசயத்தில் " +"அவற்றில் அடங்கும். சார்பு குழுவில் சுழற்சிகள் இருக்கக்கூடாது, மற்றும் கருவிகள் ஒரு " +"சுழற்சியைக் கண்டறிந்தால் பிழையைப் புகாரளிக்க வேண்டும்." + +#: ../source/specifications/dependency-groups.rst:102 +msgid "Package Building" +msgstr "தொகுப்பு கட்டிடம்" + +#: ../source/specifications/dependency-groups.rst:104 +#, fuzzy +#| msgid "" +#| "Build backends MUST NOT include Dependency Group data in built " +#| "distributions as package metadata. This means that sdist ``PKG-INFO`` and " +#| "wheel ``METADATA`` files should not include referenceable fields " +#| "containing Dependency Groups." +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" +"கட்டிய பின்தளத்தில் கட்டமைக்கப்பட்ட விநியோகங்களில் சார்பு குழு தரவை தொகுப்பு " +"மெட்டாடேட்டாவாக சேர்க்கக்கூடாது. இதன் பொருள் Sdist `` pkg-info`` மற்றும் சக்கரம் `` " +"மெட்டாடேட்டா`` கோப்புகள் சார்பு குழுக்களைக் கொண்ட குறிப்பிடக்கூடிய புலங்களைக் " +"கொண்டிருக்கக்கூடாது." + +#: ../source/specifications/dependency-groups.rst:108 +#, fuzzy +#| msgid "" +#| "It is, however, valid to use Dependency Groups in the evaluation of " +#| "dynamic metadata, and ``pyproject.toml`` files included in sdists will " +#| "still contain ``[dependency-groups]``. However, the table's contents are " +#| "not part of a built package's interfaces." +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" +"எவ்வாறாயினும், மாறும் மெட்டாடேட்டாவின் மதிப்பீட்டில் சார்பு குழுக்களைப் பயன்படுத்துவது " +"செல்லுபடியாகும், மேலும் SDIST களில் சேர்க்கப்பட்டுள்ள `` pyproject.toml`` கோப்புகள் " +"இன்னும் `` [சார்பு-குழுக்கள்] `` கொண்டிருக்கும். இருப்பினும், அட்டவணையின் உள்ளடக்கங்கள் " +"கட்டப்பட்ட தொகுப்பின் இடைமுகங்களின் ஒரு பகுதியாக இல்லை." + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "சார்பு குழுக்கள் மற்றும் கூடுதல் நிறுவுதல்" + +#: ../source/specifications/dependency-groups.rst:116 +#, fuzzy +#| msgid "" +#| "There is no syntax or specification-defined interface for installing or " +#| "referring to Dependency Groups. Tools are expected to provide dedicated " +#| "interfaces for this purpose." +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" +"சார்பு குழுக்களை நிறுவ அல்லது குறிப்பிடுவதற்கு தொடரியல் அல்லது விவரக்குறிப்பு-" +"வரையறுக்கப்பட்ட இடைமுகம் எதுவும் இல்லை. கருவிகள் இந்த நோக்கத்திற்காக பிரத்யேக இடைமுகங்களை " +"வழங்கும் என்று எதிர்பார்க்கப்படுகிறது." + +#: ../source/specifications/dependency-groups.rst:120 +#, fuzzy +#| msgid "" +#| "Tools MAY choose to provide the same or similar interfaces for " +#| "interacting with Dependency Groups as they do for managing extras. Tools " +#| "authors are advised that the specification does not forbid having an " +#| "extra whose name matches a Dependency Group. Separately, users are " +#| "advised to avoid creating Dependency Groups whose names match extras, and " +#| "tools MAY treat such matching as an error." +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" +"கூடுதல்வற்றை நிர்வகிப்பதற்காகச் செய்வதைப் போலவே சார்பு குழுக்களுடன் தொடர்புகொள்வதற்கு அதே " +"அல்லது ஒத்த இடைமுகங்களை வழங்க கருவிகள் தேர்வு செய்யலாம். கருவிகள் ஆசிரியர்கள் " +"அறிவுறுத்தப்படுகிறார்கள், விவரக்குறிப்பைக் கொண்டிருப்பதைத் தடைசெய்யவில்லை, அதன் பெயர் " +"சார்பு குழுவுடன் பொருந்துகிறது. தனித்தனியாக, பயனர்கள் சார்பு குழுக்களை உருவாக்குவதைத் " +"தவிர்க்க அறிவுறுத்தப்படுகிறார்கள், அதன் பெயர்கள் கூடுதல் பொருந்துகின்றன, மேலும் கருவிகள் " +"அத்தகைய பொருத்தத்தை பிழையாகக் கருதலாம்." + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "சரிபார்ப்பு மற்றும் பொருந்தக்கூடிய தன்மை" + +#: ../source/specifications/dependency-groups.rst:130 +#, fuzzy +#| msgid "" +#| "Tools supporting Dependency Groups may want to validate data before using " +#| "it. When implementing such validation, authors should be aware of the " +#| "possibility of future extensions to the specification, so that they do " +#| "not unnecessarily emit errors or warnings." +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" +"சார்பு குழுக்களை ஆதரிக்கும் கருவிகள் தரவைப் பயன்படுத்துவதற்கு முன்பு அதை சரிபார்க்க " +"விரும்பலாம். இத்தகைய சரிபார்ப்பை செயல்படுத்தும்போது, விவரக்குறிப்புக்கு எதிர்கால " +"நீட்டிப்புகளின் சாத்தியக்கூறுகள் குறித்து ஆசிரியர்கள் அறிந்திருக்க வேண்டும், இதனால் அவர்கள் " +"தேவையின்றி பிழைகள் அல்லது எச்சரிக்கைகளை வெளியிடுவதில்லை." + +#: ../source/specifications/dependency-groups.rst:135 +#, fuzzy +#| msgid "" +#| "Tools SHOULD error when evaluating or processing unrecognized data in " +#| "Dependency Groups." +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" +"சார்பு குழுக்களில் அங்கீகரிக்கப்படாத தரவை மதிப்பீடு செய்யும்போது அல்லது செயலாக்கும்போது " +"கருவிகள் பிழையாக இருக்க வேண்டும்." + +#: ../source/specifications/dependency-groups.rst:138 +#, fuzzy +#| msgid "" +#| "Tools SHOULD NOT eagerly validate the contents of *all* Dependency Groups " +#| "unless they have a need to do so." +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" +"கருவிகள் * அனைத்து * சார்பு குழுக்களின் உள்ளடக்கங்களையும் ஆவலுடன் சரிபார்க்கக்கூடாது." + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" +"இதன் பொருள் பின்வரும் தரவின் முன்னிலையில், பெரும்பாலான கருவிகள் `` ஃபூ`` குழுவை " +"பயன்படுத்த அனுமதிக்க வேண்டும், மேலும் `` பார்`` குழு பயன்படுத்தப்பட்டால் மட்டுமே பிழை:" + +#: ../source/specifications/dependency-groups.rst:152 +#, fuzzy +#| msgid "" +#| "There are several known cases of tools which have good cause to be " +#| "stricter. Linters and validators are an example, as their purpose is to " +#| "validate the contents of all Dependency Groups." +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" +"பல அறியப்பட்ட கருவிகள் உள்ளன, அவை கடுமையானதாக இருக்க நல்ல காரணத்தைக் கொண்டுள்ளன. " +"அனைத்து சார்பு குழுக்களின் உள்ளடக்கங்களையும் சரிபார்ப்பதே அவற்றின் நோக்கம் என்பதால், லிண்டர்கள் " +"மற்றும் வாலிடேட்டர்கள் ஒரு எடுத்துக்காட்டு." + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +msgid "Reference Implementation" +msgstr "குறிப்பு செயல்படுத்தல்" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" +"பின்வரும் குறிப்பு செயல்படுத்தல் ஒரு சார்பு குழுவின் உள்ளடக்கங்களை stdout க்கு " +"அச்சிடுகிறது, நியூலைன் பிரிக்கப்பட்டது. எனவே வெளியீடு செல்லுபடியாகும் `` தேவைகள். " +"Txt`` தரவு." + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "அக்டோபர் 2024: இந்த விவரக்குறிப்பு அங்கீகரிக்கப்பட்டது: PEP: `735`." + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "சார்பு குறிப்பான்கள்" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" +"இந்த ஆவணம் முதலில் குறிப்பிடப்பட்டுள்ளபடி சார்பு குறிப்பிட்ட வடிவமைப்பை விவரிக்கிறது: " +"PEP: `508`." + +#: ../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] போன்ற கருவிகளை நிறுவுவதற்கு சரியான " +"தொகுப்பைக் கண்டுபிடிப்பது. சில நேரங்களில் இது மிகவும் தளர்வானது - ஒரு பெயரைக் " +"குறிப்பிடுவது, சில நேரங்களில் மிகவும் குறிப்பிட்டது - நிறுவ ஒரு குறிப்பிட்ட கோப்பைக் " +"குறிப்பிடுகிறது. சில நேரங்களில் சார்புநிலைகள் ஒரு தளத்தில் மட்டுமே பொருத்தமானவை, " +"அல்லது சில பதிப்புகள் மட்டுமே ஏற்றுக்கொள்ளத்தக்கவை, எனவே இந்த நிகழ்வுகள் அனைத்தையும் " +"விவரிக்கும் மொழி அனுமதிக்கிறது." + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" +"வரையறுக்கப்பட்ட மொழி ஒரு சிறிய வரி அடிப்படையிலான வடிவமாகும், இது ஏற்கனவே PIP " +"தேவைகள் கோப்புகளில் பரவலான பயன்பாட்டில் உள்ளது, இருப்பினும் அந்தக் கோப்புகள் அனுமதிக்கும் " +"கட்டளை வரி விருப்பத்தை நாங்கள் குறிப்பிடவில்லை. ஒரு எச்சரிக்கை உள்ளது - முகவரி குறிப்பு " +"படிவம், குறிப்பிடப்பட்டுள்ளது: ref: `பதிப்பு விவரக்குறிப்பு விவரக்குறிப்பு <பதிப்பு " +"-விவரக்குறிப்புகள்>` உண்மையில் PIP இல் செயல்படுத்தப்படவில்லை, ஆனால் PIP இன் தற்போதைய சொந்த " +"வடிவமைப்பைக் காட்டிலும் அந்த வடிவமைப்பைப் பயன்படுத்துகிறோம்." + +#: ../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 "குறைந்தபட்ச முகவரி அடிப்படையிலான தேடல் ::" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "கருத்துக்கள்" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" +"சார்பு விவரக்குறிப்பு எப்போதும் விநியோக பெயரைக் குறிப்பிடுகிறது. இது கூடுதல் அம்சங்களை " +"உள்ளடக்கியது, இது விருப்ப அம்சங்களை செயல்படுத்த பெயரிடப்பட்ட விநியோகத்தின் சார்புகளை " +"விரிவுபடுத்துகிறது. நிறுவப்பட்ட பதிப்பை பதிப்பு வரம்புகளைப் பயன்படுத்தி கட்டுப்படுத்தலாம் " +"அல்லது நிறுவ ஒரு குறிப்பிட்ட கலைப்பொருளுக்கு முகவரி ஐ வழங்கலாம். இறுதியாக " +"சுற்றுச்சூழல் குறிப்பான்களைப் பயன்படுத்தி சார்புநிலையை நிபந்தனைக்குட்படுத்தலாம்." + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "இலக்கணம்" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" +"நாங்கள் முதலில் இலக்கணத்தை சுருக்கமாக மூடி, பின்னர் ஒவ்வொரு பிரிவின் சொற்பொருளிலும் " +"துளைக்கிறோம்." + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" +"விநியோக விவரக்குறிப்பு ASCII உரையில் எழுதப்பட்டுள்ளது. ஒரு துல்லியமான இலக்கணத்தை வழங்க " +"நாங்கள் ஒரு வோக்கோசு [#பார்ச்லி] _ இலக்கணத்தைப் பயன்படுத்துகிறோம். விவரங்கள் ஒரு பெரிய " +"அமைப்பில் உட்பொதிக்கப்படும் என்று எதிர்பார்க்கப்படுகிறது, இது கருத்துகள், தொடர்ச்சியான பல " +"வரி உதவி அல்லது இதுபோன்ற பிற நற்பொருத்தங்கள் போன்ற ஃப்ரேமிங்கை வழங்குகிறது." + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" +"இந்த ஆவணத்தின் முடிவில் பயனுள்ள பாகுபடுத்தும் மரத்தை உருவாக்குவதற்கான சிறுகுறிப்புகள் " +"உட்பட முழு இலக்கணம் சேர்க்கப்பட்டுள்ளது." + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" +"பதிப்புகள்: ref: `பதிப்பு விவரக்குறிப்பு விவரக்குறிப்பு <பதிப்பு-விவரக்குறிப்புகள்>` " +"விதிகளின் படி குறிப்பிடப்படலாம். ." + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" +"சுற்றுச்சூழல் குறிப்பான்கள் ஒரு விவரக்குறிப்பை உருவாக்க சில சூழல்களில் மட்டுமே " +"நடைமுறைக்கு வர அனுமதிக்கின்றன ::" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" +"ஒரு விநியோகத்தின் விருப்ப கூறுகள் கூடுதல் புலத்தைப் பயன்படுத்தி குறிப்பிடப்படலாம் ::" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" +"வரி உடைக்கும் இடைவெளி பெரும்பாலும் சொற்பொருள் பொருள் இல்லாமல் விருப்பமானது. ஒரே " +"விதிவிலக்கு ஒரு முகவரி தேவையின் முடிவைக் கண்டறிவது." + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "பெயர்கள்" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" +"பைதான் விநியோக பெயர்கள் தற்போது வரையறுக்கப்பட்டுள்ளன: PEP: `345`. விநியோகங்களுக்கான " +"முதன்மை அடையாளங்காட்டியாக பெயர்கள் செயல்படுகின்றன. அவை அனைத்து சார்பு " +"விவரக்குறிப்புகளிலும் உள்ளன, மேலும் அவை சொந்தமாக ஒரு விவரக்குறிப்பாக இருக்க " +"போதுமானவை. இருப்பினும், பைபி பெயர்களில் கடுமையான கட்டுப்பாடுகளை வைக்கிறது - அவை ஒரு " +"வழக்கு உணர்வற்ற ரெசெக்சுடன் பொருந்த வேண்டும் அல்லது அவை ஏற்றுக்கொள்ளப்படாது. அதன்படி, இந்த " +"ஆவணத்தில் அந்த ரீசெக்சுக்கு அடையாளங்காட்டிகளுக்கான ஏற்றுக்கொள்ளக்கூடிய மதிப்புகளை நாங்கள் " +"கட்டுப்படுத்துகிறோம். பெயரின் முழு மறுவரையறை எதிர்கால மேனிலை தரவு பெப்பில் " +"நடைபெறலாம். ரீசெக்ச் (RE.IGNORECASE உடன் இயக்கவும்) ::" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "கூடுதல்" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" +"கூடுதல் என்பது ஒரு விநியோகத்தின் விருப்ப பகுதியாகும். விநியோகங்கள் அவர்கள் விரும்பும் பல " +"கூடுதல்வற்றைக் குறிப்பிடலாம், மேலும் ஒவ்வொரு கூடுதல் கூடுதல் விநியோகத்தின் கூடுதல் " +"சார்புகளை அறிவிப்பதில் ** ** கூடுதல் சார்பு விவரக்குறிப்பில் பயன்படுத்தப்படும்போது. " +"உதாரணமாக ::" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" +"எக்ச்ட்ராச் யூனியன் அவர்கள் இணைக்கப்பட்டுள்ள விநியோகத்தின் சார்புகளுடன் அவர்கள் வரையறுக்கும் " +"சார்புகளில். மேலே உள்ள எடுத்துக்காட்டு கோரிக்கைகள் நிறுவப்படும், மேலும் கோரிக்கைகள் சொந்த " +"சார்புகளையும், \"பாதுகாப்பு\" கூடுதல் கோரிக்கைகளில் பட்டியலிடப்பட்டுள்ள எந்தவொரு " +"சார்புகளும்." + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "பல கூடுதல் பட்டியலிடப்பட்டால், அனைத்து சார்புகளும் ஒன்றிணைக்கப்படுகின்றன." + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "பதிப்புகள்" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" +"பதிப்பு எண்கள் மற்றும் பதிப்பு ஒப்பீடுகள் இரண்டிலும் மேலும் விவரங்களுக்கு `பதிப்பு " +"விவரக்குறிப்பு விவரக்குறிப்பு <பதிப்பு-விவரக்குறிப்புகள்>` ஐப் பார்க்கவும். பதிப்பு " +"விவரக்குறிப்புகள் பயன்படுத்தக்கூடிய விநியோகத்தின் பதிப்புகளைக் கட்டுப்படுத்துகின்றன. அவை " +"முகவரி வழியாக இல்லாமல், பெயரால் பார்க்கப்படும் விநியோகங்களுக்கு மட்டுமே பொருந்தும். " +"பதிப்பு ஒப்பீடு குறிப்பான்கள் அம்சத்திலும் பயன்படுத்தப்படுகிறது. ஒரு பதிப்பைச் சுற்றியுள்ள " +"விருப்ப அடைப்புக்குறிகள் பொருந்தக்கூடிய தன்மைக்கு உள்ளன: PEP: `345` ஆனால் " +"உருவாக்கப்படக்கூடாது, ஏற்றுக்கொள்ளப்பட்டது." + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "சுற்றுச்சூழல் குறிப்பான்கள்" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" +"சுற்றுச்சூழல் குறிப்பான்கள் ஒரு சார்பு விவரக்குறிப்பை சார்புநிலை எப்போது பயன்படுத்த " +"வேண்டும் என்பதை விவரிக்கும் ஒரு விதியை வழங்க அனுமதிக்கின்றன. உதாரணமாக, ஆர்க்பர்ச் " +"தேவைப்படும் ஒரு தொகுப்பைக் கவனியுங்கள். பைத்தானில் 2.7 ஆர்க்பர்ச் எப்போதும் இருக்கும். பழைய " +"பைதான் பதிப்புகளில் இது ஒரு சார்புநிலையாக நிறுவப்பட வேண்டும். இதை அவ்வாறு " +"வெளிப்படுத்தலாம் ::" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" +"ஒரு மார்க்கர் வெளிப்பாடு உண்மை அல்லது பொய்யை மதிப்பிடுகிறது. இது பொய்யை " +"மதிப்பிடும்போது, சார்பு விவரக்குறிப்பு புறக்கணிக்கப்பட வேண்டும்." + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" +"மார்க்கர் மொழி பைத்தானால் ஈர்க்கப்பட்டு, பாதுகாப்பு பாதிப்பாக மாறக்கூடிய தன்னிச்சையான " +"குறியீட்டை இயக்காமல் பாதுகாப்பாக மதிப்பீடு செய்யும் திறனுக்காக தேர்ந்தெடுக்கப்படுகிறது. " +"குறிப்பான்கள் முதலில் தரப்படுத்தப்பட்டன: PEP: `345`. இந்த ஆவணம் விவரிக்கப்பட்ட வடிவமைப்பில் " +"காணப்பட்ட சில சிக்கல்களை சரிசெய்கிறது: PEP: `426`." + +#: ../source/specifications/dependency-specifiers.rst:199 +#, fuzzy +#| msgid "" +#| "Comparisons in marker expressions are typed by the comparison operator. " +#| "The operators that are not in perform the same " +#| "as they do for strings in Python. The operators use the " +#| "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::" +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" +"மார்க்கர் வெளிப்பாடுகளில் ஒப்பீடுகள் ஒப்பீட்டு ஆபரேட்டரால் தட்டச்சு செய்கின்றன. " +"இல் இல்லாத <மார்க்கர்_ஓபி> ஆபரேட்டர்கள் பைத்தானில் உள்ள சரங்களுக்கு அவர்கள் செய்வதைப் போலவே " +"செயல்படுகிறார்கள். ஆபரேட்டர்கள் பதிப்பு ஒப்பீட்டு விதிகளைப் " +"பயன்படுத்துகின்றன: ref: `பதிப்பு விவரக்குறிப்பு விவரக்குறிப்பு <பதிப்பு-" +"விவரக்குறிப்புகள்>` அவை வரையறுக்கப்படும்போது (அதாவது இரு தரப்பினரும் சரியான பதிப்பு " +"விவரக்குறிப்பைக் கொண்டிருக்கும்போது). இந்த விவரக்குறிப்பின் வரையறுக்கப்பட்ட நடத்தை எதுவும் " +"இல்லை என்றால், ஆபரேட்டர் பைத்தானில் இருந்தால், ஆபரேட்டர் மீண்டும் பைதான் நடத்தைக்கு " +"விழுகிறார். இல்லையெனில் பிழை எழுப்பப்பட வேண்டும். எ.கா. பின்வருபவை பிழைகள் ::" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" +"பயனர் வழங்கப்பட்ட மாறிலிகள் எப்போதுமே `` '`` அல்லது `\" \"` `` மேற்கோள் மதிப்பெண்களுடன் " +"சரங்களாக குறியாக்கம் செய்யப்படுகின்றன. பின்வாங்கல் தப்பித்தல் வரையறுக்கப்படவில்லை, ஆனால் " +"தற்போதுள்ள செயலாக்கங்கள் அவற்றை ஆதரிக்கின்றன. அவை இந்த விவரக்குறிப்பில் சேர்க்கப்படவில்லை, " +"ஏனெனில் அவை சிக்கலான தன்மையைச் சேர்க்கின்றன இன்று அவற்றைக் காணக்கூடிய தேவை இல்லை. ASCII- " +"மட்டும்." + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" +"\"OS_NAME\" போன்ற மார்க்கர் இலக்கணத்தில் உள்ள மாறிகள் மதிப்புகளுக்குத் தீர்கின்றன, பைதான் " +"இயக்க நேரத்தில் பார்க்கப்படுகின்றன. \"கூடுதல்\" தவிர அனைத்து மதிப்புகளும் இன்று அனைத்து " +"பைதான் பதிப்புகளிலும் வரையறுக்கப்பட்டுள்ளன - ஒரு மதிப்பு வரையறுக்கப்படாவிட்டால் " +"குறிப்பான்களை செயல்படுத்துவதில் பிழை." + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" +"அறியப்படாத மாறிகள் உண்மை அல்லது பொய்யை மதிப்பிடும் ஒப்பீட்டை விட பிழையை எழுப்ப வேண்டும்." + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" +"கொடுக்கப்பட்ட பைதான் செயல்படுத்தலில் மதிப்பைக் கணக்கிட முடியாத மாறிகள் பதிப்புகளுக்கு `` " +"0`` ஆகவும், மற்ற எல்லா மாறிகளுக்கும் வெற்று சரம் என்றும் மதிப்பீடு செய்ய வேண்டும்." + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" +"\"கூடுதல்\" மாறி சிறப்பு. சக்கரத்தில் கொடுக்கப்பட்ட கூடுதல் விவரக்குறிப்புகள் `` " +"மெட்டாடேட்டா`` கோப்பில் எந்த விவரக்குறிப்புகள் பொருந்தும் என்பதைக் குறிக்க இது சக்கரங்களால் " +"பயன்படுத்தப்படுகிறது, ஆனால் `` மெட்டாடேட்டா`` கோப்பு ஒரு வரைவு பதிப்பை அடிப்படையாகக் " +"கொண்டது என்பதால்: PEP: `426`, இல்லை இதற்கான தற்போதைய விவரக்குறிப்பு. பொருட்படுத்தாமல், " +"இந்த சிறப்பு கையாளுதல் நடைபெறும் ஒரு சூழலுக்கு வெளியே, \"கூடுதல்\" மாறி மற்ற அனைத்து " +"அறியப்படாத மாறிகள் போன்ற பிழையை ஏற்படுத்தும்." + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "மார்க்கர்" + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "பைதான் சமமான" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "வகை" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "மாதிரி மதிப்புகள்" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "`` os_name``" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr ": PY: தரவு: `os.name`" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "`` posix``, `` சாவா``" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "`` sys_platform``" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr ": PY: தரவு: `sys.platform`" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" +"`` லினக்ச்``, `` லினக்ச் 2``, `` டார்வின்``, `` `சாவா 1.8.0_51`` (\" லினக்ச் \"பைதான் " +"3 இலிருந்து மற்றும் பைதான் 2 இலிருந்து\" லினக்ச் 2 \"என்பதை நினைவில் கொள்க)" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "`` இயங்குதள_மச்சின்``" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr ": py: func: `platurm.machine ()`" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "`` x86_64``" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "`` platurm_python_implementation``" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr ":py:func:`platform.python_implementation()`" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "`` Cpython``, `` jython``" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "`` PLATURM_REELEASE``" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr ":py:func:`platform.release()`" + +#: ../source/specifications/dependency-specifiers.rst:271 +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/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "`` இயங்குதள_ அமைப்பு``" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr ": py: func: `platurm.system ()`" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "`` லினக்ச்``, `` விண்டோச்``, `` சாவா``" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "`` PLATER_VERSION``" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr ": py: func: `platurm.version ()`" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" +"``#1 SMP FRI APR 25 13:07:35 EDT 2014` `` `` சாவா ஆட்ச்பாட் (டி.எம்) 64-பிட் சர்வர் " +"வி.எம். 02:18:53 PDT 2015; ரூட்: xnu-2782.40.9 ~ 2/reulation_x86_64``" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "`` python_version``" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "`` '.'" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +#, fuzzy +#| msgid "Version specifiers" +msgid ":ref:`Version `" +msgstr "பதிப்பு விவரக்குறிப்புகள்" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "`` 3.4``, `` 2.7``" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "`` python_full_version``" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr ":py:func:`platform.python_version()`" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "`` 3.4.0``, `` 3.5.0b1``" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "`` செயல்படுத்தல்_பெயர்``" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr ":py:data:`sys.implementation.name `" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "`` cpython``" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "`` செயல்படுத்தல்_்வெர்சன்``" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "கீழே உள்ள வரையறையைக் காண்க" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "`` கூடுதல்``" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "விவரக்குறிப்பை விளக்கும் சூழலால் வரையறுக்கப்படும்போது தவிர பிழை." + +#: ../source/specifications/dependency-specifiers.rst:302 +#, fuzzy +#| msgid "``pyproject.toml``" +msgid "``toml``" +msgstr "`` pyproject.toml``" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +#, fuzzy +#| msgid "``extra``" +msgid "``extras``" +msgstr "`` கூடுதல்``" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +#, fuzzy +#| msgid "``dependencies``" +msgid "``dependency_groups``" +msgstr "`` சார்புகள்``" + +#: ../source/specifications/dependency-specifiers.rst:312 +#, fuzzy +#| msgid "``test``" +msgid "``{\"test\"}``" +msgstr "`` சோதனை``" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" +"`` செயல்படுத்தல்_்வெர்சன்`` மார்க்கர் மாறி இதிலிருந்து பெறப்பட்டது: py: தரவு: " +"`sys.implementation.version `:" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" +"இந்த சுற்றுச்சூழல் குறிப்பான்கள் பிரிவு, ஆரம்பத்தில் வரையறுக்கப்பட்டுள்ளது: PEP: `508`, " +"சுற்றுச்சூழல் குறிப்பான்கள் பிரிவை மீறுகிறது: PEP:` 345`." + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "முழுமையான இலக்கணம்" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "முழுமையான வோக்கோசு இலக்கணம் ::" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "ஒரு சோதனை நிரல் - இலக்கணம் ஒரு சரத்தில் இருந்தால் `` இலக்கணம்``:" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "நவம்பர் 2015: இந்த விவரக்குறிப்பு அங்கீகரிக்கப்பட்டது: PEP: `508`." + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" +"சூலை 2019: `` python_version`` இன் வரையறை `மாற்றப்பட்டது <பைதான்-பதிப்பு-சேஞ்ச்_>` " +"`_` `தளத்திலிருந்து. ) [: 2]) ``, 2 இலக்க பெரிய மற்றும் சிறிய பதிப்புகளுடன் " +"பைத்தானின் எதிர்கால பதிப்புகளுக்கு இடமளிக்க (எ.கா. 3.10). [#future_versions] _" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" +"சூன் 2024: 2022 ஆம் ஆண்டின் பிற்பகுதியிலிருந்து பயன்பாட்டில் உள்ள பைதான் அமலாக்கத்தின் " +"நடத்தையுடன் பொருந்தக்கூடிய, `` பதிப்பு_மனி`` இன் வரையறை மாற்றப்பட்டது." + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" +"PIP, பைதான் தொகுப்புகளுக்கான பரிந்துரைக்கப்பட்ட நிறுவி (http://pip.readthedocs.org/" +"en/stable/)" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "வோக்கோசு பெக் நூலகம். (https://pypi.python.org/pypi/parsly/)" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" +"சுற்றுச்சூழல் மார்க்கர் மாறியின் வரையறையுடன் எதிர்கால பைதான் பதிப்புகள் சிக்கலாக இருக்கலாம் " +"`` பைதான்_்வெர்சன்`` (https://github.com/python/peps/issues/560)" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "நிறுவப்பட்ட விநியோகங்களின் நேரடி முகவரி தோற்றத்தை பதிவு செய்தல்" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" +"இந்த ஆவணம் ஒரு: கோப்பு: ``*. டிச்ட்-இன்ஃபோ`` ஒரு நிறுவப்பட்ட விநியோகத்தின் கோப்பகத்தில் " +"`டைரக்ட்_ஆர்ல்.சோன்` கோப்பைக் குறிப்பிடுகிறது, விநியோகத்தின் நேரடி முகவரி தோற்றத்தை " +"பதிவு செய்ய. ``*.Dist-info`` கோப்பகங்களின் பொதுவான கட்டமைப்பும் பயன்பாடும் இதில் " +"விவரிக்கப்பட்டுள்ளது: ref: `பதிவு-நிறுவப்பட்ட-தொகுப்புகள்`." + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" +"தி: கோப்பு: `direct_url.json` கோப்பு உருவாக்கப்பட வேண்டும்: கோப்பு:`*. டிச்ட்-இன்ஃபோ` " +"கோப்பகத்தை நிறுவிகள் மூலம் நேரடி முகவரி குறிப்பைக் குறிப்பிடும் தேவையிலிருந்து ஒரு " +"விநியோகத்தை நிறுவும் போது (வி.சி.எச் முகவரி உட்பட)." + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" +"வேறு வகை தேவையிலிருந்து (அதாவது பெயர் பிளச் பதிப்பு விவரக்குறிப்பு) ஒரு விநியோகத்தை " +"நிறுவும் போது இந்த கோப்பு உருவாக்கப்படக்கூடாது." + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" +"இந்த சாதொபொகு கோப்பு ஒரு UTF-8 குறியாக்கப்பட்டதாக இருக்க வேண்டும்,: RFC: `8259` " +"இணக்கமான, சீரியலைசேசன்: DOC:` நேரடி-உர்எல்-தரவு-கட்டமைப்பு`." + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" +"கோரப்பட்ட முகவரி இல் கோப்பு: // திட்டம் மற்றும் வி.சி.எச் புதுப்பித்தலைக் கொண்டிருக்கும் " +"உள்ளக கோப்பகத்தை சுட்டிக்காட்டும்போது, நிறுவிகள் எந்த வி.சி.எச் தகவலையும் ஊகிக்க " +"முயற்சிக்கக்கூடாது, எனவே எந்த வி.சி.எச் தொடர்பான தகவல்களையும் வெளியிடக்கூடாது (போன்றவை " +"`VCS_INFO` `) இல்: கோப்பு:` direct_url.json`." + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" +"ஒரு பொதுவான விதியாக, நிறுவிகள் உருவாக்கும் போது கோரப்பட்ட முகவரி இல் வழங்கப்பட்ட " +"தகவல்களை முடிந்தவரை பாதுகாக்க வேண்டும்: கோப்பு: `direct_url.json`. எடுத்துக்காட்டாக " +"பயனர்: கடவுச்சொல் சூழல் மாறிகள் பாதுகாக்கப்பட வேண்டும், மேலும் கோரப்பட்ட முகவரி இல் " +"வழங்கப்பட்ட திருத்தத்தை முடிந்தவரை உண்மையாகவே `` கோரப்பட்ட_ரெவிசன்`` பிரதிபலிக்க " +"வேண்டும். எவ்வாறாயினும், `` கமிட்_ஐடி`` போன்ற துல்லியமான தரவுகளுடன் இந்த செய்தி * " +"செறிவூட்டப்படுகிறது." + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "எடுத்துக்காட்டு பிஐபி கட்டளைகள் மற்றும் அவற்றின் விளைவு டைரக்ட்_ஆர்ல்.சோன்" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "ஒரு `` sydread_url.json`` ஐ உருவாக்கும் கட்டளைகள்:" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "`` பிஐபி நிறுவவும்" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" +"`` பிஐபி நிறுவுதல் -பொருத்தப்பட்ட \"பயன்பாடு @ git+https: //example.com/repo/" +"app.git#subdirectory=setup\" `` (இந்த விசயத்தில், `` url`` உள்ளக கோப்பகமாக " +"இருக்கும் களஞ்சியம் நகலி செய்யப்பட்டுள்ளது, மற்றும் `` dir_info`` `` திருத்தக்கூடியது " +"\": உண்மை`` மற்றும் இல்லை `` vcs_info`` அமைக்கப்படும்)" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "* `` Direct_url.json`` ஐ உருவாக்காத * கட்டளைகள்" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "மார்ச் 2020: இந்த விவரக்குறிப்பு மூலம் அங்கீகரிக்கப்பட்டது: PEP: `610`." + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "நேரடி முகவரி தரவு அமைப்பு" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" +"இந்த ஆவணம் ஒரு JSON-Serializable சுருக்க தரவு கட்டமைப்பைக் குறிப்பிடுகிறது, இது " +"பைதான் திட்டங்களுக்கான முகவரி களைக் குறிக்கும் மற்றும் வி.சி.எச் மூல மரங்கள், உள்ளக மூல " +"மரங்கள், மூல வழங்கல் மற்றும் சக்கரங்கள் போன்ற விநியோக கலைப்பொருட்கள்." + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" +"எழுதும் நேரத்தில், இந்த தரவு கட்டமைப்பின் பகுதிகளை ஒரு முகவரி ஆக எவ்வாறு ஒன்றிணைப்பது " +"என்பது முறையாக குறிப்பிடப்படவில்லை, அவை கருவிகளுக்கு அனுப்பப்படலாம். ஒரு பொதுவான " +"பிரதிநிதித்துவம் PIP முகவரி வடிவம் (`VCS உதவி ` _), பிற " +"எடுத்துக்காட்டுகள்: ref: `பதிப்பு விவரக்குறிப்பு விவரக்குறிப்பு <பதிப்பு-" +"விவரக்குறிப்புகள்>`." + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" +"நேரடி முகவரி தரவு அமைப்பு ஒரு அகராதியாக இருக்க வேண்டும், இதன் படி சாதொபொகு க்கு " +"வரிசைப்படுத்தக்கூடியது: RFC: `8259`." + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +msgstr "" +"அதில் குறைந்தது இரண்டு புலங்கள் இருக்க வேண்டும். முதலாவது `` url``, வகை `` சரம்``. " +"அதன் உள்ளடக்கம் `whatewg முகவரி தரநிலை ` _ இன் படி " +"செல்லுபடியாகும் முகவரி ஆக இருக்க வேண்டும்." + +#: ../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`` ஒரு வி.சி.எச் குறிப்பு என்றால்), `` `url`` என்றால்` `url`` மூல காப்பகம் அல்லது " +"ஒரு சக்கரம்), அல்லது `` dir_info`` (`` url`` என்றால் உள்ளக அடைவு என்றால்). இந்த செய்தி " +"புலங்கள் ஒரு (சாத்தியமான வெற்று) அடக்குமுறையை மதிப்பாக வைத்திருக்கின்றன, கீழே " +"வரையறுக்கப்பட்ட விசைகள் உள்ளன." + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "பாதுகாப்பு பரிசீலனைகள்" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" +"தொடர்ந்து இருக்கும்போது, பாதுகாப்பு காரணங்களுக்காக, `` url`` எந்தவொரு முக்கியமான " +"அங்கீகார தகவல்களையும் அகற்ற வேண்டும்." + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" +"பயனர்: முகவரி இன் கடவுச்சொல் பிரிவு சுற்றுச்சூழல் மாறிகள் கொண்டதாக இருக்கலாம், பின்வரும் " +"வழக்கமான வெளிப்பாட்டுடன் பொருந்துகிறது:" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" +"கூடுதலாக, பயனர்: முகவரி இன் கடவுச்சொல் பிரிவு நன்கு அறியப்பட்ட, பாதுகாப்பு அல்லாத " +"உணர்திறன் கொண்ட சரமாக இருக்கலாம். `` Ssh: // git@gitlab.com/பயனர்/ரெப்போ`` போன்ற " +"முகவரி இன் விசயத்தில் `` கிட்`` ஒரு பொதுவான எடுத்துக்காட்டு." + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "பகஅ முகவரி கள்" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" +"`` Url`` ஒரு வி.சி.எச் களஞ்சியத்தைக் குறிக்கும் போது, `` VCS_INFO`` விசை பின்வரும் " +"விசைகளுடன் அகராதியாக இருக்க வேண்டும்:" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" +"ஒரு `` vcs`` விசை (வகை `` சரம்```) இருக்க வேண்டும், இதில் VC களின் பெயரைக் " +"கொண்டுள்ளது (அதாவது `` git``, `` hg``, `` bzr``, `` svn ``). இந்த விவரக்குறிப்பை " +"திருத்துவதற்கு ஒரு PEP ஐ எழுதுவதன் மூலம் பிற வி.சி.க்கள் பதிவு செய்யப்பட வேண்டும். `` " +"Url`` மதிப்பு தொடர்புடைய VC களுடன் இணக்கமாக இருக்க வேண்டும், எனவே ஒரு நிறுவி பகஅ இன் " +"புதுப்பித்து/பதிவிறக்க கட்டளைக்கு மாற்றப்படாமல் அதை ஒப்படைக்க முடியும்." + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" +"ஒரு `` கமிட்_ஐடி`` விசை (வகை `` சரம்``) இருக்க வேண்டும், இதில் சரியான கமிட்/திருத்த " +"எண்ணை நிறுவ வேண்டும்/நிறுவ வேண்டும். மூலக் குறியீட்டின் மாறாத பதிப்பைக் குறிப்பிடுவதற்கு " +"வி.சி.எச் கமிட்-ஆச் அடிப்படையிலான திருத்த அடையாளங்காட்டிகளை ஆதரித்தால், அத்தகைய கமிட்-" +"ஆச் `` கமிட்_ஐடி`` எனப் பயன்படுத்தப்பட வேண்டும்." + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "காப்பக முகவரி கள்" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" +"`` Url`` ஒரு மூல காப்பகம் அல்லது சக்கரத்தைக் குறிக்கும் போது, `` காப்பகம்_இன்ஃபோ`` விசை " +"பின்வரும் விசைகளுடன் அகராதியாக இருக்க வேண்டும்:" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "இந்த ஆச் பெயர்கள் எப்போதும் சிறிய எழுத்துக்களாக இயல்பாக்கப்பட வேண்டும்." + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" +"எந்த ஆச் வழிமுறையும் மூலம் கிடைக்கும்: PY: MOD: `ஆச்லிப்` (குறிப்பாக ஏதேனும் தேர்ச்சி " +"பெறக்கூடியது: PY: FUNC:` Hashlib.new () `மற்றும் கூடுதல் அளவுருக்கள் தேவையில்லை) " +"ஆசச் அகராதி ஒரு விசையாக பயன்படுத்தப்படலாம் . இருந்து குறைந்தது ஒரு பாதுகாப்பான " +"வழிமுறை: PY: தரவு: `hashlib.algorithms_ugranaled` எப்போதும் சேர்க்கப்பட வேண்டும். " +"எழுதும் நேரத்தில், `` சா 256`` குறிப்பாக பரிந்துரைக்கப்படுகிறது." + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" +"ஒரு நீக்கப்பட்ட `` ஆச்`` விசை (வகை `` சரம்``) பின்னோக்கி பொருந்தக்கூடிய நோக்கங்களுக்காக " +"இருக்கலாம், மதிப்பு `` <ஆச்-அல்காரிதம்> = <எதிர்பார்க்கப்படும்-ஆச்> ``." + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" +"தரவு கட்டமைப்பின் தயாரிப்பாளர்கள் ஒன்று அல்லது பல ஆச்கள் கிடைக்குமா என்பதை `` ஆச்கள்` " +"`விசையை வெளியிட வேண்டும். தயாரிப்பாளர்கள் `` ஆச்`` விசையை அவர்கள் முன்பு செய்த " +"சூழல்களில் தொடர்ந்து வெளியிட வேண்டும், இதனால் இருக்கும் வாடிக்கையாளர்களுக்கு பின்னோக்கி " +"பொருந்தக்கூடிய தன்மையை வைத்திருக்க வேண்டும்." + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" +"`` ஆச்`` மற்றும் `` ஆச்கள்`` விசைகள் இரண்டும் இருக்கும்போது, `` ஆச்` விசையில் " +"குறிப்பிடப்பட்டுள்ள ஆச் `` ஆச்கள்`` அகராதியில் இருக்க வேண்டும், எனவே நுகர்வோர் `` ஆச்களைக் " +"கருத்தில் கொள்ளலாம் `` அது இருந்தால் மட்டுமே முக்கியமானது, இல்லையெனில் `` ஆச்`` க்கு " +"திரும்பவும்." + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "உள்ளக கோப்பகங்கள்" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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/direct-url-data-structure.rst:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" +"`` Url`` ஒரு உள்ளக கோப்பகத்தைக் குறிக்கும் போது, அதற்கு `` கோப்பு`` திட்டத்தைக் " +"கொண்டிருக்க வேண்டும் மற்றும் இணக்கமாக இருக்க வேண்டும்: RFC: `8089`. குறிப்பாக, பாதை " +"கூறு முழுமையானதாக இருக்க வேண்டும். உறவினர் பாதைகளை முழுமையானதாக மாற்றும்போது " +"குறியீட்டு இணைப்புகள் பாதுகாக்கப்பட வேண்டும்." + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "துணை அடைவுகளில் திட்டங்கள்" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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 "`` Pyproject.toml`` அல்லது `` setup.py. `அமைந்துள்ளது." + +#: ../source/specifications/direct-url-data-structure.rst:139 +msgid "Registered VCS" +msgstr "பதிவுசெய்யப்பட்ட வி.சி." + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" +"இந்த பிரிவு பதிவுசெய்யப்பட்ட வி.சி.எச்சை பட்டியலிடுகிறது; விரிவாக்கப்பட்ட, `` vcs``, " +"`` கோரப்பட்ட_ரெவிசன்`` மற்றும் `` vcs_info`` இன் பிற துறைகளை எவ்வாறு பயன்படுத்துவது " +"என்பது பற்றிய வி.சி.எச்-குறிப்பிட்ட தகவல்கள்; மற்றும் சில சந்தர்ப்பங்களில் கூடுதல் வி.சி.எச்-" +"குறிப்பிட்ட புலங்கள். இந்த விவரக்குறிப்பை திருத்துவதற்கு ஒரு PEP ஐ எழுதுவதன் மூலம் " +"அவற்றை பதிவு செய்ய பரிந்துரைக்கப்பட்டாலும் கருவிகள் மற்ற வி.சி.க்களை ஆதரிக்கக்கூடும். `` " +"Vcs`` புலம் கட்டளை பெயராக இருக்க வேண்டும் (கீழ்நிலை). அத்தகைய வி.சி.க்களை ஆதரிக்க " +"தேவையான கூடுதல் புலங்கள் வி.சி.எச் கட்டளை பெயருடன் முன்னொட்டப்பட வேண்டும்." + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "அறிவிலி" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "முகப்பு பக்கம்" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "https://git-scm.com/" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "வி.சி.எச் கட்டளை" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "அறிவிலி" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "`` vcs`` புலம்" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "`` கோரப்பட்டது_ரெவிசன்` புலம்" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "`` கமிட்_ஐடி`` புலம்" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "ஒரு கமிட் ஆச் (40 எக்சாடெசிமல் எழுத்துக்கள் சா 1)." + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" +"கருவிகள் `` கோரப்பட்ட_ரெவிசன்`` ஒரு அறிவிலி ref உடன் ஒத்திருக்கிறதா என்பதை தீர்மானிக்க " +"`` அறிவிலி சோ-ரெஃப்`` மற்றும் `` அறிவிலி சிம்போலிக்-ரெஃப்`` கட்டளைகளைப் பயன்படுத்தலாம். " +"இதையொட்டி, `` refs/tags/`` உடன் ஒரு REF ஒரு குறிச்சொல்லுடன் ஒத்திருக்கிறது, மேலும் " +"ஒரு கிளோனிங் ஒரு கிளைக்கு ஒத்த பிறகு `` refs/ரிமோட்டுகள்/தோற்றம்/`` உடன் தொடங்கும்." + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "மெர்குரியல்" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "https://www.mercurial-scm.org/" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "எச்.சி." + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "ஒரு குறிச்சொல் பெயர், கிளை பெயர், மாற்றங்கள் ஐடி, சுருக்கப்பட்ட மாற்றங்கள் ஐடி." + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "ஒரு மாற்ற ஐடி (40 எக்சாடெசிமல் எழுத்துக்கள்)." + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "கடைவீதி" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "https://www.breezy-vcs.org/" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "பொத்தான்" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "ஒரு குறிச்சொல் பெயர், கிளை பெயர், திருத்த ஐடி." + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "ஒரு திருத்த ஐடி." + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "எச்.வி.என்" + +#: ../source/specifications/direct-url-data-structure.rst:226 +msgid "" +"``requested_revision`` must be compatible with ``svn checkout`` ``--" +"revision`` option. In Subversion, branch or tag is part of ``url``." +msgstr "" +"`` கோரப்பட்ட_ரெவிசன்`` `` எச்.வி.என் புதுப்பிப்பு` `` `--revision`` விருப்பத்துடன் " +"இணக்கமாக இருக்க வேண்டும். கீழ்ப்படிதலில், கிளை அல்லது குறிச்சொல் `` url`` இன் ஒரு " +"பகுதியாகும்." + +#: ../source/specifications/direct-url-data-structure.rst:230 +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:235 +msgid "JSON Schema" +msgstr "சாதொபொகு SCHEMA" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" +"`` Adrent_url.json`` இன் உள்ளடக்கங்களை சரிபார்க்க பின்வரும் சாதொபொகு திட்டத்தைப் " +"பயன்படுத்தலாம்:" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "மூல காப்பகம்:" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "குறிச்சொல் மற்றும் கமிட்-ஆச் உடன் git url:" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "உள்ளக அடைவு:" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "திருத்தக்கூடிய பயன்முறையில் உள்ளக அடைவு:" + +#: ../source/specifications/direct-url-data-structure.rst:294 +msgid "" +"March 2020: This specification was approved through :pep:`610`, defining the " +"``direct_url.json`` metadata file." +msgstr "" +"மார்ச் 2020: இந்த விவரக்குறிப்பு மூலம் அங்கீகரிக்கப்பட்டது: PEP: `610`,` `` " +"direct_url.json`` மேனிலை தரவு கோப்பை வரையறுக்கிறது." + +#: ../source/specifications/direct-url-data-structure.rst:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" +"சனவரி 2023: `` காப்பகம்_இன்ஃபோ.ஆச்கள்` விசையை (`கலந்துரையாடல் <காப்பகம்-இன்ஃபோ-ஆச்கள்_>` " +"_) சேர்த்தது." + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "நுழைவு புள்ளிகள் விவரக்குறிப்பு" + +#: ../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/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`` நுழைவு புள்ளிகளைக் குறிப்பிடலாம், ஒவ்வொன்றும் ஒரு " +"செயல்பாட்டைக் குறிக்கின்றன. * பிஐபி * (அல்லது மற்றொரு கன்சோல்_ச்கிரிப்ட்ச் விழிப்புணர்வு " +"நிறுவி) விநியோகத்தை நிறுவும் போது, இது ஒவ்வொரு நுழைவு புள்ளிக்கும் ஒரு கட்டளை-வரி " +"ரேப்பரை உருவாக்கும்." + +#: ../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 "" +"செருகுநிரல்களை ஏற்ற பயன்பாடுகள் நுழைவு புள்ளிகளைப் பயன்படுத்தலாம்; எ.கா. பைக்மென்ட்ச் " +"(ஒரு தொடரியல் சிறப்பம்சமாக கருவி) தனித்தனியாக நிறுவப்பட்ட தொகுப்புகளிலிருந்து கூடுதல் " +"லெக்சர்கள் மற்றும் பாணிகளைப் பயன்படுத்தலாம். இதைப் பற்றி மேலும் அறிய, காண்க: DOC: `/" +"வழிகாட்டிகள்/உருவாக்குதல் மற்றும் கண்டுபிடித்தல்-பிளகின்ச்`." + +#: ../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 "" +"இயக்க நேரத்தில் படிக்கப்படும் ஒருங்கிணைப்பு புள்ளி மெட்டாடேட்டாவை வழங்க செட்டுப்லூல்களுடன் " +"கட்டப்பட்ட தொகுப்புகளை அனுமதிக்க நுழைவு புள்ளி கோப்பு வடிவம் முதலில் உருவாக்கப்பட்டது: " +"PY: MOD: `INSPROMLIB.Metadata`. இது இப்போது ஒரு PYPA இயங்குதள விவரக்குறிப்பாக " +"வரையறுக்கப்பட்டுள்ளது, வெளியிடுவதற்கு `` setuptools`` தவிர வேறு பல கருவிகளை " +"அனுமதிக்க: py: mod: `importlib.metadata` இணக்கமான நுழைவு புள்ளி மேனிலை தரவு " +"மற்றும் இயக்க நேர நூலகங்கள்: py: mod:` வெளியிடப்பட்ட நுழைவு புள்ளி மெட்டாடேட்டாவைப் " +"படிக்க இறக்குமதி லிப்." + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "தரவு மாதிரி" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" +"கருத்தியல் ரீதியாக, ஒரு நுழைவு புள்ளி மூன்று தேவையான பண்புகளால் வரையறுக்கப்படுகிறது:" + +#: ../source/specifications/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 "" +"** குழு ** ஒரு நுழைவு புள்ளி சொந்தமானது என்பது எந்த வகையான பொருளை வழங்குகிறது " +"என்பதைக் குறிக்கிறது. உதாரணமாக, `` கன்சோல்_ச்கிரிப்ட்ச்`` என்பது ஒரு கட்டளையாகப் " +"பயன்படுத்தக்கூடிய செயல்பாடுகளைக் குறிக்கும் நுழைவு புள்ளிகளுக்கானது, அதே நேரத்தில் `` " +"பைக்மென்ட்ச். நுகர்வோர் பொதுவாக எதிர்பார்த்த இடைமுகத்தை வரையறுக்கிறார்கள். மோதல்களைத் " +"தவிர்ப்பதற்கு, ஒரு புதிய குழுவை வரையறுக்கும் நுகர்வோர் நுகர்வோர் திட்டத்திற்கு சொந்தமான " +"PYPI பெயருடன் தொடங்கி பெயர்களைப் பயன்படுத்த வேண்டும், அதைத் தொடர்ந்து `` .``. குழு " +"பெயர்கள் கடிதங்கள், எண்கள் மற்றும் அடிக்கோடிட்டுக் காட்டங்களின் ஒன்று அல்லது அதற்கு மேற்பட்ட " +"குழுக்களாக இருக்க வேண்டும், அவை புள்ளிகளால் பிரிக்கப்படுகின்றன (regex ``^\\ w+(\\. \\ " +"W+)*$ ``)." + +#: ../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 "" +"** பெயர் ** இந்த நுழைவு புள்ளியை அதன் குழுவிற்குள் அடையாளம் காட்டுகிறது. இதன் " +"துல்லியமான பொருள் நுகர்வோர் வரை. கன்சோல் ச்கிரிப்ட்களைப் பொறுத்தவரை, நுழைவு புள்ளியின் " +"பெயர் அதைத் தொடங்க பயன்படுத்தப்படும் கட்டளை. ஒரு விநியோகத்திற்குள், நுழைவு புள்ளி பெயர்கள் " +"தனித்துவமாக இருக்க வேண்டும். வெவ்வேறு விநியோகங்கள் ஒரே பெயரை வழங்கினால், இதுபோன்ற " +"மோதல்களை எவ்வாறு கையாள்வது என்பதை நுகர்வோர் தீர்மானிக்கிறார். பெயரில் `` = `` தவிர வேறு " +"எந்த எழுத்துக்களும் இருக்கலாம், ஆனால் அது எந்த இடைவெளி எழுத்திலும் தொடங்கவோ முடிவடையவோ " +"முடியாது, அல்லது `` [`` உடன் தொடங்க முடியாது. புதிய நுழைவு புள்ளிகளுக்கு, " +"எழுத்துக்கள், எண்கள், அடிக்கோடிட்டுக் காட்டுதல், புள்ளிகள் மற்றும் கோடுகள் (regex `[\\ w .-]" +"+` `) மட்டுமே பயன்படுத்த பரிந்துரைக்கப்படுகிறது." + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" +"** பொருள் குறிப்பு ** பைதான் பொருளை சுட்டிக்காட்டுகிறது. இது `` இறக்குமதி " +"செய்யக்கூடியது. புள்ளிகள் மற்றும் பெருங்குடல் ஆகியவற்றால் பிரிக்கப்பட்ட ஒவ்வொரு பகுதிகளும் " +"சரியான பைதான் அடையாளங்காட்டியாகும். இது இப்படி பார்க்கப்பட வேண்டும் ::" + +#: ../source/specifications/entry-points.rst:64 +msgid "" +"Some tools call this kind of object reference by itself an 'entry point', " +"for want of a better term, especially where it points to a function to " +"launch a program." +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 "" +"ஒரு விருப்ப சொத்து உள்ளது: ** கூடுதல் ** என்பது நுழைவு புள்ளியை வழங்கும் விநியோகத்தின் " +"விருப்ப அம்சங்களை அடையாளம் காணும் சரங்களின் தொகுப்பாகும். இவை குறிப்பிடப்பட்டால், நுழைவு " +"புள்ளிக்கு அந்த 'கூடுதல்' சார்புநிலைகள் தேவைப்படுகின்றன. மேனிலை தரவு புலத்தைக் காண்க: " +"ref: `Metadata_provides_extra`." + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" +"ஒரு நுழைவு புள்ளிக்கு கூடுதல் பயன்படுத்துவது இனி பரிந்துரைக்கப்படாது. ஏற்கனவே உள்ள " +"விநியோகங்களிலிருந்து அவற்றை பாகுபடுத்த நுகர்வோர் ஆதரிக்க வேண்டும், ஆனால் பின்னர் அவற்றைப் " +"புறக்கணிக்கலாம். புதிய வெளியீட்டு கருவிகள் கூடுதல் குறிப்புகளை ஆதரிக்க தேவையில்லை. " +"கூடுதல் கையாளுதலின் செயல்பாடு 'முட்டை' தொகுப்புகளை நிர்வகிக்கும் செடுப்டூல்சின் " +"மாதிரியுடன் பிணைக்கப்பட்டுள்ளது, ஆனால் பிஐபி மற்றும் மெய்நிகர்இவி போன்ற புதிய கருவிகள் " +"வேறு மாதிரியைப் பயன்படுத்துகின்றன." + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "கோப்பு வடிவம்" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" +"நுழைவு புள்ளிகள் எனப்படும் கோப்பில் வரையறுக்கப்பட்டுள்ளன: கோப்பு: `entry_points.txt` " +"இல்: கோப்பு:`*. டிச்ட்-இன்ஃபோ` விநியோகத்தின் அடைவு. இது விவரிக்கப்பட்டுள்ள கோப்பகமாகும்: " +"குறிப்பு: நிறுவப்பட்ட விநியோகங்களுக்கான `பதிவு-நிறுவப்பட்ட-பேக்கேச்கள்`, மற்றும் இல்: " +"ref:` பைனரி-விநியோக வடிவிலான சக்கரங்களுக்கு. கோப்பு யுடிஎஃப் -8 எழுத்து " +"குறியாக்கத்தைப் பயன்படுத்துகிறது." + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" +"பைதான் படித்தபடி கோப்பு உள்ளடக்கங்கள் ஐ.என்.ஐ வடிவத்தில் உள்ளன: மோட்: `கட்டமைப்பு " +"பார்வையாளர்` தொகுதி. இருப்பினும், கட்டமைப்பாளரின் பெயர்களை இயல்புநிலையாக வழக்கு-" +"உணர்வற்றதாகக் கருதுகிறது, அதேசமயம் நுழைவு புள்ளி பெயர்கள் வழக்கு உணர்திறன் கொண்டவை. ஒரு " +"வழக்கு-உணர்திறன் உள்ளமைவு பாகுபடுத்தி இப்படி செய்யப்படலாம் ::" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" +"மதிப்புகளிலிருந்து பெயர்களை வரையறுக்க நுழைவு புள்ளிகள் கோப்பு எப்போதும் `` = `` " +"பயன்படுத்த வேண்டும் (அதேசமயம் கட்டமைப்பாளர்களும் ``: ``) பயன்படுத்த அனுமதிக்கிறது." + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" +"கட்டமைப்பு கோப்பின் பிரிவுகள் நுழைவு புள்ளி குழுக்களைக் குறிக்கின்றன, பெயர்கள் பெயர்கள், " +"மற்றும் மதிப்புகள் பொருள் குறிப்பு மற்றும் விருப்ப கூடுதல் இரண்டையும் குறியாக்குகின்றன. " +"கூடுதல் பயன்படுத்தப்பட்டால், அவை சதுர அடைப்புக்குறிக்குள் கமாவால் பிரிக்கப்பட்ட பட்டியல்." + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" +"ஒரு மதிப்புக்குள், வாசகர்கள் பெருங்குடலுக்கு முன் அல்லது அதற்குப் பிறகு, பொருள் குறிப்பு " +"மற்றும் இடது சதுர அடைப்புக்குறிக்கு இடையில், கூடுதல் பெயர்களுக்கும் சதுர " +"அடைப்புக்குறிகளுக்கும், அவற்றை வரையறுக்கும் காலன்களுக்கும் இடையில், மற்றும் சரியான " +"சதுரத்திற்குப் பிறகு இடங்களை ஏற்றுக்கொண்டு புறக்கணிக்க வேண்டும் அடைப்புக்குறி. கூடுதல் " +"அம்சங்களுக்கான தொடரியல் முறையாக குறிப்பிடப்பட்டுள்ளது: PEP: `508` (` `கூடுதல்``) " +"மற்றும் குறிப்பிடப்பட்ட மதிப்புகள் மீதான கட்டுப்பாடுகள்: PEP:` 685`. கோப்பை எழுதும் " +"கருவிகளுக்கு, பொருள் குறிப்பு மற்றும் இடது சதுர அடைப்புக்குறிக்கு இடையில் ஒரு இடத்தை " +"செருக மட்டுமே பரிந்துரைக்கப்படுகிறது." + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "ச்கிரிப்டுகளுக்கு பயன்படுத்தவும்" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" +"நுழைவு புள்ளிகளின் இரண்டு குழுக்கள் பேக்கேசிங்கில் சிறப்பு முக்கியத்துவம் வாய்ந்தவை: `` " +"கன்சோல்_ச்கிரிப்ட்ச்`` மற்றும் `` gui_scripts``. இரு குழுக்களிலும், தொகுப்பு நிறுவப்பட்ட " +"பின் கணினி செல்லில் கட்டளையாக நுழைவு புள்ளியின் பெயர் பயன்படுத்தப்பட வேண்டும். பொருள் " +"குறிப்பு ஒரு செயல்பாட்டை சுட்டிக்காட்டுகிறது, இது இந்த கட்டளை இயக்கப்படும்போது எந்த " +"வாதங்களும் இல்லாமல் அழைக்கப்படும். செயல்பாடு ஒரு முழு எண்ணாக ஒரு செயல்முறை வெளியேறும் " +"குறியீடாகப் பயன்படுத்தப்படலாம், மேலும் `` எதுவுமில்லை` `திரும்பப் பெறுவது` `0``." + +#: ../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 "" +"உதாரணமாக, நுழைவு புள்ளி `` mycmd = mymod: main`` இது போன்ற ஒரு ச்கிரிப்டைத் " +"தொடங்கும் கட்டளையை உருவாக்கும் ::" + +#: ../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 "" +"`` கன்சோல்_ச்கிரிப்ட்ச்`` மற்றும் `` gui_scripts` ஆகியவற்றுக்கு இடையிலான வேறுபாடு " +"சாளரங்கள் அமைப்புகளை மட்டுமே பாதிக்கிறது. `` console_scripts`` ஒரு கன்சோலில் " +"இயங்கக்கூடியதாக இருக்கும், எனவே அவை ஒரு கன்சோலுடன் இணைக்கப்பட்டு பயன்படுத்தலாம்: py: " +"தரவு: `sys.stdin`,: py: data:` sys.stdout` மற்றும்: py: தரவு: ` உள்ளீடு மற்றும் " +"வெளியீட்டிற்கு sys.stderr`. `` gui_scripts`` ஒரு GUI இயங்கக்கூடியதாக " +"மூடப்பட்டிருக்கும், எனவே அவை கன்சோல் இல்லாமல் தொடங்கப்படலாம், ஆனால் பயன்பாட்டுக் குறியீடு " +"அவற்றை திருப்பிவிடாவிட்டால் நிலையான ச்ட்ரீம்களைப் பயன்படுத்த முடியாது. மற்ற தளங்களில் ஒரே " +"வேறுபாடு இல்லை." + +#: ../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 "" +"நிறுவல் திட்டத்தின் ச்கிரிப்ட்ச் கோப்பகத்தில் `` கன்சோல்_ச்கிரிப்ட்ச்`` மற்றும் `` gui_scripts` " +"ஆகிய இரண்டிற்கும் ரேப்பர்களை நிறுவும் கருவிகள் அமைக்கும் என்று எதிர்பார்க்கப்படுகிறது. " +"கட்டளை-வரி கருவிகள் எங்கு காணப்படுகின்றன என்பதை வரையறுக்கும் `` பாதை` சுற்றுச்சூழல் " +"மாறியில் இந்த கோப்பகத்தை வைப்பதற்கு அவர்கள் பொறுப்பல்ல." + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" +"பெயர்களிலிருந்து கோப்புகள் உருவாக்கப்படுவதால், சில கோப்பு முறைமைகள் வழக்கு-உணர்வற்றவை " +"என்பதால், தொகுப்புகள் இந்த குழுக்களில் பெயர்களைப் பயன்படுத்துவதைத் தவிர்க்க வேண்டும். பெயர்கள் " +"வேறுபடும்போது நிறுவும் கருவிகளின் நடத்தை வரையறுக்கப்படவில்லை." + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" +"அக்டோபர் 2017: இந்த விவரக்குறிப்பு செட்ப்டூல்சின் (கலந்துரையாடல்_) இருக்கும் நுழைவு " +"புள்ளிகள் அம்சத்தை முறைப்படுத்த எழுதப்பட்டது." + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "வெளிப்புறமாக நிர்வகிக்கப்பட்ட சூழல்கள்" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" +"சில பைதான் நிறுவல்கள் பைத்தானை நிறுவிய பயனரால் முழுமையாக நிர்வகிக்கப்படுகின்றன, மற்றவை " +"மற்றொரு வழிமுறையால் வழங்கப்படலாம் மற்றும் நிர்வகிக்கப்படலாம் (லினக்ச் விநியோகத்தில் இயக்க " +"முறைமை தொகுப்பு மேலாளர் அல்லது ஒரு பிரத்யேக நிறுவியுடன் ஒரு பயன்பாட்டில் தொகுக்கப்பட்ட " +"பைதான் சூழலாக) ." + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" +"இதுபோன்ற சூழல்களைக் கையாள வழக்கமான பைதான் பேக்கேசிங் கருவிகளைப் பயன்படுத்த முயற்சிப்பது " +"மிகச் சிறந்ததாகவும், முழு அடிப்படை இயக்க முறைமையையும் மிக மோசமாக உடைக்கும். ஆவணங்கள் " +"மற்றும் இயங்குதன்மை வழிகாட்டிகள் இதுபோன்ற சிக்கல்களைத் தீர்ப்பதில் மட்டுமே இதுவரை செல்கின்றன." + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" +"இந்த விவரக்குறிப்பு `` வெளிப்புறமாக நிர்வகிக்கப்பட்ட`` மார்க்கர் கோப்பை வரையறுக்கிறது, " +"இது ஒரு பைதான் நிறுவலை பைதான்-குறிப்பிட்ட கருவிகளைக் குறிக்க அனுமதிக்கிறது, அதாவது " +"`` பிஐபி`` அவை மொழிபெயர்ப்பாளரின் இயல்புநிலை நிறுவல் சூழலில் தொகுப்புகளை நிறுவவோ " +"அல்லது அகற்றவோ இல்லை, அதற்கு பதிலாக இறுதி பயனரைப் பயன்படுத்துவதை வழிநடத்த வேண்டும்: " +"ref: `மெய்நிகர்-சுற்றுச்சூழல்." + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" +"இது `` சிச்கான்ஃபிக்` திட்டங்களின் விளக்கத்தையும் தரப்படுத்துகிறது, இதனால் ஒரு பைதான்-" +"குறிப்பிட்ட தொகுப்பு மேலாளர் ஒரு மொழிபெயர்ப்பாளர் அளவிலான சூழலில் ஒரு தொகுப்பை நிறுவ " +"உள்ளால், வெளிப்புறத்துடன் முரண்படுவதைத் தவிர்க்கும் வகையில் அவ்வாறு செய்ய முடியும் தொகுப்பு " +"மேலாளர் மற்றும் வெளிப்புற தொகுப்பு மேலாளரால் அனுப்பப்பட்ட மென்பொருளை உடைக்கும் அபாயத்தை " +"குறைக்கிறது." + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "சொல்" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" +"இந்த விவரக்குறிப்பில் பயன்படுத்தப்படும் சில சொற்கள் அது பரவியிருக்கும் சூழல்களில் பல " +"அர்த்தங்களைக் கொண்டுள்ளன. தெளிவுக்கு, இந்த விவரக்குறிப்பு பின்வரும் சொற்களை குறிப்பிட்ட " +"வழிகளில் பயன்படுத்துகிறது:" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "டிச்ட்ரோ" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" +"\"விநியோகத்திற்கான\" குறுகிய, பல்வேறு வகையான மென்பொருள்களின் தொகுப்பாகும், இது (இந்த " +"ஆவணத்துடன் தொடர்புடைய சூழல்களில்) பைதான் மொழிபெயர்ப்பாளர், பைத்தானில் எழுதப்பட்ட மென்பொருள் " +"மற்றும் பிற மொழிகளில் எழுதப்பட்ட மென்பொருள் உட்பட ஒன்றாக ஒன்றாக வேலை செய்ய " +"வடிவமைக்கப்பட்டுள்ளது. அதாவது, இது \"லினக்ச் டிச்ட்ரோ\" அல்லது \"பெர்க்லி மென்பொருள் " +"வழங்கல்\" போன்ற சொற்றொடர்களில் பயன்படுத்தப்படும் உணர்வு." + +#: ../source/specifications/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 "" +"ஒரு டிச்ட்ரோ டெபியன், ஃபெடோரா அல்லது ஃப்ரீ.பி.எச்.டி போன்ற அதன் சொந்த இயக்க முறைமையாக " +"(ஓஎச்) இருக்கலாம். இது ஓம்பிரூ அல்லது மேக்போர்ட்ச் போன்ற ஏற்கனவே உள்ள OS க்கு மேல் நிறுவும் " +"மேலடுக்கு விநியோகமாகவும் இருக்கலாம்." + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" +"இந்த ஆவணம் குறுகிய கால \"டிச்ட்ரோ\" ஐப் பயன்படுத்துகிறது, ஏனெனில் \"வழங்கல்\" என்ற சொல் " +"பைதான் பேக்கேசிங் சூழல்களில் மற்றொரு பொருளைக் கொண்டுள்ளது: பைதான் மொழி மென்பொருளின் ஒற்றை " +"பகுதியின் மூல அல்லது பைனரி விநியோக தொகுப்பு, அதாவது `` செட்டுப்டூல்கள் என்ற பொருளில். " +"Dist.distribution`` அல்லது \"Sdist\". குழப்பத்தைத் தவிர்க்க, இந்த ஆவணம் \"வழங்கல்\" " +"என்ற எளிய வார்த்தையைப் பயன்படுத்தாது. பைதான் பேக்கேசிங் அர்த்தத்தில், இது \"விநியோக " +"தொகுப்பு\" அல்லது \"தொகுப்பு\" என்ற முழு சொற்றொடரைப் பயன்படுத்துகிறது (கீழே காண்க)." + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" +"ஒரு டிச்ட்ரோவின் வழங்குநர் - மென்பொருளை சேகரித்து வெளியிடும் குழு அல்லது நிறுவனம் " +"எந்தவொரு மாற்றங்களையும் செய்யும் - அதன் ** விநியோகச்தர் **." + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "தொகுப்பு" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" +"பைத்தானுக்குள் நிறுவப்பட்டு பயன்படுத்தக்கூடிய மென்பொருளின் ஒரு அலகு. அதாவது, பைதான்-" +"குறிப்பிட்ட பேக்கேசிங் கருவிகள் ஒரு: கால: `விநியோக தொகுப்பு` அல்லது வெறுமனே ஒரு\" " +"வழங்கல் \"என்று அழைக்க முனைகின்றன என்பதைக் குறிக்கிறது; பைதான் தொகுப்பு குறியீட்டின் " +"அர்த்தத்தில் பேச்சுவழக்கு சுருக்கம் \"தொகுப்பு\" பயன்படுத்தப்படுகிறது." + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" +"இந்த ஆவணம் பைதான் தொகுதிகள் கொண்ட இறக்குமதி செய்யக்கூடிய பெயரின் அர்த்தத்தில் \"தொகுப்பு\" " +"ஐப் பயன்படுத்தாது, இருப்பினும் பல சந்தர்ப்பங்களில், ஒரு விநியோக தொகுப்பு அதே பெயரில் " +"இறக்குமதி செய்யக்கூடிய ஒற்றை தொகுப்பைக் கொண்டுள்ளது." + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" +"இந்த ஆவணம் பொதுவாக ஒரு டிச்ட்ரோவின் தொகுப்பு மேலாளரால் நிறுவலின் அலகுகளைக் குறிக்க " +"\"தொகுப்பு\" என்ற வார்த்தையைப் பயன்படுத்தாது (போன்றவை `.deb`` அல்லது` .rpm`` கோப்புகள் " +"போன்றவை). தேவைப்படும்போது, இது \"ஒரு டிச்ட்ரோவின் தொகுப்பு\" போன்ற சொற்றொடரைப் " +"பயன்படுத்துகிறது. ." + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "பைதான்-குறிப்பிட்ட தொகுப்பு மேலாளர்" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" +"பைதான் பேக்கேசிங் தரநிலைகளுக்கு இணங்க பைதான் தொகுப்புகளை நிறுவுதல், மேம்படுத்துதல் " +"மற்றும்/அல்லது அகற்றுவதற்கான ஒரு கருவி. மிகவும் பிரபலமான பைதான்-குறிப்பிட்ட தொகுப்பு " +"மேலாளர் பிப்_; மற்ற எடுத்துக்காட்டுகளில் பழைய `எளிதான நிறுவல் கட்டளை <எளிதான-" +"நிறுவல்_>` _ மற்றும் `` setup.py`` கட்டளையின் நேரடி பயன்பாடு ஆகியவை அடங்கும்." + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" +"(Note that the ``easy_install`` கட்டளை was removed in setuptools version 52, " +"released 23 மா-தை 2021.)" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" +". காண்டா உருவாக்கிய சூழல்களில், பைதான்-குறிப்பிட்ட தொகுப்பு மேலாளராக செயல்படும்போது " +"இந்த ஆவணத்தில் உள்ள பெரும்பாலான கவலைகள் `` கான்டா`` க்கு பொருந்தாது.)" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "டிச்ட்ரோ தொகுப்பு மேலாளர்" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" +"அந்த டிச்ட்ரோவின் நிறுவப்பட்ட நிகழ்வில் ஒரு டிச்ட்ரோவின் தொகுப்புகளை நிறுவுதல், " +"மேம்படுத்துதல் மற்றும்/அல்லது அகற்றுவதற்கான ஒரு கருவி, இது பைதான் தொகுப்புகள் மற்றும் " +"பைதான் அல்லாத தொகுப்புகளை நிறுவும் திறன் கொண்டது, எனவே பொதுவாக நிறுவப்பட்ட " +"மென்பொருளின் சொந்த தரவுத்தளத்தை பொதுவாகக் கொண்டுள்ளது : ref: `நிறுவப்பட்ட விநியோகங்களின் " +"தரவுத்தளம் <பதிவு-நிறுவப்பட்ட-பேக்கேச்கள்>`. எடுத்துக்காட்டுகளில் `` apt``, `dpkg``,` " +"`dnf``,` `rpm``,` `பேக்மேன்``, மற்றும்` `ப்ரூ`` ஆகியவை அடங்கும். முக்கிய நற்பொருத்தம் " +"என்னவென்றால், ஒரு டிச்ட்ரோ தொகுப்பு மேலாளரால் ஒரு தொகுப்பு நிறுவப்பட்டிருந்தால், ஒரு " +"பைதான்-குறிப்பிட்ட தொகுப்பு மேலாளரை திருப்திப்படுத்தும் வகையில் அதை அகற்றுவது அல்லது " +"மேம்படுத்துவது பொதுவாக ஒரு டிச்ட்ரோ தொகுப்பு மேலாளரை சீரற்ற நிலையில் விட்டுவிடுவார்." + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" +"இந்த ஆவணம் சில சூழல்களில் டிச்ட்ரோ தொகுப்பு மேலாளரைப் பார்க்க \"வெளிப்புற தொகுப்பு " +"மேலாளர்\" அல்லது \"கணினியின் தொகுப்பு மேலாளர்\" போன்ற சொற்றொடர்களையும் பயன்படுத்துகிறது." + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "நிழல்" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" +"நிறுவப்பட்ட பைதான் தொகுப்பை நிழலாடுவது, நிழல் தொகுப்பிலிருந்து எந்த கோப்புகளையும் " +"அகற்றாமல் இறக்குமதிக்கு வேறு சில தொகுப்புகளை விரும்புகிறது. இதற்கு `` sys.bath`` இல் " +"பல உள்ளீடுகள் தேவைப்படுகின்றன: தொகுப்பு A 2.0 ஒரு `` sys.bath`` நுழைவாயிலில் `` " +"a.py`` தொகுப்பை நிறுவுகிறது, மேலும் 1.0 ஐ நிறுவுகிறது தொகுதி `a.py```` a.py`` " +"பின்னர் `` sys.bath`` நுழைவாயிலில், `` இறக்குமதி a`` முந்தையவற்றிலிருந்து தொகுதியைத் " +"தருகிறது, மேலும் 2.0 நிழல்கள் 1.0 என்று நாங்கள் கூறுகிறோம்." + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "இந்த விவரக்குறிப்பு இரு மடங்கு." + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" +"முதலாவதாக, ஒரு பைதான் மொழிபெயர்ப்பாளரின் விநியோகச்தர்களுக்கு அந்த மொழிபெயர்ப்பாளருக்கு " +"அதன் தொகுப்புகள் பைதானுக்கு வெளிப்புற வழிமுறைகளை நிர்வகிப்பதாகக் குறிக்க ஒரு வழி இது " +"விவரிக்கிறது ** `sys.bath`` எந்த வகையிலும் (குறிப்பாக மீறப்படாவிட்டால் சேர்க்கவும், " +"மேம்படுத்தவும்/தரமிறக்கவும் அல்லது அகற்றவும்). மெய்நிகர் சூழலை மாற்றாக எவ்வாறு " +"பயன்படுத்துவது என்பதைக் குறிக்க விநியோகச்தருக்கு இது ஒரு வழிமுறையை வழங்குகிறது." + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" +"இது ஒரு விருப்பமான பொறிமுறையாகும்: இயல்பாக, மேலோடை மூலங்களிலிருந்து தொகுக்கப்பட்ட " +"பைதான் மொழிபெயர்ப்பாளர் அவ்வளவு குறிக்கப்பட மாட்டார், எனவே `` பிஐபி நிறுவுதல்`` ஒரு " +"தன்வய ஒருங்கிணைந்த மொழிபெயர்ப்பாளருடன் அல்லது அதன் வெளிப்படையாகக் குறிக்கப்படாத ஒரு " +"டிச்ட்ரோவுடன் இயங்குகிறது மொழிபெயர்ப்பாளர், அது எப்போதும் வேலை செய்ததால் வேலை செய்யும்." + +#: ../source/specifications/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/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "வெளிப்புற தொகுப்பு மேலாளரைப் பயன்படுத்துவதில் ஒரு மொழிபெயர்ப்பாளரைக் குறிக்கும்" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" +"ஒரு பைதான் -குறிப்பிட்ட தொகுப்பு நிறுவி (அதாவது, பிஐபி போன்ற ஒரு கருவி - APT போன்ற " +"வெளிப்புற கருவி அல்ல) ஒரு தொகுப்பை ஒரு குறிப்பிட்ட பைதான் சூழலில் நிறுவுவதற்கு முன், " +"இது இயல்புநிலையாக பின்வரும் சோதனைகளை உருவாக்க வேண்டும்:" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" +"இது ஒரு மெய்நிகர் சூழலுக்கு வெளியே இயங்குகிறதா? `` Sys.prefix == " +"sys.base_prefix`` என்பதன் மூலம் இதை தீர்மானிக்க முடியும்." + +#: ../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 "" +"`` Sysconfig.get_path (\"stdlib\", sysconfig.get_default_scheme ()) `` `` `` " +"ஆல் அடையாளம் காணப்பட்ட கோப்பகத்தில் `` வெளிப்புறமாக நிர்வகிக்கப்பட்ட`` கோப்பு உள்ளதா?" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" +"இந்த இரண்டு நிபந்தனைகளும் உண்மையாக இருந்தால், இந்த பைதான் மொழிபெயர்ப்பாளரின் கோப்பகத்தில் " +"தொகுப்பு நிறுவல் ஒரு மெய்நிகர் சூழலுக்கு வெளியே முடக்கப்பட்டிருப்பதைக் குறிக்கும் பிழை " +"செய்தியுடன் நிறுவி வெளியேற வேண்டும்." + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" +"கட்டளை-வரி கொடி ``-பிரேக்-சிச்டம்-பேக்கேச்கள்`` போன்ற இந்த விதிகளை பயனருக்கு மேலெழுத " +"நிறுவி ஒரு வழியைக் கொண்டிருக்க வேண்டும். இந்த விருப்பம் இயல்புநிலையாக இயக்கப்படக்கூடாது, " +"அதன் பயன்பாடு ஆபத்தானது என்ற சில அர்த்தங்களைக் கொண்டிருக்க வேண்டும்." + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" +"`` வெளிப்புறமாக நிர்வகிக்கப்பட்ட`` கோப்பு என்பது ஒரு ஐ.என்.ஐ-பாணி மேனிலை தரவு " +"கோப்பாகும், இது நிலையான நூலக கட்டமைப்பு_ தொகுதி மூலம் பாகுபடுத்தக்கூடியதாக இருக்கும். " +"கோப்பை `` configparser.configparser (இடைக்கணிப்பு = எதுவுமில்லை) `` `யுடிஎஃப் -8 " +"குறியாக்கத்தைப் பயன்படுத்துவதன் மூலம் பாகுபடுத்த முடியும் என்றால், அதில் ஒரு பிரிவு` " +"`[வெளிப்புறமாக நிர்வகிக்கப்படும்]` `ஆகியவற்றைக் கொண்டுள்ளது, பின்னர் நிறுவி ஒரு பிழை " +"செய்தியைத் தேட வேண்டும் கோப்பில் குறிப்பிடப்பட்டுள்ளது மற்றும் அதன் பிழையின் ஒரு பகுதியாக " +"அதை வெளியிடுகிறது. டூப்பின் முதல் உறுப்பு `` locale.getLocale " +"(locale.lc_messages) ``, அதாவது, மொழிக் குறியீடு, `` எதுவுமில்லை'` அல்ல என்றால், " +"அது பிழை செய்தியை பெயரிடப்பட்ட ஒரு முக்கிய மதிப்பாக பார்க்க வேண்டும் `` பிழை- `` " +"மொழித் குறியீட்டைத் தொடர்ந்து. அந்த விசை இல்லையென்றால், மொழிக் குறியீட்டில் அடிக்கோடிட்டு " +"அல்லது ஐபன் இருந்தால், அது `` பிழை-` 'என்ற விசையை அடிக்கோடிட்டுக் காட்ட வேண்டும். " +"அவற்றில் ஏதேனும் ஒன்றைக் கண்டுபிடிக்க முடியாவிட்டால், அல்லது மொழிக் குறியீடு `` " +"எதுவுமில்லை`` என்றால், அது வெறுமனே `` பிழை` என்ற பெயரைக் காண வேண்டும்." + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" +"நிறுவி கோப்பில் பிழை செய்தியைக் கண்டுபிடிக்க முடியாவிட்டால் (கோப்பை பாகுபடுத்த " +"முடியாது அல்லது பொருத்தமான பிழை விசை இல்லாததால்), நிறுவி அதன் சொந்த முன் " +"வரையறுக்கப்பட்ட பிழை செய்தியைப் பயன்படுத்த வேண்டும், இது பயனரை பரிந்துரைக்க வேண்டும் " +"தொகுப்புகளை நிறுவ ஒரு மெய்நிகர் சூழலை உருவாக்கவும்." + +#: ../source/specifications/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 an ``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 "" +"பைதான் அல்லாத-குறிப்பிட்ட தொகுப்பு மேலாளரைக் கொண்ட மென்பொருள் விநியோகச்தர்கள், அவர்களின் " +"பைதான் தொகுப்பின் `` sys.bath`` இல் உள்ள நூலகங்களை நிர்வகிக்கும், பொதுவாக, `` " +"வெளிப்புறமாக நிர்வகிக்கப்பட்ட`` கோப்பை அவர்களின் நிலையான நூலக கோப்பகத்தில் அனுப்ப " +"வேண்டும். உதாரணமாக, டெபியன் ஒரு கோப்பை ``/usr/lib/python3.9/வெளிப்புறமாக " +"நிர்வகிக்கப்பட்ட` போன்றவற்றில் அனுப்பலாம்." + +#: ../source/specifications/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" +"இது ஒரு தொகுப்பை நிறுவ முயற்சிக்கும் பயனருக்கு பயனுள்ள மற்றும் டிச்ட்ரோ தொடர்பான " +"தகவல்களை வழங்குகிறது. விருப்பமாக, மொழிபெயர்ப்புகளை அதே கோப்பில் வழங்க முடியும்:" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" +"படைப்புக்குப் பிறகு புதுப்பிக்கப்படாத ஒற்றை-பயன்பாட்டு கொள்கலன் படங்கள் போன்ற சில " +"சூழல்களில், ஒரு விநியோகச்தர் ஒரு `` வெளிப்புறமாக நிர்வகிக்கப்பட்ட`` கோப்பை அனுப்ப " +"வேண்டாம் என்று தேர்வு செய்யலாம், இதனால் பயனர்கள் தங்களால் விரும்பியதை நிறுவ முடியும் " +"(இன்று அவர்கள் முடிந்தவரை) இந்த விதியை கைமுறையாக மேலெழுதாமல்." + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "இலக்கு `` சிச்கான்ஃபிக்`` திட்டத்திற்கு மட்டுமே எழுதுதல்" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" +"வழக்கமாக, ஒரு பைதான் தொகுப்பு நிறுவி `` சிச்கான்ஃபிக்`` நிலையான நூலக தொகுப்பு மூலம் " +"திரும்பிய திட்டத்தில் கோப்பகங்களுக்கு நிறுவுகிறது. பொதுவாக, இது `` " +"sysconfig.get_default_scheme () `` வழங்கிய திட்டமாகும், ஆனால் உள்ளமைவின் " +"அடிப்படையில் (எ.கா." + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" +"நிறுவி ஒரு `` சிச்கான்ஃபிக்`` திட்டத்திற்கு நிறுவும் போதெல்லாம், அந்த திட்டத்திற்கு " +"வெளியே உள்ள கோப்புகளை நிறுவி ஒருபோதும் மாற்றவோ அல்லது நீக்கவோ கூடாது என்று இந்த " +"விவரக்குறிப்பு அறிவிக்கிறது. உதாரணமாக, இது ஒரு தொகுப்பை மேம்படுத்தினால், தொகுப்பு " +"ஏற்கனவே அந்தத் திட்டத்திற்கு வெளியே ஒரு கோப்பகத்தில் நிறுவப்பட்டிருந்தால் (ஒருவேளை மற்றொரு " +"திட்டத்திலிருந்து ஒரு கோப்பகத்தில்), அது ஏற்கனவே இருக்கும் கோப்புகளை மட்டும் விட்டுவிட " +"வேண்டும்." + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" +"மேம்படுத்தலின் போது நிறுவி ஏற்கனவே உள்ள நிறுவலை நிழலாடுவதை முடித்தால், அதன் ஓட்டத்தின் " +"முடிவில் அது ஒரு எச்சரிக்கையை உருவாக்க பரிந்துரைக்கிறோம்." + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" +"நிறுவி ஒரு `` சிச்கான்ஃபிக்` திட்டத்திற்கு வெளியே ஒரு இடத்திற்கு நிறுவினால் (எ.கா., " +"`` பிஐபி நிறுவல் - -இலக்கு``), இந்த துணைப்பிரிவு பொருந்தாது." + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "டிச்ட்ரோக்களுக்கான பரிந்துரைகள்" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" +"இந்த பிரிவு நெறிமுறையற்றது. டிச்ட்ரோக்கள் ஒரு குறிப்பிட்ட காரணத்தை இல்லாவிட்டால் " +"அவர்களுக்கு பின்பற்ற வேண்டும் என்று நாங்கள் நம்புகிறோம்." + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "வெளிப்புறமாக நிர்வகிக்கப்பட்டபடி நிறுவலைக் குறிக்கவும்" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" +"டிச்ட்ரோக்கள் தங்கள் `` stdlib`` கோப்பகத்தில் `` வெளிப்புறமாக நிர்வகிக்கப்பட்ட`` கோப்பை " +"உருவாக்க வேண்டும்." + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "மெய்நிகர் சூழல்களை நோக்கி பயனர்களை வழிநடத்துங்கள்" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" +"டிச்ட்ரோவின் தொகுப்பு மேலாளர் வழியாக கணினி அளவிலான தொகுப்புகளை எவ்வாறு நிறுவுவது " +"மற்றும் மெய்நிகர் சூழலை எவ்வாறு அமைப்பது என்பதைக் குறிக்கும் பயனுள்ள மற்றும் டிச்ட்ரோ " +"தொடர்பான பிழை செய்தியை கோப்பில் கொண்டிருக்க வேண்டும். `` பைதான் 3`` கட்டளை கிடைக்கும் " +"(குறிப்பாக `` பிப்`` அல்லது `` கெட் -பிப்`` கிடைக்கும் இடத்தில்) உங்கள் டிச்ட்ரோ " +"பெரும்பாலும் பயனர்களால் பயன்படுத்தப்பட்டால்) ஆனால் `` பைதான் 3 -எம் வென்வ்``` வேலை " +"செய்யாது, செய்தி `` பைதான் 3 -எம் வெர்வ்`` சரியாக வேலை செய்வது எப்படி என்பதை தெளிவாகக் " +"குறிக்க வேண்டும்." + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" +"பைதான்-மொழி பயன்பாடுகளை நிறுவுவதற்கான கருவியான PIPX_ ஐ பேக்கேசிங் செய்வதைக் " +"கவனியுங்கள், மேலும் அதை பிழையில் பரிந்துரைக்கவும். PIPX தானாகவே அந்த பயன்பாட்டிற்கான " +"ஒரு மெய்நிகர் சூழலை உருவாக்குகிறது, இது சில பைதான்-மொழி மென்பொருளை (இது டிச்ட்ரோவில் " +"கிடைக்கவில்லை) நிறுவ விரும்பும் இறுதி பயனர்களுக்கு மிகச் சிறந்த இயல்புநிலையாகும், ஆனால் " +"அவை பைதான் பயனர்கள் அல்ல. டிச்ட்ரோவில் உள்ள பிஐபிஎக்ச் பேக்கேசிங் பயனர்களுக்கு `` பிஐபி " +"நிறுவுதல்-யூசர்-பிரேக்-சிச்டம்-பேக்கேச்கள் பிப்எக்ச்`` கணினி தொகுப்புகளை உடைப்பதை * " +"தவிர்க்க அறிவுறுத்துவதன் முரண்பாட்டைத் தவிர்க்கிறது. விசயங்களை ஒழுங்குபடுத்துவதைக் " +"கவனியுங்கள், எனவே இறுதி பயனர்களுக்கான பைத்தானுக்கான உங்கள் டிச்ட்ரோவின் தொகுப்பு / சூழல் " +"(எ.கா., ஃபெடோராவில் `` பைதான் 3`` அல்லது `` பைதான் 3-ஃபுல்`` டெபியன் மீது) பிப்எக்ச் " +"சார்ந்துள்ளது." + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "மார்க்கர் கோப்பை கொள்கலன் படங்களில் வைக்கவும்" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" +"ஒற்றை-பயன்பாட்டு கொள்கலன்களுக்கான அதிகாரப்பூர்வ படங்களை உருவாக்கும் டிச்ட்ரோக்கள் (எ.கா., " +"கப்பல்துறை கொள்கலன் படங்கள்) `` வெளிப்புறமாக நிர்வகிக்கப்பட்ட`` கோப்பை வைத்திருக்க வேண்டும், " +"முன்னுரிமை அந்த படத்தின் பயனர் அவற்றின் உள்ளே தொகுப்பு புதுப்பிப்புகளை நிறுவினால் அது " +"போகாது படம் (`` என்று சிந்தியுங்கள்." + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "தனி டிச்ட்ரோ மற்றும் உள்ளக கோப்பகங்களை உருவாக்கவும்" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" +"டிச்ட்ரோக்கள் கணினி மொழிபெயர்ப்பாளரின் `` sys.bath``, ஒன்று டிச்ட்ரோ-நிறுவப்பட்ட " +"தொகுப்புகளுக்கு மற்றும் உள்ளக கணினி நிர்வாகியால் நிறுவப்பட்ட தொகுப்புகளுக்கு ஒன்று வைக்க " +"வேண்டும், மேலும் `` sysconfig.get_default_scheme () `` பிந்தைய பாதை. பிஐபி போன்ற " +"கருவிகள் டிச்ட்ரோ நிறுவப்பட்ட தொகுப்புகளை மாற்றாது என்பதை இது உறுதி செய்கிறது. உள்ளக " +"கணினி நிர்வாகிக்கான பாதை `` sys.path`` இல் டிச்ட்ரோ பாதைக்கு முன் வர வேண்டும், இதனால் " +"உள்ளக நிறுவல்கள் டிச்ட்ரோ தொகுப்புகளை விட முன்னுரிமை பெறுகின்றன." + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" +"எடுத்துக்காட்டாக, ஃபெடோரா மற்றும் டெபியன் (மற்றும் அவற்றின் வழித்தோன்றல்கள்) இருவரும் " +"உள்நாட்டில் நிறுவப்பட்ட தொகுப்புகளுக்கு ``/usr/local` மற்றும் டிச்ட்ரோ நிறுவப்பட்ட " +"தொகுப்புகளுக்கு ``/usr`` ஆகியவற்றைப் பயன்படுத்தி இந்த பிளவுகளை செயல்படுத்துகிறார்கள். " +"ஃபெடோரா ``/usr/local/lib/python3.x/site- பேக்கேச்கள்` `` `/usr/lib/python3.x/" +"site-packages`` ஐப் பயன்படுத்துகிறது. . நீங்கள் ``/usr/local/bin`` இல் மேலோடை " +"சிபிதானை உருவாக்கி நிறுவுகிறீர்கள், அது பார்க்கும் ``/usr/local/lib/python3/site-" +"packages``, மற்றும் உள்நாட்டில் கட்டப்பட்ட மொழிபெயர்ப்பாளர் வழியாக நிறுவப்பட்ட தொகுப்புகள் " +"டிச்ட்ரோ மொழிபெயர்ப்பாளருக்கு `` sys.path`` இல் காண்பிக்கப்படாது என்பதை உறுதிப்படுத்த " +"டெபியன் விரும்புகிறார். )" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" +"``/Usr/local` vs. ``/usr``` பிளவு `` பாதை`` சுற்றுச்சூழல் மாறுபாடு பொதுவாக ``/" +"usr/local/bin:/usr/bin`` மற்றும் எவ்வாறு அடங்கும் என்பதற்கு ஒத்ததாக இருக்கிறது என்பதை " +"நினைவில் கொள்க டிச்ட்ரோ அல்லாத மென்பொருள் இயல்பாக ``/usr/local`` க்கு நிறுவுகிறது. " +"இந்த பிளவு `கோப்பு முறைமை வரிசைமுறை தரநிலையால் பரிந்துரைக்கப்படுகிறது`__." + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" +"இதை நீங்கள் செய்ய இரண்டு வழிகள் உள்ளன. ஒன்று, நீங்கள் பைதான் நூலகங்களை நேரடியாக உருவாக்கி " +"பேக்கேசிங் செய்தால் (எ.கா. `திட்டம் ஆனால் இன்னும்` `sys.bath`` இல் உள்ளது." + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" +"மற்றொன்று, நிறுவப்பட்ட கணினியில் இயங்கும் போது ஒரு தொகுப்பு கட்டமைப்பிற்குள் இயங்கும்போது " +"இயல்புநிலை `` சிச்கான்ஃபிக்`` திட்டத்தை மாற்ற ஏற்பாடு செய்ய வேண்டும். BPO-43976_ " +"இலிருந்து `` sysconfig`` தனிப்பயனாக்குதல் கொக்கிகள் இதை எளிதாக்க வேண்டும் (ஒருமுறை " +"ஏற்றுக்கொள்ளப்பட்டு செயல்படுத்தப்பட்டால்): உங்கள் பேக்கேசிங் கருவியை சூழல் மாறியை அமைக்கவும் " +"அல்லது வேறு ஏதேனும் கண்டறியக்கூடிய உள்ளமைவை அமைக்கவும், மேலும் `` " +"get_preferred_schemes`` செயல்பாட்டை வரையறுக்கவும் ஒரு தொகுப்பு கட்டமைப்பிற்குள் " +"இருந்து அழைக்கும்போது திட்டம். உங்கள் டிச்ட்ரோ பேக்கேசிங்கின் ஒரு பகுதியாக `` பிஐபி " +"நிறுவுதல்` ஐப் பயன்படுத்தலாம்." + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" +"ஒரு குறிப்பிட்ட திட்டத்திற்கு எதிராக இயங்க PIP க்கு அறிவுறுத்துவதற்கான `` --scheme " +"= ... `` விருப்பத்தை சேர்க்க நாங்கள் முன்மொழிகிறோம். . உங்கள் டிச்ட்ரோவின் இருப்பிடத்தில் " +"ஒரு தொகுப்பை நிறுவவும் (`` get_prefered_schemes`` ஐத் தவிர்த்து). கணினி-" +"நிர்வகிக்கப்பட்ட கோப்பகத்திலிருந்து தொகுப்புகளை அகற்ற PIP ஐப் பயன்படுத்த `` பிஐபி நிறுவல் " +"நீக்குதல்-scheme = posix_distro`` ஐப் பயன்படுத்தலாம்." + +#: ../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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" +"இவற்றை தானாக அமைப்பதன் நன்மை (உங்கள் உருவாக்க சூழலில் மார்க்கர் கோப்பை அடக்குதல் மற்றும் `` " +"get_prefered_schemes`` உங்கள் டிச்ட்ரோவின் திட்டத்தை தானாகவே திருப்பித் தருவது) என்பது " +"ஒரு அலங்காரமற்ற `` பிஐபி நிறுவல்`` ஒரு தொகுப்பு கட்டமைப்பிற்குள் செயல்படும், இது " +"பொதுவாக `` பிஐபி நிறுவுதல்`` உள்நாட்டில் அழைக்கப்படும் ஒரு மாற்றப்படாத மேலோடை உருவாக்க " +"ச்கிரிப்ட் சரியானதைச் செய்யும். நிச்சயமாக, உங்கள் பேக்கேசிங் செயல்முறை எப்போதுமே `` பிஐபி " +"நிறுவல் --சேம் = POSIX_DISTRO-பிரேக்-சிச்டம்-பேக்கேச்கள்`` என்று அழைப்பதை நீங்கள் " +"உறுதிப்படுத்திக் கொள்ளலாம், அதுவும் வேலை செய்யும்." + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" +"இங்கே சிறந்த அணுகுமுறை உங்கள் டிச்ட்ரோவின் மரபுகள் மற்றும் பேக்கேசிங்கிற்கான வழிமுறைகளைப் " +"பொறுத்தது." + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" +"இதேபோல், இறக்குமதி செய்யக்கூடிய பைதான் குறியீட்டிற்காக இல்லாத `` சிச்கான்ஃபிக்` பாதைகள் - " +"அதாவது `` அடங்கும்``, `` பிளாட்டின்க்ளூட்``, `` ச்கிரிப்ட்கள்``, மற்றும் `` தரவு`` - " +"இரண்டு வகைகளும் இருக்க வேண்டும் . உதாரணமாக, ஒரு பொதுவான FHS- இணக்கமான டிச்ட்ரோ " +"இயல்புநிலை திட்டத்தின் `` ``` மற்றும்` `/usr/`` டிச்ட்ரோ-பேக்கேச் செய்யப்பட்ட " +"தலைப்புகளுக்கு` `/usr/incllow`` ஐப் பயன்படுத்தும். தேடல் பாதையைத் தேடுங்கள், இது " +"இயல்புநிலை திட்டத்தின் `` ச்கிரிப்ட்கள்`` மற்றும் ``/usr/bin`` டிச்ட்ரோ-தொகுக்கப்பட்ட " +"நுழைவு புள்ளிகளுக்கு `` $ பாதை`` இரண்டையும் வைக்கவும்." + +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" +msgstr "செயல்படுத்தல் குறிப்புகள்" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" +"இந்த பிரிவு நெறிமுறையற்றது மற்றும் விவரக்குறிப்பு மற்றும் சாத்தியமான செயலாக்கங்கள் " +"இரண்டிற்கும் தொடர்புடைய குறிப்புகளைக் கொண்டுள்ளது." + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" +"தற்போது (மே 2021 நிலவரப்படி), ஒரு இலக்கை `` சிச்கான்ஃபிக்`` திட்டத்தைத் " +"தேர்ந்தெடுப்பதற்கான வழியை பிஐபி நேரடியாக அம்பலப்படுத்தவில்லை, ஆனால் நிறுவும் போது " +"திட்டங்களைப் பார்ப்பதற்கான மூன்று வழிகள் உள்ளன:" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "`` பிஐபி நிறுவுதல்``" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" +"`` Sysconfig.get_default_scheme () ``, இது வழக்கமாக (அப்ச்ட்ரீம் சிபிதான் மற்றும் " +"பெரும்பாலான தற்போதைய டிச்ட்ரோக்களில்) `` get_prefered_scheme ('முன்னொட்டு') ``." + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "`` பிஐபி நிறுவுதல் -பிரெஃபிக்ச் =/சில/பாதை``" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "`` Sysconfig.get_prefered_scheme ('முன்னொட்டு') ``." + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "`` பிஐபி நிறுவுதல் --user``" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "`` Sysconfig.get_prefered_scheme ('பயனர்') ``." + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" +"இறுதியாக, `` பிஐபி நிறுவுதல் - -இலக்கு =/சில/பாதை`` எந்த திட்டங்களையும் பார்க்காமல் " +"நேரடியாக ``/சில/பாதை`` க்கு எழுதுகிறது." + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" +"டெபியன் தற்போது ஒரு மெய்நிகர் சூழலுக்குள் இயல்புநிலை நிறுவும் இருப்பிடத்தை மாற்ற ஒரு " +"`பேட்சைக் கொண்டு செல்கிறார், சில ஊரிச்டிக்சைப் பயன்படுத்தி (` `மெய்நிகர்_இன்`` சுற்றுச்சூழல் " +"மாறியைச் சரிபார்ப்பது உட்பட), பெரும்பாலும் மெய்நிகர் சூழலில் பயன்படுத்தப்படும் அடைவு `` " +"தள-பேக்கேச்கள்`` மற்றும் `` மாவட்ட-பேக்கேச்கள்`` அல்ல. இது குறிப்பாக இந்த திட்டத்தை " +"பாதிக்காது, ஏனென்றால் அந்த இணைப்பை செயல்படுத்துவது உண்மையில் இயல்புநிலை `` சிச்கான்ஃபிக்` " +"திட்டத்தை மாற்றாது, குறிப்பாக `` sysconfig.get_path (\"stdlib\") `` இன் முடிவை " +"மாற்றாது." + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" +"ஃபெடோரா தற்போது rpmbuild`__ க்குள் இயங்காதபோது இயல்புநிலை நிறுவல் இருப்பிடத்தை மாற்ற " +"ஒரு `பேட்சைக் கொண்டுள்ளது, அவை இரண்டு அமைப்பு அளவிலான-இயக்குநர்கள் அணுகுமுறையை " +"செயல்படுத்த பயன்படுத்துகின்றன. மாற்றப்பட்ட `` சிச்கான்ஃபிக்`` திட்டமாக பதிலாக `` " +"டிச்ட்டில்ச்`` ஒரு குறியீடு இணைப்பாக செயல்படுத்தப்பட்டதைத் தவிர, இது பிபிஓ -43976_ ஆல் " +"கற்பனை செய்யப்பட்ட கொக்கி என்பது கருத்தியல் ரீதியாக உள்ளது." + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" +"மேலே உள்ள `` is_virtual_enveronment``, அத்துடன் `` வெளிப்புறமாக நிர்வகிக்கப்பட்ட`` " +"கோப்பை ஏற்றுவதற்கும், அதிலிருந்து பிழை செய்தியைக் கண்டுபிடிப்பதற்கும் தர்க்கத்தையும் " +"செயல்படுத்துவதும் நிலையான நூலகத்தில் சேர்க்கப்படலாம் (`sys`` மற்றும் `` sysconfig``` " +"`முறையே), அவற்றின் செயலாக்கங்களை மையப்படுத்த, ஆனால் அவை இன்னும் சேர்க்கப்பட வேண்டியதில்லை." + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "பதிப்புரிமை" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" +"இந்த ஆவணம் பொது களத்தில் அல்லது CC0-1.0-பல்கலைக்கழக உரிமத்தின் கீழ் வைக்கப்பட்டுள்ளது, எது " +"மிகவும் அனுமதிக்கப்பட்டாலும்." + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "சூன் 2022: இந்த விவரக்குறிப்பு மூலம் அங்கீகரிக்கப்பட்டது: PEP: `668`." + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +#, fuzzy +#| msgid "This specification was originally defined in :pep:`753`." +msgid "This specification was originally defined in :pep:`592`." +msgstr "இந்த விவரக்குறிப்பு முதலில் வரையறுக்கப்பட்டது: PEP: `753`." + +#: ../source/specifications/file-yanking.rst:14 +#, fuzzy +#| msgid "" +#| ":pep:`740` includes changes to the HTML and JSON index APIs. These " +#| "changes are documented in the :ref:`simple-repository-api` " +#| "under :ref:`simple-repository-api-base` and :ref:`json-serialization`." +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" +": PEP: `740` உஉகுமொ மற்றும் சாதொபொகு குறியெண் பநிஇ களில் மாற்றங்களை உள்ளடக்கியது. " +"இந்த மாற்றங்கள்: ref: `Simple-reposition-api` இன் கீழ் ஆவணப்படுத்தப்பட்டுள்ளன: ref:` " +"எளிய-ரோபோசிட்டரி-ஆபி-பேச்` மற்றும்: குறிப்பு: `json-cerialization`." + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" +"எளிய களஞ்சியத்தில் உள்ள இணைப்புகள் ** ** ஒரு `` தரவு-யாங்கட்`` பண்புக்கூறு இருக்கலாம், " +"இது எந்த மதிப்பும் இல்லாதிருக்கலாம், அல்லது ஒரு தன்னிச்சையான சரம் மதிப்பாக இருக்கலாம். " +"ஒரு `` தரவு-யங்க்` பண்புக்கூறு ** இருப்பு ** இந்த குறிப்பிட்ட இணைப்பால் சுட்டிக்காட்டப்பட்ட " +"கோப்பு \"அசைக்கப்பட்டது\" என்பதைக் குறிக்கிறது, மேலும் குறிப்பிட்ட காட்சிகளின் கீழ் தவிர, " +"ஒரு நிறுவியால் பொதுவாக தேர்ந்தெடுக்கப்படக்கூடாது ." + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" +"`` டேட்டா-யாங்கட்`` பண்புக்கூறின் மதிப்பு, இருந்தால், ஒரு தன்னிச்சையான சரம், இது கோப்பு " +"ஏன் அசைக்கப்பட்டது என்பதற்கான காரணத்தைக் குறிக்கிறது. எளிய களஞ்சிய பநிஇ ** செயலாக்கும் " +"கருவிகள் ** இந்த சரத்தை இறுதி பயனர்களுக்கு மேற்பரப்பு செய்யலாம்." + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" +"யங்க் செய்யப்பட்ட பண்புக்கூறு மாறாதவுடன் மாறாதது அல்ல, எதிர்காலத்தில் ரத்து செய்யப்படலாம் " +"(மற்றும் ரத்து செய்யப்பட்டவுடன், மீட்டமைக்கப்படலாம்). இவ்வாறு பநிஇ பயனர்கள் ** ** ஒரு " +"அழிக்கப்பட்ட கோப்பை \"ஒழுங்கற்ற\" (மற்றும் மீண்டும் அசைக்கக் கூட) சமாளிக்க முடியும்." + +#: ../source/specifications/file-yanking.rst:40 +msgid "Installers" +msgstr "நிறுவிகள்" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" +"பயனர்களுக்கு விரும்பத்தக்க பட்டறிவு என்னவென்றால், ஒரு கோப்பை அசைத்தவுடன், ஒரு மனிதர் " +"தற்போது ஒரு கோப்பை நேரடியாக நிறுவ முயற்சிக்கும்போது, அந்தக் கோப்பு நீக்கப்பட்டதைப் போல " +"தோல்வியடைகிறது. இருப்பினும், ஒரு மனிதர் சிறிது நேரத்திற்கு முன்பு அதைச் செய்தபோது, " +"இப்போது ஒரு கணினி இப்போது அசைக்கப்பட்ட கோப்பை நிறுவ அசல் வரிசையை இயந்திரத்தனமாக " +"பின்பற்றி வருகிறது, பின்னர் அது அசைக்கப்படாதது போல் செயல்படுகிறது." + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" +"ஒரு நிறுவி ** ** யங்க் வெளியீடுகளை புறக்கணிக்க வேண்டும், தேர்வு தடைகளை யாங்க்ட் " +"செய்யப்படாத பதிப்பில் நிறைவு அடைய முடியும் என்றால், ** மே ** ஒரு கோரிக்கையை " +"திருப்திப்படுத்த முடியாது என்று பொருள் இருந்தாலும் கூட ஒரு வெளியீட்டைப் பயன்படுத்த " +"மறுக்கலாம். ஒரு செயல்படுத்தல் ** ** மேலே உள்ள நோக்கத்தின் ஆவியைப் பின்பற்றும் ஒரு " +"கொள்கையைத் தேர்வு செய்ய வேண்டும், மேலும் இது வெளியீடுகள்/கோப்புகளை \"புதிய\" சார்புகளைத் " +"தடுக்கிறது." + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" +"இதன் பொருள் என்னவென்றால், குறிப்பிட்ட நிறுவி வரை, அவற்றின் நிறுவியின் ஒட்டுமொத்த " +"பயன்பாட்டிற்கு எவ்வாறு சிறப்பாக பொருந்துவது என்பதை தீர்மானிக்க. இருப்பினும், எடுக்க இரண்டு " +"பரிந்துரைக்கப்பட்ட அணுகுமுறைகள் உள்ளன:" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" +"`` == `` (``.*``) அல்லது `` === `` போன்ற ஒரு வரம்பை உருவாக்கும் எந்த மாற்றிகளும் " +"இல்லாமல், சரியான பதிப்பிற்கு \"ஊசிகளை\" பொருத்தும் ஒரே கோப்பாக இல்லாவிட்டால், அவை " +"எப்போதும் புறக்கணிக்கப்படுகின்றன. இந்த பதிப்பு விவரக்குறிப்பைப் பொருத்துவது இல்லையெனில் " +"செய்யப்பட வேண்டும்: குறிப்பு: `பதிப்பு விவரக்குறிப்புகள் விவரக்குறிப்பு <பதிப்பு-" +"விவரக்குறிப்புகள்>` உள்ளக பதிப்புகள், சுழிய திணிப்பு போன்றவற்றுக்கு." + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" +"ஒரு பூட்டுக் கோப்பு (`` pipfile.lock`` அல்லது `` Poetic.lock`` போன்றவை) நிறுவப்பட " +"வேண்டியதைக் குறிப்பிடும் ஒரே கோப்பாக இல்லாவிட்டால், அவை எப்போதும் புறக்கணிக்கப்படும். இந்த " +"வழக்கில், சில உள்ளீட்டு கோப்பு அல்லது கட்டளையிலிருந்து பூட்டு கோப்பை உருவாக்கும்போது " +"அல்லது புதுப்பிக்கும்போது ** ** பயன்படுத்தப்படக்கூடாது." + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "கண்ணாடிகள்" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "கண்ணாடிகள் பொதுவாக இரண்டு வழிகளில் ஒன்றான கோப்புகளை நடத்தலாம்:" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" +"அவர்கள் தங்கள் எளிய களஞ்சிய பநிஇ இருந்து முற்றிலும் தவிர்க்க தேர்வு செய்யலாம், இது " +"\"செயலில்\", இணைக்கப்படாத கோப்புகளை மட்டுமே காட்டும் களஞ்சியத்தின் மீது ஒரு பார்வையை " +"வழங்குகிறது." + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" +"அவர்கள் யங்க் செய்யப்பட்ட கோப்புகளைச் சேர்க்க தேர்வு செய்யலாம், மேலும் கூடுதலாக `` தரவு-" +"யாங்கட்`` பண்புகளையும் பிரதிபலிக்கலாம்." + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" +"கண்ணாடிகள் ** ** அதற்கான `` டேட்டா-யாங்கட்`` பண்புக்கூறையும் பிரதிபலிக்காமல் ஒரு அழிந்த " +"கோப்பை பிரதிபலிக்கக்கூடாது." + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" +"எண்ணெழுத்து எழுத்துக்கள், அடிக்கோடிட்டு (`` _``), ஐபன்கள் (`` -``) மற்றும் புள்ளிகள் " +"(`` .``) ஆகியவை சொற்களஞ்சியத்துடன் பொருந்த வேண்டும்." + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" +"சிறப்பு குளோப் எழுத்துக்கள்: ``*``, ``? `` [...] `` க்குள், ஐபன் ஒரு லோகேல்-அஞ்ஞான " +"வரம்பைக் குறிக்கிறது (எ.கா. `` a-z``, யூனிகோட் குறியீடு புள்ளிகளின் அடிப்படையில் " +"ஆர்டர்). தொடக்க அல்லது முடிவில் ஐபன்கள் உண்மையில் பொருந்துகின்றன." + +#: ../source/specifications/glob-patterns.rst:27 +#, fuzzy +#| msgid "Path delimiters must be the forward slash character (``/``)." +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "பாதை டிலிமிட்டர்கள் முன்னோக்கி ச்லாச் எழுத்துக்குறியாக இருக்க வேண்டும் (``/``)." + +#: ../source/specifications/glob-patterns.rst:29 +#, fuzzy +#| msgid "" +#| "Path delimiters MUST be the forward slash character (``/``). Patterns are " +#| "relative to the directory containing :file:`pyproject.toml`, therefore " +#| "the leading slash character MUST NOT be used." +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" +"பாதை டிலிமிட்டர்கள் முன்னோக்கி ச்லாச் எழுத்துக்குறியாக இருக்க வேண்டும் (``/``). வடிவங்கள் " +"கொண்ட கோப்பகத்துடன் தொடர்புடையவை: கோப்பு: `pyproject.toml`, எனவே முன்னணி ச்லாச் " +"எழுத்து பயன்படுத்தப்படக்கூடாது." + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "பெற்றோர் அடைவு குறிகாட்டிகள் (`` ..``) பயன்படுத்தப்படக்கூடாது." + +#: ../source/specifications/glob-patterns.rst:36 +#, fuzzy +#| msgid "" +#| "Any characters or character sequences not covered by this specification " +#| "are invalid. Projects MUST NOT use such values. Tools consuming this " +#| "field SHOULD reject invalid values with an error." +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" +"இந்த விவரக்குறிப்பால் மூடப்படாத எந்த எழுத்துக்கள் அல்லது எழுத்துக்குறி காட்சிகளும் " +"தவறானவை. திட்டங்கள் அத்தகைய மதிப்புகளைப் பயன்படுத்தக்கூடாது. இந்த புலத்தை எடுத்துக் " +"கொள்ளும் கருவிகள் பிழையுடன் தவறான மதிப்புகளை நிராகரிக்க வேண்டும்." + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" +"நேரடி பாதைகள் (எ.கா.: கோப்பு: `உரிமம்`) செல்லுபடியாகும் குளோப்கள், அதாவது அவை " +"வரையறுக்கப்படலாம்." + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" +"ஒவ்வொரு மதிப்பையும் ஒரு குளோப் வடிவமாகக் கருத வேண்டும், மேலும் வடிவத்தில் தவறான குளோப் " +"தொடரியல் இருந்தால் பிழையை உயர்த்த வேண்டும்." + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" +"எந்தவொரு தனிப்பட்ட பயனர் குறிப்பிட்ட வடிவமும் குறைந்தது ஒரு கோப்பில் பொருந்தவில்லை என்றால் " +"பிழையை உயர்த்த வேண்டும்." + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +#, fuzzy +#| msgid "Reference Implementation" +msgid "Reference implementation in Python" +msgstr "குறிப்பு செயல்படுத்தல்" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "PYPA விவரக்குறிப்புகள்" + +#: ../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 "" +"இது பைதான் பேக்கேசிங் ஆணையத்தால் பராமரிக்கப்படும் தற்போது செயலில் உள்ள இயங்குதன்மை " +"விவரக்குறிப்புகளின் பட்டியல். இந்த தரங்களை புதுப்பிப்பதற்கான செயல்முறை, மற்றும் புதியவற்றை " +"முன்மொழியுவதற்காக, `pypa.io __." + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "குறியீட்டு புரவலன் சான்றுகள்" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "இந்த விவரக்குறிப்பு முதலில் வரையறுக்கப்பட்டது: PEP: `740`." + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" +": PEP: `740` உஉகுமொ மற்றும் சாதொபொகு குறியெண் பநிஇ களில் மாற்றங்களை உள்ளடக்கியது. " +"இந்த மாற்றங்கள்: ref: `Simple-reposition-api` இன் கீழ் ஆவணப்படுத்தப்பட்டுள்ளன: ref:` " +"எளிய-ரோபோசிட்டரி-ஆபி-பேச்` மற்றும்: குறிப்பு: `json-cerialization`." + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "இறுதிப்புள்ளி மாற்றங்களை பதிவேற்றவும்" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" +"\"லெகசி\" பதிவேற்ற பநிஇ தரப்படுத்தப்படவில்லை. `PYPI இன் பதிவேற்ற பநிஇ ஆவணங்கள் " +"` _ சான்றுகள் எவ்வாறு பதிவேற்றப்படுகின்றன " +"என்பதைப் பார்க்கவும்." + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "சான்றளிப்பு பொருள்கள்" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" +"ஒரு சான்றளிப்பு பொருள் என்பது பல தேவையான விசைகளைக் கொண்ட சாதொபொகு பொருள்; " +"வெளிப்படையாக பட்டியலிடப்பட்ட அனைத்து விசைகளும் வழங்கப்படும் வரை பயன்பாடுகள் அல்லது " +"கையொப்பமிட்டவர்கள் கூடுதல் விசைகளை உள்ளடக்கியிருக்கலாம். ஒரு சான்றளிப்பு பொருளின் " +"தேவையான தளவமைப்பு கீழே உள்ள சூடோகோடாக வழங்கப்படுகிறது." + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" +"`` வெளிப்படைத்தன்மை_இஎன்டரிசில் உள்ள ஒவ்வொரு பொருளுக்கும் ஒரு முழு தரவு மாதிரி " +"வழங்கப்பட்டுள்ளது: குறிப்பு: `பின் இணைப்பு`. சான்றளிப்பு பொருள்கள் ** ** ஒன்று அல்லது " +"அதற்கு மேற்பட்ட வெளிப்படைத்தன்மை பதிவு உள்ளீடுகளை உள்ளடக்கியிருக்க வேண்டும், மேலும் ** " +"கையொப்பமிடப்பட்ட நேரத்தின் பிற ஆதாரங்களுக்கான கூடுதல் விசைகளை உள்ளடக்கியிருக்கலாம் (AN: " +"RFC: `3161` நேர முத்திரையிடும் அதிகாரம் அல்லது` rogatime `__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" +"சான்றளிப்பு அறிக்கை `வி 1 இன்-டோட்டோ அறிக்கை பொருளாக வடிவம். வரிசைப்படுத்தப்பட்டால், " +"அறிக்கை ஒரு ஒளிபுகா பைனரி குமிழியாக கருதப்படுகிறது, நியமனமயமாக்கலின் தேவையைத் " +"தவிர்க்கிறது." + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" +"ஒரு வி 1 இன்-டோட்டோ அறிக்கையாக இருப்பதோடு மட்டுமல்லாமல், சான்றளிப்பு அறிக்கை பின்வரும் " +"வழிகளில் கட்டுப்படுத்தப்பட்டுள்ளது:" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "இன்-டோட்டோ `` பொருள்`` ** ** ஒரே ஒரு விசயத்தை மட்டுமே கொண்டிருக்க வேண்டும்." + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" +"`` பொருள் [0] .பெயர்`` என்பது விநியோகத்தின் கோப்பு பெயர், இது ** ** செல்லுபடியாகும்: " +"குறிப்பு: `மூல வழங்கல் <மூல-விநியோக-வடிவ>` அல்லது: குறிப்பு: `சக்கர வழங்கல் <பைனரி-" +"விநியோக-- வடிவம்> `கோப்பு பெயர்." + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" +"`` பொருள் [0] .digest`` ** கட்டாயம் ** ஒரு SHA-256 டைசெச்டைக் கொண்டிருக்க வேண்டும். " +"பிற செரிமானங்கள் ** இருக்கலாம் ** இருக்கலாம். செரிமானங்கள் ** ** எக்சாடெசிமல் சரங்களாக " +"குறிப்பிடப்பட வேண்டும்." + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "பின்வரும் `` முன்னுரிமைப் வகை`` மதிப்புகள் ஆதரிக்கப்படுகின்றன:" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr ";" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" +"`PYPI சான்றிதழை வெளியிடுங்கள் ` " +"__: `` https: // docs.pypi.org/சான்றுகள்/வெளியீடு/v1``" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" +"இந்த அறிக்கையின் கையொப்பம் `வி 1 டி.எச்.எச்.இ கையொப்ப நெறிமுறை __ உடன், ஒரு` `bayode_type` " +"`` `விண்ணப்பம்/vnd.in-toto+json`` மற்றும் ஒரு` `பேலோட்_போடி`` இன் மேலே JSON- " +"குறியிடப்பட்ட அறிக்கை. வேறு `` பேலோட்_ டைப்`` அனுமதிக்கப்படவில்லை." + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "ஆதார பொருள்கள்" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" +"மெட்டாடேட்டாவுடன் பதிவேற்றிய சான்றிதழ்களை இந்த குறியீடு வழங்கும், அவை சாதொபொகு தொடர் " +"பொருள்களின் வடிவத்தில் சரிபார்க்க உதவக்கூடும்." + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" +"இந்த * ஆதார பொருள்கள் * மேலே விவரிக்கப்பட்டுள்ளபடி எளிய குறியீட்டு மற்றும் JSON- " +"அடிப்படையிலான எளிய பநிஇ வழியாக கிடைக்கும், மேலும் பின்வரும் தளவமைப்பு இருக்கும்:" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "அல்லது, சூடோகோடாக:" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" +"`` பதிப்பு`` இது `` 1``. சான்றளிப்பு பொருள்களைப் போலவே, ஆதாரப் பொருள்களும் " +"பதிக்கப்பட்டுள்ளன, மேலும் இந்த PEP பதிப்பை `` 1`` மட்டுமே வரையறுக்கிறது." + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" +"`` சான்றளிப்பு_பண்டில்ச்`` என்பது ஒரு ** தேவை ** சாதொபொகு வரிசை, இதில் ஒன்று அல்லது " +"அதற்கு மேற்பட்ட \"மூட்டைகள்\" சான்றுகள் உள்ளன. ஒவ்வொரு மூட்டையும் கையொப்பமிடும் " +"அடையாளத்திற்கு ஒத்திருக்கிறது (நம்பகமான வெளியீட்டு அடையாளம் போன்றவை), மேலும் ஒன்று " +"அல்லது அதற்கு மேற்பட்ட சான்றளிப்பு பொருள்களைக் கொண்டுள்ளது." + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" +"`` வெளியீட்டாளர்` மாதிரியில் குறிப்பிட்டுள்ளபடி, ஒவ்வொரு `` சான்றளிப்பு. பப்ளிசர்`` " +"பொருளும் அதன் நம்பகமான வெளியீட்டாளருக்கு குறிப்பிட்டது, ஆனால் குறைந்தபட்சம் சேர்க்கப்பட " +"வேண்டும்:" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" +"ஒரு `` வகையான`` விசை, இது ** ** ஒரு சாதொபொகு சரம் இருக்க வேண்டும், இது நம்பகமான " +"வெளியீட்டாளரை தனித்துவமாக அடையாளம் காணும்." + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" +"நம்பகமான வெளியீட்டாளர் அங்கீகாரத்தின் போது குறியீட்டால் தக்கவைக்கப்பட்ட எந்தவொரு சூழல்-" +"குறிப்பிட்ட உரிமைகோரல்களையும் கொண்ட ஒரு `` உரிமைகோரல்கள்` `விசையானது ** ஒரு " +"சாதொபொகு பொருளாக இருக்க வேண்டும்." + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "வெளியீட்டாளர் பொருளின் மற்ற அனைத்து விசைகளும் வெளியீட்டாளர் சார்ந்தவை." + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" +"சான்றளிக்கும் பொருள்களின் ஒவ்வொரு வரிசையும் பதிவேற்றப்பட்ட நேரத்தில் பதிவேற்றப்பட்ட `` " +"சான்றுகள்`` வரிசையின் ஒரு சூப்பர்செட் ஆகும், இதில் விவரிக்கப்பட்டுள்ளபடி: குறிப்பு: ref: " +"`பதிவேற்ற-எண்ட் பாயிண்ட்` மற்றும்: ref:` மாற்றங்கள்- பெறுநர் avownance-bocticals`." + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "ஆதார பொருள்களில் மாற்றங்கள்" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" +"ஆதார பொருள்கள் * மாறாதவை அல்ல, காலப்போக்கில் மாறக்கூடும். ஆதாரப் பொருளில் மாற்றங்களுக்கான " +"காரணங்கள் பின்வருவனவற்றை உள்ளடக்குகின்றன, ஆனால் அவை மட்டுப்படுத்தப்படவில்லை:" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" +"முன்பே இருக்கும் கையொப்பமிடும் அடையாளத்திற்கான புதிய சான்றுகளைச் சேர்ப்பது: ஏற்கனவே " +"பதிவேற்றப்பட்ட கோப்புகளுக்கான புதிய சான்றளிப்பு பதிப்புகள் போன்ற முன்பே இருக்கும் " +"கையொப்பமிடும் அடையாளங்கள் மூலம் கூடுதல் சான்றுகளை அனுமதிக்க குறியீட்டு ** தேர்வு " +"செய்யலாம்." + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" +"புதிய கையொப்பமிடும் அடையாளங்கள் மற்றும் அதனுடன் தொடர்புடைய சான்றுகள்: குறியீட்டு ** ** " +"மூன்றாம் தரப்பு தணிக்கையாளர்கள் அல்லது குறியீட்டு போன்ற கோப்பின் பதிவேற்றியவரைத் தவிர வேறு " +"மூலங்களிலிருந்து சான்றுகளை ஆதரிக்க ** தேர்வு செய்யலாம். இந்த சான்றுகள் ஒத்திசைவற்ற " +"முறையில் செய்யப்படலாம், அவற்றை ஆதாரப் பொருளில் செருக குறியீடு தேவைப்படுகிறது *பிந்தைய " +"உண்மை *." + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "சான்றளிப்பு சரிபார்ப்பு" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" +"ஒரு விநியோக கோப்புக்கு எதிராக ஒரு சான்றளிப்பு பொருளை சரிபார்க்க பின்வருவனவற்றில் " +"சரிபார்ப்பு தேவைப்படுகிறது:" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" +"`` பதிப்பு`` இது `` 1``. சரிபார்ப்பு ** ** வேறு எந்த பதிப்பையும் நிராகரிக்க வேண்டும்." + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "`` சரிபார்ப்பு_மாட்டியல்." + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "`` சரிபார்ப்பு_மாட்டியல்." + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" +"`` உறை. விநியோகத்தின் கோப்பு பெயருக்கு, பொருத்தமான ** பொருத்தமான மூல வழங்கல் அல்லது " +"சக்கர கோப்பு பெயர் வடிவமைப்பைப் பயன்படுத்தி பாகுபடுத்துவதன் மூலம் ** செய்யப்பட வேண்டும், " +"ஏனெனில் அறிக்கையின் பொருள் சமமாக இருக்கலாம் ஆனால் இயல்பாக்கப்படலாம்." + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" +"`` v1 dsse கையொப்பம் நெறிமுறை` `` உறை. __." + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" +"மேலே தேவையான படிகளுக்கு கூடுதலாக, ஒரு சரிபார்ப்பு ** ** கூடுதலாக கொள்கை " +"அடிப்படையில் `` சரிபார்ப்பு_மாட்டியல். குறைந்தது ஒரு வெளிப்படைத்தன்மை பதிவு நுழைவு " +"அல்லது உள்ளீடுகளின் நுழைவு தேவை. வெளிப்படைத்தன்மை உள்ளீடுகளை சரிபார்க்கும்போது, " +"சரிபார்ப்பு ** ஒவ்வொரு நுழைவுக்கும் சேர்க்கும் நேரம் கையொப்பமிடும் சான்றிதழின் " +"செல்லுபடியாகும் காலத்திற்குள் இருப்பதை உறுதிப்படுத்த வேண்டும்." + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "பின் இணைப்பு: வெளிப்படைத்தன்மை பதிவு உள்ளீடுகளுக்கான தரவு மாதிரிகள்" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" +"இந்த பிற்சேர்க்கையில் சான்றளிப்பு பொருள்களில் வெளிப்படைத்தன்மை பதிவு உள்ளீடுகளுக்கான போலி " +"தரவு மாதிரிகள் உள்ளன. ஒவ்வொரு வெளிப்படைத்தன்மை பதிவு நுழைவும் கையொப்பமிடப்பட்ட சேர்க்கை " +"நேரத்தின் ஆதாரமாக செயல்படுகிறது, மேலும் ஆன்லைனில் அல்லது ஆஃப்லைனில் சரிபார்க்கலாம்." + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "இன்லைன் ச்கிரிப்ட் மேனிலை தரவு" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" +"இந்த விவரக்குறிப்பு ஒரு மேனிலை தரவு கருத்து தொகுதி வடிவமைப்பை வரையறுக்கிறது " +"(`மறுசீரமைப்பு டெக்ச்ட் டைரெக்டிவ்ச்`__ ஆல் ஈர்க்கப்பட்டது)." + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" +"இந்த இரண்டு வரிகளுக்கிடையேயான ஒவ்வொரு வரியும் (``# /// type`` மற்றும் ``# /// `)` " +"`#` `உடன் தொடங்கும் கருத்தாக இருக்க வேண்டும். ``#`` க்குப் பிறகு எழுத்துக்கள் இருந்தால், " +"முதல் எழுத்து ஒரு இடமாக இருக்க வேண்டும். இரண்டாவது எழுத்து ஒரு இடமாக இருந்தால் ஒவ்வொரு " +"வரியின் முதல் இரண்டு எழுத்துக்களை எடுத்துச் செல்வதன் மூலம் உட்பொதிக்கப்பட்ட உள்ளடக்கம் " +"உருவாகிறது, இல்லையெனில் முதல் எழுத்து (இதன் பொருள் வரி ஒரே ஒரு ``#``) மட்டுமே உள்ளது." + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" +"மேலே விவரிக்கப்பட்டுள்ளபடி அடுத்த வரி செல்லுபடியாகும் உட்பொதிக்கப்பட்ட உள்ளடக்க வரியாக " +"இல்லாதபோது ``# /// `` ஒரு இறுதி வரிக்கான முன்னுரிமை வழங்கப்படுகிறது. " +"எடுத்துக்காட்டாக, பின்வருபவை முழுமையாக செல்லுபடியாகும் தொகுதி:" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" +"மற்றொரு தொடக்க வரிக்கும் அதன் முடிவுக் கோட்டிற்கும் இடையில் ஒரு தொடக்க வரி " +"வைக்கப்படக்கூடாது. இதுபோன்ற சந்தர்ப்பங்களில் கருவிகள் பிழையை உருவாக்கக்கூடும். திறக்கப்படாத " +"தொகுதிகள் புறக்கணிக்கப்பட வேண்டும்." + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" +"ஒரே `` வகை`` வரையறுக்கப்பட்ட பல கருத்துத் தொகுதிகள் இருக்கும்போது, கருவிகள் பிழையை " +"உருவாக்க வேண்டும்." + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" +"கருவிகள் படித்தல் உட்பொதிக்கப்பட்ட மேனிலை தரவு நிலையான பைதான் குறியாக்க அறிவிப்பை " +"மதிக்கலாம். அவ்வாறு செய்ய வேண்டாம் என்று அவர்கள் தேர்வுசெய்தால், அவர்கள் கோப்பை யுடிஎஃப் -8 " +"ஆக செயலாக்க வேண்டும்." + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "மெட்டாடேட்டாவை அலசுவதற்குப் பயன்படுத்தக்கூடிய நியமன வழக்கமான வெளிப்பாடு இது:" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" +"உரை விவரக்குறிப்புக்கும் வழக்கமான வெளிப்பாட்டிற்கும் இடையில் முரண்பாடு உள்ள சூழ்நிலைகளில், " +"உரை விவரக்குறிப்பு முன்னுரிமை பெறுகிறது." + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" +"இந்த விவரக்குறிப்பால் தரப்படுத்தப்படாத வகைகளைக் கொண்ட மேனிலை தரவு தொகுதிகளிலிருந்து " +"கருவிகள் படிக்கக்கூடாது." + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "ச்கிரிப்ட் வகை" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" +"முதல் வகை மேனிலை தரவு தொகுதி `` ச்கிரிப்ட்`` என்று பெயரிடப்பட்டுள்ளது, இதில் ச்கிரிப்ட் " +"மேனிலை தரவு (சார்பு தரவு மற்றும் கருவி உள்ளமைவு) உள்ளது." + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" +"இந்த ஆவணத்தில் `` சார்புநிலைகள்`` மற்றும் `` தேவைப்படுகிறது-பைதான் `` `[கருவி]` " +"`அட்டவணையை சேர்க்கலாம்." + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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 "" +"நடத்தையை உள்ளமைக்க `` [கருவி] `` அட்டவணை எந்தவொரு கருவி, ச்கிரிப்ட் ரன்னர் அல்லது " +"வேறுவிதமாக பயன்படுத்தப்படலாம். இது அதே சொற்பொருளைக் கொண்டுள்ளது: ref: `[கருவி] " +"அட்டவணை pyproject.toml `." + +#: ../source/specifications/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "உயர்மட்ட புலங்கள்:" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" +"`` சார்புநிலைகள்``: ச்கிரிப்ட்டின் இயக்க நேர சார்புகளைக் குறிப்பிடும் சரங்களின் பட்டியல். " +"ஒவ்வொரு நுழைவும் செல்லுபடியாகும்: ref: `சார்பு விவரக்குறிப்பு <சார்பு-" +"விவரக்குறிப்புகள்>`." + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" +"``-பைதான் தேவை` ``: ச்கிரிப்ட் இணக்கமான பைதான் பதிப்பை (களை) குறிப்பிடும் ஒரு சரம். " +"இந்த புலத்தின் மதிப்பு செல்லுபடியாகும்: ref: `பதிப்பு விவரக்குறிப்பு <பதிப்பு-" +"விவரக்குறிப்புகள்>`." + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" +"குறிப்பிட்ட `` சார்புநிலைகள்`` வழங்க முடியாவிட்டால் ச்கிரிப்ட் ஓட்டப்பந்தய வீரர்கள் பிழையாக " +"வேண்டும். குறிப்பிட்ட `` தேவைகள் தேவைப்படும் பைதானின் பதிப்பு எதுவும் வழங்கப்படாவிட்டால் " +"ச்கிரிப்ட் ஓட்டப்பந்தய வீரர்கள் பிழையாக இருக்க வேண்டும்." + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "உட்பொதிக்கப்பட்ட மேனிலை தரவு கொண்ட ச்கிரிப்ட்டின் எடுத்துக்காட்டு பின்வருமாறு:" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" +"பைதான் 3.11 அல்லது அதற்கு மேற்பட்ட மெட்டாடேட்டாவை எவ்வாறு படிப்பது என்பதற்கு பின்வருபவை " +"ஒரு எடுத்துக்காட்டு." + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" +"பெரும்பாலும் கருவிகள் தொகுப்பு மேலாளர்கள் அல்லது தொஒ இல் சார்பு புதுப்பிப்பு ஆட்டோமேசன் " +"போன்ற சார்புகளைத் திருத்தும். `` டாம்ல்கிட்`` நூலகத்தைப் பயன்படுத்தி உள்ளடக்கத்தை " +"மாற்றுவதற்கான ஒரு கச்சா எடுத்துக்காட்டு பின்வருமாறு." + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" +"இந்த எடுத்துக்காட்டு டாம்ல் வடிவமைப்பைப் பாதுகாக்கும் ஒரு நூலகத்தைப் பயன்படுத்தியது என்பதை " +"நினைவில் கொள்க. இது எந்த வகையிலும் திருத்துவதற்கான தேவை அல்ல, மாறாக \"இருப்பது " +"நல்லது\" அம்சமாகும்." + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" +"தன்னிச்சையான மேனிலை தரவு தொகுதிகளின் ச்ட்ரீமை எவ்வாறு படிப்பது என்பதற்கு பின்வருபவை ஒரு " +"எடுத்துக்காட்டு." + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "பரிந்துரைகள்" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" +"பைத்தானின் வெவ்வேறு பதிப்புகளை நிர்வகிப்பதை ஆதரிக்கும் கருவிகள், ச்கிரிப்டின் ``-பைதான்`` " +"மெட்டாடேட்டாவுடன் பொருந்தக்கூடிய பைத்தானின் மிக உயர்ந்த பதிப்பைப் பயன்படுத்த முயற்சிக்க " +"வேண்டும்." + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "அக்டோபர் 2023: இந்த விவரக்குறிப்பு நிபந்தனையுடன் அங்கீகரிக்கப்பட்டது: PEP: `723`." + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" +"சனவரி 2024: திருத்தங்கள் மூலம்: PEP: `723`,` `பைபிரோசெக்ட்`` மேனிலை தரவு பிளாக் " +"வகை` `ச்கிரிப்ட்`` என மறுபெயரிடப்பட்டது, மற்றும்` `ரன்]` `அட்டவணை கைவிடப்பட்டது,` " +"`சார்புகளை உருவாக்கியது `மற்றும்` `-பைதான்`` விசைகள் முதல் நிலை தேவை. கூடுதலாக, " +"விவரக்குறிப்பு இனி தற்காலிகமாக இல்லை." + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +#, fuzzy +#| msgid "Some additional examples of valid ``License-Expression`` values:" +msgid "Examples of valid license expressions:" +msgstr "" +"செல்லுபடியாகும் `` உரிம-வெளிப்பாடு`` மதிப்புகளின் சில கூடுதல் எடுத்துக்காட்டுகள்:" + +#: ../source/specifications/license-expression.rst:45 +#, fuzzy +#| msgid "Some additional examples of valid ``License-Expression`` values:" +msgid "Examples of invalid license expressions:" +msgstr "" +"செல்லுபடியாகும் `` உரிம-வெளிப்பாடு`` மதிப்புகளின் சில கூடுதல் எடுத்துக்காட்டுகள்:" + +#: ../source/specifications/name-normalization.rst:3 +msgid "Names and normalization" +msgstr "பெயர்கள் மற்றும் இயல்பாக்கம்" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" +"தொகுப்புகள் மற்றும் கூடுதல் அம்சங்களுக்கான பெயர்கள் பின்பற்ற வேண்டிய வடிவமைப்பை இந்த " +"விவரக்குறிப்பு வரையறுக்கிறது. அவற்றை எவ்வாறு இயல்பாக்குவது என்பதையும் இது " +"விவரிக்கிறது, இது தேடல்கள் மற்றும் ஒப்பீடுகளுக்கு முன் செய்யப்பட வேண்டும்." + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "பெயர் வடிவம்" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" +"செல்லுபடியாகும் பெயர் ASCII கடிதங்கள் மற்றும் எண்கள், காலம், அடிக்கோடிட்டு மற்றும் ஐபன் " +"ஆகியவற்றைக் கொண்டுள்ளது. இது ஒரு கடிதம் அல்லது எண்ணுடன் தொடங்கி முடிக்க வேண்டும். இதன் " +"பொருள் செல்லுபடியாகும் திட்ட பெயர்கள் பின்வரும் ரீசெக்சுடன் பொருந்தக்கூடியவற்றுடன் " +"மட்டுப்படுத்தப்பட்டுள்ளன (இயங்கும்: PY: தரவு: `Re.ignorecase`) ::" + +#: ../source/specifications/name-normalization.rst:26 +msgid "Name normalization" +msgstr "பெயர் இயல்பாக்குதல்" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" +"```,` `-``, அல்லது` `_`` ஒரு ஒற்றை` `-`` எழுத்துடன் மாற்றப்பட்ட எழுத்துக்களின் அனைத்து " +"ரன்களிலும் பெயர் குறைவாக இருக்க வேண்டும். இதை RE தொகுதிக்கு பைதானில் செயல்படுத்தலாம்:" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "இதன் பொருள் பின்வரும் பெயர்கள் அனைத்தும் சமமானவை:" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "`` நட்பு-கார்ட்`` (இயல்பாக்கப்பட்ட வடிவம்)" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "`` நட்பு-கார்ட்``" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "`` நட்பு-கார்ட்``" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "`` நட்பு. பார்ட்``" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "`` நட்பு_பார்ட்``" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "`` நட்பு-பார்ட்``" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" +"`` நட்பு -._.- பார்ட்`` (ஒரு பெயரை எழுத ஒரு * பயங்கரமான * வழி, ஆனால் அது " +"செல்லுபடியாகும்)" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" +"செப்டம்பர் 2015: இயல்பாக்கப்பட்ட பெயரின் விவரக்குறிப்பு மூலம் அங்கீகரிக்கப்பட்டது: PEP: `503 " +"<503#இயல்பாக்கப்பட்ட-பெயர்கள்>`." + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" +"நவம்பர் 2015: செல்லுபடியாகும் பெயர்களின் விவரக்குறிப்பு அங்கீகரிக்கப்பட்டது: PEP: `508 " +"<508#பெயர்கள்>`." + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "இயங்குதள பொருந்தக்கூடிய குறிச்சொற்கள்" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" +"இயங்குதள பொருந்தக்கூடிய குறிச்சொற்கள் குறிப்பிட்ட தளங்களுடன் பொருந்தக்கூடியதாக இருப்பதைக் " +"குறிக்க கருவிகளை உருவாக்க அனுமதிக்கின்றன, மேலும் அவை இயங்கும் கணினியுடன் எந்த " +"விநியோகங்கள் இணக்கமாக உள்ளன என்பதை நிறுவிகள் புரிந்துகொள்ள அனுமதிக்கிறது." + +#: ../source/specifications/platform-compatibility-tags.rst: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 "பைதான் குறிச்சொல்" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "அப்பாக், நிரம்பியுள்ளது" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "'cp32dmu', 'எதுவுமில்லை'" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "'லினக்ச்_எக்ச் 86_64', 'ஏதேனும்'" + +#: ../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-`` என்ற குறிச்சொல் பைதான் 2.7 (எந்த பைதான் 2.7 " +"செயல்படுத்தல்) உடன் பொருந்தக்கூடிய தன்மையைக் குறிக்கிறது, எந்தவொரு தளத்திலும் பநிஇ தேவை " +"இல்லை." + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" +"`` சக்கரம்`` கட்டப்பட்ட தொகுப்பு வடிவத்தில் இந்த குறிச்சொற்கள் அதன் கோப்பு பெயர்களில், " +"`{distribution}-{version} (-{build tag})? .whl``. பிற தொகுப்பு வடிவங்களில் " +"அவற்றின் சொந்த மரபுகள் இருக்கலாம்." + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" +"எந்தவொரு குறிச்சொல்லிலும் உள்ள எந்த சாத்தியமான இடங்களும் `` _`` உடன் மாற்றப்பட வேண்டும்." + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "பைதான் குறிச்சொல்" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" +"பைதான் குறிச்சொல் ஒரு விநியோகத்தால் தேவைப்படும் செயல்படுத்தல் மற்றும் பதிப்பைக் " +"குறிக்கிறது. முக்கிய செயலாக்கங்கள் ஆரம்பத்தில் சுருக்கமான குறியீடுகளைக் கொண்டுள்ளன:" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "PY: பொதுவான பைதான் (செயல்படுத்தல்-குறிப்பிட்ட நற்பொருத்தங்கள் தேவையில்லை)" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "சிபி: cpython" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "ஐபி: அயர்ன் பிதான்" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "பிபி: பைபி" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "நீங்கள்: உத்தான்" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" +"பிற பைதான் செயலாக்கங்கள் பயன்படுத்தப்பட வேண்டும்: PY: தரவு: `sys.implementation.name " +"`." + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" +"பதிப்பு `` py_version_nodot``. சிபிதான் எந்த புள்ளியும் இல்லாமல் விலகிச் செல்கிறது, " +"ஆனால் ஒருவருக்கு தேவைப்பட்டால் அடிக்கோடிட்ட `` _`` அதற்கு பதிலாக பயன்படுத்தப்படுகிறது. " +"பைபி தனது சொந்த பதிப்புகளை இங்கே `` பிபி 18``, `` பிபி 19`` பயன்படுத்த வேண்டும்." + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" +"பல தூய-பைதான் விநியோகங்களுக்கு `` 2` அல்லது `` 3` `` py2``, `` 3` `` py2`` என்ற " +"முக்கிய பதிப்பாக பதிப்பு இருக்க முடியும்." + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" +"முக்கியமாக, `` py2`` மற்றும் `py3` போன்ற முக்கிய-பதிப்பு-மட்டும் குறிச்சொற்கள்` `py20`` " +"மற்றும்` `py30`` ஆகியவற்றுக்கு சுருக்கெழுத்து அல்ல. அதற்கு பதிலாக, இந்த குறிச்சொற்கள் " +"பேக்கேசர் வேண்டுமென்றே குறுக்கு-பதிப்பு-இணக்கமான விநியோகத்தை வெளியிட்டன." + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" +"ஒற்றை மூல பைதான் 2/3 இணக்கமான வழங்கல் `` py2.py3`` என்ற கலவை குறிச்சொல்லைப் " +"பயன்படுத்தலாம். கீழே `சுருக்கப்பட்ட குறிச்சொல் தொகுப்புகள்`_ ஐப் பார்க்கவும்." + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "அபி நாள்" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" +"சேர்க்கப்பட்ட எந்தவொரு நீட்டிப்பு தொகுதிகளுக்கும் பைதான் பநிஇ தேவை என்பதை பநிஇ குறிச்சொல் " +"குறிக்கிறது. செயல்படுத்தல்-குறிப்பிட்ட ABI கள், செயல்படுத்தல் பைதான் குறிச்சொல்லைப் போலவே " +"சுருக்கமாக உள்ளது, எ.கா. `` cp33d`` பிழைத்திருத்தத்துடன் சிபிதான் 3.3 பநிஇ இருக்கும்." + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "பகிரப்பட்ட நூலக பின்னொட்டைப் போலவே `` abi3`` என்பது cpython stable abi ஆகும்." + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" +"மிகவும் நிலையற்ற பநிஇ கொண்ட செயலாக்கங்கள் அவற்றின் மூலக் குறியீடு திருத்தம் மற்றும் கம்பைலர் " +"கொடிகள் போன்ற SHA-256 ஆசின் முதல் 6 பைட்டுகளை (8 பேச் 64-குறியிடப்பட்ட எழுத்துக்களாக) " +"பயன்படுத்தலாம், ஆனால் பைனரி விநியோகங்களை விநியோகிக்க அதிக தேவை இருக்காது. ஒவ்வொரு " +"செயல்படுத்தலின் சமூகமும் பநிஇ குறிச்சொல்லை எவ்வாறு சிறப்பாகப் பயன்படுத்துவது என்பதை " +"தீர்மானிக்கலாம்." + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "இயங்குதள குறிச்சொல்" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "அடிப்படை இயங்குதள குறிச்சொற்கள்" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" +"அதன் எளிமையான வடிவத்தில், இயங்குதள குறிச்சொல்: py: func: `sysconfig.get_platform " +"()` எல்லா ஐபன்களுடனும் `` --`` மற்றும் காலகட்டங்கள் `` `.`` அடிக்கோடிட்ட` `_`` உடன் " +"மாற்றப்பட்டது. அகற்றும் வரை: குறிப்பு: பைதான் 3.12 இல் `தொலைதூரங்கள்`, இது` " +"`distutils.util.get_platform ()` `. உதாரணமாக:" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "அது" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "லினக்ச்_ஐ 386" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "லினக்ச்_எக்ச் 86_64" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "`` மேனிலினக்ச்``" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" +"லினக்ச் தளங்களின் பெரிய சுற்றுச்சூழல் அமைப்பு மற்றும் அவற்றுக்கிடையேயான நுட்பமான " +"வேறுபாடுகள் காரணமாக, லினக்ச் தளங்களுக்கு சக்கர கோப்புகளை பொது விநியோகத்திற்கு மேலே " +"உள்ள எளிய திட்டம் போதுமானதாக இல்லை." + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" +"அதற்கு பதிலாக, அந்த தளங்களுக்கு, `` மேனிலினக்ச்`` தரநிலை லினக்ச் தளங்களின் பொதுவான " +"துணைக்குழுவைக் குறிக்கிறது, மேலும் `` மேனிலினக்ச்`` இயங்குதள குறிச்சொல்லுடன் " +"குறிக்கப்பட்ட சக்கரங்களை உருவாக்க அனுமதிக்கிறது, இது மிகவும் பொதுவான லினக்ச் " +"விநியோகங்களில் பயன்படுத்தப்படலாம்." + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" +"பின்தங்கிய பொருந்தக்கூடிய தன்மைக்கு பின்வரும் பழைய குறிச்சொற்கள் இன்னும் ஆதரிக்கப்படுகின்றன:" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" +"`` X86_64`` மற்றும் `i686`` கட்டமைப்புகளில்` `மேனிலினக்ச் 1`` கிளிப் 2.5 ஐ " +"ஆதரிக்கிறது." + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" +"`` x86_64`` மற்றும் `` i686`` ஆகியவற்றில் `` மேனிலினக்ச் 2010`` கிளிப் 2.12 ஐ " +"ஆதரிக்கிறது." + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" +"`` X86_64``, `` i686``, `` aarch64``, `` ARMV7l``, `` பிபிசி 64``, `` பிபிசி " +"64le`` `." + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "பொதுவாக. 2010 க்கு முன்னர் இருந்த தளங்களில் வேலை செய்யுங்கள்)." + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" +"`` மேனிலினக்ச் 1` மற்றும் `` மேனிலினக்ச் 2010`` ஆகியவற்றிற்கான வழங்கப்பட்ட உருவாக்க " +"சூழலை உருவாக்கிய சூழலை வாழ்நாள் முழுவதும் அடைந்துவிட்டது என்ற எச்சரிக்கையுடன், தொகுப்பு " +"பராமரிப்பாளர்கள் மிகவும் இணக்கமான விவரக்குறிப்பை குறிவைக்க முயற்சிக்க வேண்டும், அதாவது " +"இந்த படங்கள் இனி பாதுகாப்பு புதுப்பிப்புகளைப் பெறாது." + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" +"பின்வரும் அட்டவணை பல்வேறு `` மேனிலினக்ச்`` தரங்களை ஆதரிக்க தொடர்புடைய திட்டங்களின் " +"குறைந்தபட்ச பதிப்புகளைக் காட்டுகிறது:" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "கருவி" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "`` Mantinux1``" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "`` Mantinux2010 `" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "`` மேனிலினக்ச் 2014``" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "`` manylinux_x_y``" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "``> = 8.1.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "``> = 19.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "``> = 19.3``" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "``> = 20.3``" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "தணிக்கை" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "``> = 1.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "``> = 2.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "``> = 3.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "``> = 3.3.0`` [#] _" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "`` மேனிலினக்ச்_2_24`` க்கான உதவி மட்டுமே தணிக்கைக்கு 3.3.0 இல் சேர்க்கப்பட்டுள்ளது" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "`` musllinux``" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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 "" +"MSL பதிப்பு மதிப்புகளைப் பெறலாம் MSL LIBC பகிரப்பட்ட நூலகத்தை இயக்குவதன் மூலம் பைதான் " +"மொழிபெயர்ப்பாளர் தற்போது இயங்குகிறார், மேலும் வெளியீட்டை பாகுபடுத்துகிறார்:" + +#: ../source/specifications/platform-compatibility-tags.rst:193 +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 "" +"ஒரு பைதான் மொழிபெயர்ப்பாளர் இயங்கும் MSL நூலகத்தின் இருப்பிடத்தைக் கண்டுபிடிக்க தற்போது " +"இரண்டு வழிகள் உள்ளன, இது கணினி LDD_ கட்டளையுடன் அல்லது இயங்கக்கூடிய ELF_ " +"தலைப்பிலிருந்து `` PT_INTERP`` பிரிவின் மதிப்பை பாகுபடுத்துவதன் மூலம்." + +#: ../source/specifications/platform-compatibility-tags.rst:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "பயன்படுத்தவும்" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" +"சாத்தியமான கட்டமைக்கப்பட்ட விநியோகங்களின் பட்டியலிலிருந்து பதிவிறக்கம் செய்ய எந்த " +"கட்டமைக்கப்பட்ட வழங்கல் (ஏதேனும் இருந்தால்) என்பதை தீர்மானிக்க குறிச்சொற்கள் நிறுவிகளால் " +"பயன்படுத்தப்படுகின்றன. நிறுவி ஆதரிக்கும் (பைவர், பநிஇ, ஆர்ச்) டூப்பிள்களின் பட்டியலை " +"பராமரிக்கிறது. கட்டப்பட்ட விநியோகத்தின் குறிச்சொல் `` இன்` பட்டியலில் இருந்தால், அதை " +"நிறுவலாம்." + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" +"பழைய பைதான் வெளியீடுகளுக்காக வெளியிடப்பட்ட தூய பைதான் பதிப்புகளுக்குத் திரும்புவதற்கு " +"முன், இயல்புநிலையாக கிடைக்கக்கூடிய மிக அம்சமான கட்டமைக்கப்பட்ட விநியோகத்தை (நிறுவல் " +"சூழலுக்கு மிகவும் குறிப்பிட்டது) தேர்வு செய்ய நிறுவல்கள் பரிந்துரைக்கப்படுகின்றன. " +"அனுமதிக்கப்பட்ட பொருந்தக்கூடிய குறிச்சொற்களின் பட்டியலை உள்ளமைக்கவும் மீண்டும் ஆர்டர் செய்யவும் " +"ஒரு வழியை வழங்க நிறுவிகள் பரிந்துரைக்கப்படுகின்றன; எடுத்துக்காட்டாக, ஒரு பயனர் தங்களை " +"தூய பைத்தான் என்று விளம்பரப்படுத்தும் கட்டப்பட்ட தொகுப்புகளை மட்டுமே பதிவிறக்குவதற்கு ``*-" +"ஒரு-எந்த` குறிச்சொற்களை மட்டுமே ஏற்றுக்கொள்ளலாம்." + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" +"மற்றொரு விரும்பத்தக்க நிறுவி நற்பொருத்தம், \"முடிந்தால் மூலத்திலிருந்து மீண்டும் இணைத்தல்\" " +"என்பது இணக்கமான ஆனால் மரபு முன்பே கட்டப்பட்ட சில விருப்பங்களை விட மிகவும் " +"விரும்பத்தக்கதாக இருக்கும்." + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" +"இந்த எடுத்துக்காட்டு பட்டியல் லினக்ச்_எக்ச் 86_64 கணினியில் CPyThon 3.3 இன் கீழ் இயங்கும் " +"நிறுவிக்கு. இது பெரும்பாலான விருப்பமான (ஒரு தொகுக்கப்பட்ட நீட்டிப்பு தொகுதியுடன் ஒரு " +"வழங்கல், பைத்தானின் தற்போதைய பதிப்பிற்காக கட்டப்பட்டுள்ளது) குறைந்தது-விருப்பமான " +"(பைத்தானின் பழைய பதிப்பைக் கொண்டு கட்டப்பட்ட தூய-பைதான் விநியோகம்):" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "CP33-CP33M-LINUX_X86_64" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "CP33-ABI3-LINUX_X86_64" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "CP3-ABI3-LINUX_X86_64" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "cp33-none-linux_x86_64*" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "cp3-none-linux_x86_64*" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "py33-none-linux_x86_64*" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "py3-none-linux_x86_64*" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "CP33-NONE-ANY" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "CP3-none-any-any" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "py33-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "py3-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "py32-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "py31-none-any" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "py30-none-any- any" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" +"சி நீட்டிப்புகளைத் தவிர வேறு காரணங்களுக்காக கட்டப்பட்ட விநியோகங்கள் குறிப்பிட்ட தளமாக " +"இருக்கலாம், அதாவது ஒரு துணை செயலாக்கமாக செயல்படுத்தப்பட்ட ஒரு சொந்த இயங்கக்கூடியவை." + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" +"சில நேரங்களில் ஒரு தொகுப்பின் ஒரு குறிப்பிட்ட பதிப்பிற்கு ஒன்றுக்கு மேற்பட்ட உதவி " +"கட்டப்பட்ட வழங்கல் இருக்கும். எடுத்துக்காட்டாக, ஒரு பேக்கேசர் ஒரு விருப்பமான சி நீட்டிப்பு " +"மற்றும் அதே வழங்கல் குறிக்கப்பட்ட `` py3-none-any`` ஆகியவற்றைக் கொண்ட `` CP33-ABI3-" +"LINUX_X86_64`` குறிக்கப்பட்ட ஒரு தொகுப்பை வெளியிட முடியும். ஆதரிக்கப்பட்ட குறிச்சொற்கள் " +"பட்டியலில் உள்ள குறிச்சொல்லின் குறியீடு டை உடைக்கிறது, மேலும் சி நீட்டிப்புடன் கூடிய " +"தொகுப்பு இல்லாமல் தொகுப்புக்கு முன்னுரிமை அளிக்கப்பட்டுள்ளது, ஏனெனில் அந்த குறிச்சொல் " +"முதலில் பட்டியலில் தோன்றும்." + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "சுருக்கப்பட்ட குறிச்சொல் தொகுப்புகள்" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +#, fuzzy +#| 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::" +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" +"ஒன்றுக்கு மேற்பட்ட பொருந்தக்கூடிய குறிச்சொல்லுடன் பணிபுரியும் BDISTS இன் சிறிய கோப்பு " +"பெயர்களை அனுமதிக்க, ஒரு கோப்பு பெயரில் உள்ள ஒவ்வொரு குறிச்சொல்லும் அதற்கு பதிலாக '.'- " +"பிரிக்கப்பட்ட, வரிசைப்படுத்தப்பட்ட, குறிச்சொற்களின் தொகுப்பாக இருக்கலாம். எடுத்துக்காட்டாக, " +"ஒரே மூலக் குறியீட்டைக் கொண்டு பைதான் 2 மற்றும் 3 இன் கீழ் இயக்க எழுதப்பட்ட ஒரு தூய-பைதான் " +"தொகுப்பு, `` py2.py3-none-any`` என்ற குறிச்சொல்லுடன் ஒரு BDIST ஐ விநியோகிக்க " +"முடியும். எளிய குறிச்சொற்களின் முழு பட்டியல் ::" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" +"இந்த திட்டத்தை செயல்படுத்தும் ஒரு BDIST வடிவத்தில் BDIST- குறிப்பிட்ட மெட்டாடேட்டாவில் " +"விரிவாக்கப்பட்ட குறிச்சொற்கள் இருக்க வேண்டும். இந்த சுருக்கத் திட்டம் அதிக எண்ணிக்கையிலான " +"ஆதரிக்கப்படாத குறிச்சொற்கள் மற்றும் பைதான் செயல்படுத்தல் இல்லாத \"சாத்தியமற்ற\" " +"குறிச்சொற்களை உருவாக்க முடியும் எ.கா. \"CP33-CP31U-WIN64\", எனவே அதை குறைவாகப் " +"பயன்படுத்துங்கள்." + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "முன்னிருப்பாக என்ன குறிச்சொற்கள் பயன்படுத்தப்படுகின்றன?" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +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-wone`` இயல்பாக. பேக்கேசர் இயல்புநிலையை மீறினால், அவை குறுக்கு-பைத்தான் " +"பொருந்தக்கூடிய தன்மையை வழங்க விரும்பியதைக் குறிக்கிறது." + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" +"எனது வழங்கல் பைத்தானின் புதிய பதிப்பிற்கு பிரத்யேகமான அம்சத்தைப் பயன்படுத்தினால் நான் என்ன " +"குறிச்சொல்லைப் பயன்படுத்துகிறேன்?" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" +"பொருந்தக்கூடிய குறிச்சொற்கள் ஒரு விநியோகத்தின் * ஒற்றை பதிப்பின் * மிகவும் இணக்கமான * " +"கட்டமைப்பைத் தேர்ந்தெடுப்பதில் நிறுவிகளுக்கு உதவுகின்றன. எடுத்துக்காட்டாக, பைதான் 3.3 " +"இல்லாதபோது `` பீக்லெவோட் -1.2.0`` (இது ஒரு பைதான் 3.4 பிரத்தியேக அம்சத்தைப் " +"பயன்படுத்துகிறது) இது `` py3-none-any- `` குறிச்சொல்லைப் பயன்படுத்தலாம் py34-none-" +"any` குறிச்சொல். ஒரு பைதான் 3.3 பயனர் பழைய வெளியீட்டுக்கான தேவை போன்ற பிற தகுதிகளை " +"இணைக்க வேண்டும் `` பீகிள்வோட் -1.1.0`` இது புதிய அம்சத்தைப் பயன்படுத்தாதது, இணக்கமான " +"கட்டமைப்பைப் பெற." + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "பைதான் பதிப்பு எண்ணில் ஏன் `` .`` இல்லை?" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" +"3 இலக்க பெரிய வெளியீடு இல்லாமல் CPyThon 20+ ஆண்டுகள் நீடித்தது. இது சிறிது நேரம் தொடர " +"வேண்டும். மற்ற செயலாக்கங்கள் _ இரண்டையும் ஒரு டிலிமிட்டராகப் பயன்படுத்தலாம் - மற்றும். " +"சுற்றியுள்ள கோப்பு பெயரை வரையறுக்கவும்." + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "ஐபன்கள் மற்றும் பிற ஆல்பனுமெரிக் அல்லாத எழுத்துக்களை அடிக்கோடிட்டுக் காட்டுவது ஏன்?" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" +"கோப்பு பெயரின் கூறுகளை பிரிக்கும் `` .` மற்றும் `` --`` எழுத்துக்களுடன் முரண்படுவதைத் " +"தவிர்ப்பதற்கும், கோப்பு பெயர்களுக்கான பரந்த அளவிலான கோப்பு முறைமை வரம்புகளுடன் சிறந்த " +"பொருந்தக்கூடிய தன்மைக்கும் (மேற்கோள் காட்டாமல் முகவரி பாதைகளில் பயன்படுத்தக்கூடியது உட்பட)." + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "`` .` அல்லது `` -`` ஐ விட சிறப்பு எழுத்தை ஏன் பயன்படுத்தக்கூடாது?" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" +"அந்த தன்மை சில சூழல்களில் சிரமமாக அல்லது குழப்பமானதாக இருப்பதால் (எடுத்துக்காட்டாக, " +"``+`` முகவரி களில் மேற்கோள் காட்டப்பட வேண்டும், `` `` பயனரின் வீட்டு கோப்பகத்தை POSIX இல் " +"குறிக்கப் பயன்படுகிறது), அல்லது 4 டாலர், PERATER க்குள் மாற்றுவதற்கு போதுமானதாக இல்லை " +"என்பதால், `` `பயன்படுத்தப்படுகிறது. சுருக்கப்பட்ட குறிச்சொல்லில் கூறுகளை பிரிக்க `` `.` " +"ஐ விட` `)." + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "சுருக்கமான செயலாக்கங்களின் பதிவேட்டை யார் பராமரிப்பார்கள்?" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" +"பைதான்-டெவ் அஞ்சல் பட்டியலில் புதிய இரண்டு-எழுத்து சுருக்கங்களை கோரலாம். கட்டைவிரல் " +"விதியாக, தற்போதைய 4 மிக முக்கியமான செயலாக்கங்களுக்கு சுருக்கங்கள் ஒதுக்கப்பட்டுள்ளன." + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "பொருந்தக்கூடிய குறிச்சொல் மேனிலை தரவு அல்லது பி.கே.சி-இன்ஃபோவுக்குச் செல்கிறதா?" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" +"இல்லை. பொருந்தக்கூடிய குறிச்சொல் கட்டப்பட்ட விநியோகத்தின் மெட்டாடேட்டாவின் ஒரு " +"பகுதியாகும். மேனிலை தரவு / பி.கே.சி-இன்ஃபோ ஒரு முழு விநியோகத்திற்கும் " +"செல்லுபடியாகும், அந்த விநியோகத்தின் ஒரு கட்டமைப்பும் கூட இல்லை." + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "எனக்கு பிடித்த பைதான் செயல்படுத்தலை ஏன் குறிப்பிடவில்லை?" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +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 "" +"சுருக்கமான குறிச்சொற்கள் ஒரு பொது குறியீட்டில் தொகுக்கப்பட்ட பைதான் குறியீட்டைப் பகிர்வதற்கு " +"உதவுகின்றன. உங்கள் பைதான் செயல்படுத்தல் இந்த விவரக்குறிப்பையும் பயன்படுத்தலாம், ஆனால் நீண்ட " +"குறிச்சொற்களுடன். அனைத்து \"தூய பைதான்\" கட்டப்பட்ட விநியோகங்களும் `` py`` ஐப் " +"பயன்படுத்துகின்றன என்பதை நினைவில் கொள்க." + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" +"குறிப்பு செயல்படுத்தலில் அபி குறிச்சொல் (இரண்டாவது குறிச்சொல்) சில நேரங்களில் " +"\"எதுவுமில்லை\"?" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" +"பைதான் 2 க்கு சோபிக்குச் செல்ல எளிதான வழி இல்லை என்பதால் (இந்த கருத்து பைத்தானின் புதிய " +"பதிப்புகளிலிருந்து வருகிறது 3) \"எதுவுமில்லை\" என்ற யூகங்களை எழுதும் நேரத்தில் " +"குறிப்பு செயல்படுத்தல். வெறுமனே இது பைத்தானின் புதிய பதிப்புகளுக்கு ஒத்த \"PY27 (D | " +"M | U)\" ஐக் கண்டறியும், ஆனால் இதற்கிடையில் \"எதுவுமில்லை\" என்பது \"தெரியாது\" என்று " +"சொல்வதற்கு போதுமான வழி." + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" +"பிப்ரவரி 2013: இந்த விவரக்குறிப்பின் அசல் பதிப்பு மூலம் அங்கீகரிக்கப்பட்டது: PEP: `425`." + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "சனவரி 2016: `` மேனிலினக்ச் 1`` குறிச்சொல் மூலம் அங்கீகரிக்கப்பட்டது: PEP: `513`." + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" +"ஏப்ரல் 2018: `` மேனிலினக்ச் 2010`` குறிச்சொல் மூலம் அங்கீகரிக்கப்பட்டது: PEP: `571`." + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" +"சூலை 2019: `` மேனிலினக்ச் 2014`` குறிச்சொல் மூலம் அங்கீகரிக்கப்பட்டது: PEP: `599`." + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" +"நவம்பர் 2019: `` Manylinux_x_y`` வற்றாத குறிச்சொல் மூலம் அங்கீகரிக்கப்பட்டது: PEP: " +"`600`." + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" +"ஏப்ரல் 2021: `` musllinux_x_y`` குறிச்சொல் மூலம் அங்கீகரிக்கப்பட்டது: PEP: `656`." + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +#, fuzzy +#| msgid "Project Summaries" +msgid "Project Status Markers" +msgstr "திட்ட சுருக்கங்கள்" + +#: ../source/specifications/project-status-markers.rst:9 +#, fuzzy +#| msgid "This specification was originally defined in :pep:`740`." +msgid "This specification was originally defined in :pep:`792`." +msgstr "இந்த விவரக்குறிப்பு முதலில் வரையறுக்கப்பட்டது: PEP: `740`." + +#: ../source/specifications/project-status-markers.rst:14 +#, fuzzy +#| msgid "" +#| ":pep:`740` includes changes to the HTML and JSON index APIs. These " +#| "changes are documented in the :ref:`simple-repository-api` " +#| "under :ref:`simple-repository-api-base` and :ref:`json-serialization`." +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" +": PEP: `740` உஉகுமொ மற்றும் சாதொபொகு குறியெண் பநிஇ களில் மாற்றங்களை உள்ளடக்கியது. " +"இந்த மாற்றங்கள்: ref: `Simple-reposition-api` இன் கீழ் ஆவணப்படுத்தப்பட்டுள்ளன: ref:` " +"எளிய-ரோபோசிட்டரி-ஆபி-பேச்` மற்றும்: குறிப்பு: `json-cerialization`." + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +#, fuzzy +#| msgid "Installation" +msgid "Installer semantics: none." +msgstr "நிறுவல்" + +#: ../source/specifications/project-status-markers.rst:45 +#, fuzzy +#| msgid "``packages``" +msgid "``archived``" +msgstr "`` தொகுப்புகள்``" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +#, fuzzy +#| msgid "Installers" +msgid "Installer semantics:" +msgstr "நிறுவிகள்" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +#, fuzzy +#| msgid "Deprecated" +msgid "``deprecated``" +msgstr "மதிப்பிடப்பட்டது" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +#, fuzzy +#| msgid "``pyproject.toml`` specification" +msgid "``pylock.toml`` Specification" +msgstr "`` pyproject.toml`` விவரக்குறிப்பு" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +#, fuzzy +#| msgid "This specification was originally defined in :pep:`753`." +msgid "This specification was originally defined in :pep:`751`." +msgstr "இந்த விவரக்குறிப்பு முதலில் வரையறுக்கப்பட்டது: PEP: `753`." + +#: ../source/specifications/pylock-toml.rst:16 +#, fuzzy +#| msgid "File Format" +msgid "File Name" +msgstr "கோப்பு வடிவம்" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +#, fuzzy +#| msgid "``platform_version``" +msgid "``lock-version``" +msgstr "`` PLATER_VERSION``" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +#, fuzzy +#| msgid "Requires" +msgid "**Required?**: yes" +msgstr "தேவை" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +#, fuzzy +#| msgid "``entry-points``" +msgid "``environments``" +msgstr "`` நுழைவு புள்ளிகள்``" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +#, fuzzy +#| msgid "TOML_ type: array of strings" +msgid "**Type**: Array of strings" +msgstr "டாம்_ வகை: சரங்களின் வரிசை" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +#, fuzzy +#| msgid "TOML_ type: string" +msgid "**Type**: string" +msgstr "TOML_ வகை: சரம்" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +#, fuzzy +#| msgid "The ``[dependency-groups]`` Table" +msgid "``dependency-groups``" +msgstr "`` [சார்பு-குழுக்கள்] `` அட்டவணை" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +#, fuzzy +#| msgid ":ref:`pyproject-toml-spec`" +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr ": ref: `pyproject-toml-spec`" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +#, fuzzy +#| msgid "" +#| "``INSTALLER``: records the name of the tool used to install the project." +msgid "Records the name of the tool used to create the lock file." +msgstr "" +"`` நிறுவி``: திட்டத்தை நிறுவ பயன்படுத்தப்படும் கருவியின் பெயரை பதிவு செய்கிறது." + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +#, fuzzy +#| msgid "``packages``" +msgid "``[[packages]]``" +msgstr "`` தொகுப்புகள்``" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +#, fuzzy +#| msgid "TOML_ type: array of strings" +msgid "**Type**: array of tables" +msgstr "டாம்_ வகை: சரங்களின் வரிசை" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.name``" +msgstr "`` தொகுப்புகள்``" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +#, fuzzy +#| msgid "" +#| "For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgid "The name of the package :ref:`normalized `." +msgstr "" +"ஒப்பீட்டு நோக்கங்களுக்காக, பெயர்கள் இருக்க வேண்டும்: குறிப்பு: `இயல்பாக்கப்பட்ட <பெயர்-" +"இயல்பாக்கம்>` ஒப்பிடுவதற்கு முன்." + +#: ../source/specifications/pylock-toml.rst:210 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.version``" +msgstr "`` தொகுப்புகள்``" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +#, fuzzy +#| msgid "Creating the package" +msgid "The version of the package." +msgstr "தொகுப்பை உருவாக்குதல்" + +#: ../source/specifications/pylock-toml.rst:216 +#, fuzzy +#| msgid "" +#| "``subject[0].name`` is the distribution's filename, which **MUST** be a " +#| "valid :ref:`source distribution ` " +#| "or :ref:`wheel distribution ` filename." +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" +"`` பொருள் [0] .பெயர்`` என்பது விநியோகத்தின் கோப்பு பெயர், இது ** ** செல்லுபடியாகும்: " +"குறிப்பு: `மூல வழங்கல் <மூல-விநியோக-வடிவ>` அல்லது: குறிப்பு: `சக்கர வழங்கல் <பைனரி-" +"விநியோக-- வடிவம்> `கோப்பு பெயர்." + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.marker``" +msgstr "`` தொகுப்புகள்``" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +#, fuzzy +#| msgid "``requires-python``" +msgid "``packages.requires-python``" +msgstr "``-பைதான் தேவை`" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +#, fuzzy +#| msgid "``dependencies``" +msgid "``[[packages.dependencies]]``" +msgstr "`` சார்புகள்``" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +#, fuzzy +#| msgid "``packages``" +msgid "``[packages.vcs]``" +msgstr "`` தொகுப்புகள்``" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +#, fuzzy +#| msgid "TOML_ type: string or table" +msgid "**Type**: table" +msgstr "TOML_ வகை: சரம் அல்லது அட்டவணை" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.vcs.type``" +msgstr "`` தொகுப்புகள்``" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +#, fuzzy +#| msgid "Install from version control systems" +msgid "The type of version control system used." +msgstr "பதிப்பு கட்டுப்பாட்டு அமைப்புகளிலிருந்து நிறுவவும்" + +#: ../source/specifications/pylock-toml.rst:306 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.vcs.url``" +msgstr "`` தொகுப்புகள்``" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +#, fuzzy +#| msgid "The source tree" +msgid "The URL_ to the source tree." +msgstr "மூல மரம்" + +#: ../source/specifications/pylock-toml.rst:317 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.vcs.path``" +msgstr "`` தொகுப்புகள்``" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +#, fuzzy +#| msgid "``requested_revision`` field" +msgid "``packages.vcs.requested-revision``" +msgstr "`` கோரப்பட்டது_ரெவிசன்` புலம்" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.vcs.commit-id``" +msgstr "`` தொகுப்புகள்``" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +#, fuzzy +#| 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." +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" +"ஒரு `` கமிட்_ஐடி`` விசை (வகை `` சரம்``) இருக்க வேண்டும், இதில் சரியான கமிட்/திருத்த " +"எண்ணை நிறுவ வேண்டும்/நிறுவ வேண்டும். மூலக் குறியீட்டின் மாறாத பதிப்பைக் குறிப்பிடுவதற்கு " +"வி.சி.எச் கமிட்-ஆச் அடிப்படையிலான திருத்த அடையாளங்காட்டிகளை ஆதரித்தால், அத்தகைய கமிட்-" +"ஆச் `` கமிட்_ஐடி`` எனப் பயன்படுத்தப்பட வேண்டும்." + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +#, fuzzy +#| msgid "``packages``" +msgid "``[packages.directory]``" +msgstr "`` தொகுப்புகள்``" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +#, fuzzy +#| msgid "``package_data``" +msgid "``packages.directory.path``" +msgstr "`` தொகுப்பு_டேட்டா``" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +#, fuzzy +#| msgid "``packages``" +msgid "``[packages.archive]``" +msgstr "`` தொகுப்புகள்``" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.archive.url``" +msgstr "`` தொகுப்புகள்``" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.archive.path``" +msgstr "`` தொகுப்புகள்``" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.archive.size``" +msgstr "`` தொகுப்புகள்``" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +#, fuzzy +#| msgid "The name of the project." +msgid "The size of the archive file." +msgstr "திட்டத்தின் பெயர்." + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +#, fuzzy +#| msgid "Where the guide is deployed" +msgid "The time the file was uploaded." +msgstr "வழிகாட்டி பயன்படுத்தப்படும் இடத்தில்" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +#, fuzzy +#| msgid "TOML_ type: array of strings" +msgid "**Type**: Table of strings" +msgstr "டாம்_ வகை: சரங்களின் வரிசை" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.index``" +msgstr "`` தொகுப்புகள்``" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +#, fuzzy +#| msgid "``packages``" +msgid "``[packages.sdist]``" +msgstr "`` தொகுப்புகள்``" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +#, fuzzy +#| msgid "``package_data``" +msgid "``packages.sdist.name``" +msgstr "`` தொகுப்பு_டேட்டா``" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +#, fuzzy +#| msgid "``package_data``" +msgid "``packages.sdist.upload-time``" +msgstr "`` தொகுப்பு_டேட்டா``" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.sdist.url``" +msgstr "`` தொகுப்புகள்``" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +#, fuzzy +#| msgid "``package_data``" +msgid "``packages.sdist.path``" +msgstr "`` தொகுப்பு_டேட்டா``" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.sdist.size``" +msgstr "`` தொகுப்புகள்``" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +#, fuzzy +#| msgid "``package_data``" +msgid "``packages.sdist.hashes``" +msgstr "`` தொகுப்பு_டேட்டா``" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +#, fuzzy +#| msgid "``packages``" +msgid "``[[packages.wheels]]``" +msgstr "`` தொகுப்புகள்``" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.wheels.name``" +msgstr "`` தொகுப்புகள்``" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.wheels.url``" +msgstr "`` தொகுப்புகள்``" + +#: ../source/specifications/pylock-toml.rst:647 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.wheels.path``" +msgstr "`` தொகுப்புகள்``" + +#: ../source/specifications/pylock-toml.rst:655 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.wheels.size``" +msgstr "`` தொகுப்புகள்``" + +#: ../source/specifications/pylock-toml.rst:663 +#, fuzzy +#| msgid "``packages``" +msgid "``packages.wheels.hashes``" +msgstr "`` தொகுப்புகள்``" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +#, fuzzy +#| msgid ":ref:`pyproject-toml-spec`" +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr ": ref: `pyproject-toml-spec`" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +#, fuzzy +#| msgid "``packages``" +msgid "``[packages.tool]``" +msgstr "`` தொகுப்புகள்``" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +#, fuzzy +#| msgid "Binary distribution format" +msgid ":ref:`Install `." +msgstr "பைனரி விநியோக வடிவம்" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +#, fuzzy +#| msgid "" +#| "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" +"ஏப்ரல் 2018: `` மேனிலினக்ச் 2010`` குறிச்சொல் மூலம் அங்கீகரிக்கப்பட்டது: PEP: `571`." + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "தி: கோப்பு: `.pypirc` கோப்பு" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" +"ப: கோப்பு: `.pypirc` கோப்பு இதற்கான உள்ளமைவை வரையறுக்க உங்களை அனுமதிக்கிறது: கால:` " +"தொகுப்பு குறியீடுகள் <தொகுப்பு குறியீட்டு> `(இங்கே\" களஞ்சியங்கள் \"என்று " +"குறிப்பிடப்படுகிறது), இதனால் நீங்கள் முகவரி, பயனர்பெயரை உள்ளிட வேண்டியதில்லை , அல்லது " +"கடவுச்சொல் நீங்கள் ஒரு தொகுப்பைப் பதிவேற்றும்போதெல்லாம்: குறிப்பு: `ட்வைன்` அல்லது: " +"குறிப்பு:` ஃபிளிட்`." + +#: ../source/specifications/pypirc.rst:13 +#, fuzzy +#| msgid "The :file:`.pypirc` file" +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "தி: கோப்பு: `.pypirc` கோப்பு" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "வடிவம் (முதலில் வரையறுக்கப்படுகிறது: ref: `தொலைதூரங்கள்` தொகுப்பு):" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" +"`` தொலைதூரங்கள்`` பிரிவு ஒரு `` குறியீட்டு-சேவையகங்கள்` துறையை வரையறுக்கிறது, இது " +"ஒரு களஞ்சியத்தை விவரிக்கும் அனைத்து பிரிவுகளின் பெயரையும் பட்டியலிடுகிறது." + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "ஒரு களஞ்சியத்தை விவரிக்கும் ஒவ்வொரு பகுதியும் மூன்று புலங்களை வரையறுக்கிறது:" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "`` களஞ்சியம்``: களஞ்சியத்தின் முகவரி." + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "`` பயனர்பெயர்``: களஞ்சியத்தில் பதிவுசெய்யப்பட்ட பயனர்பெயர்." + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "`` கடவுச்சொல்``: பயனர்பெயரை அங்கீகரிக்க பயன்படுத்தப்படும் கடவுச்சொல்." + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" +"இது உங்கள் கடவுச்சொல்லை எளிய உரையில் சேமிக்கிறது என்பதை அறிந்து கொள்ளுங்கள். சிறந்த " +"பாதுகாப்பிற்காக, `கீரிங்`_ போன்ற மாற்றீட்டைக் கவனியுங்கள், சுற்றுச்சூழல் மாறிகள் அமைத்தல் " +"அல்லது கடவுச்சொல்லை கட்டளை வரியில் வழங்குதல்." + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" +"இல்லையெனில், அனுமதிகளை அமைக்கவும்: கோப்பு: `.pypirc`, இதனால் நீங்கள் மட்டுமே அதைப் " +"பார்க்க அல்லது மாற்ற முடியும். எடுத்துக்காட்டாக, லினக்ச் அல்லது மேகோசில், இயக்கவும்:" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "பொதுவான உள்ளமைவுகள்" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" +"இந்த எடுத்துக்காட்டுகள் இதற்குப் பொருந்தும்: ref: `ட்வைன்`. பிற திட்டங்கள் (எ.கா.: ref: " +"`Flit`) மேலும் பயன்படுத்தவும்: கோப்பு:` .pypirc`, ஆனால் வெவ்வேறு இயல்புநிலைகளுடன். " +"மேலும் விவரங்கள் மற்றும் பயன்பாட்டு வழிமுறைகளுக்கு ஒவ்வொரு திட்டத்தின் ஆவணங்களையும் " +"பார்க்கவும்." + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" +"கயிறின் இயல்புநிலை உள்ளமைவு மிமிக்ச் a: கோப்பு: `.pypirc` பைபி மற்றும் டெச்ட்பிஐ " +"ஆகியவற்றிற்கான களஞ்சிய பிரிவுகளுடன்:" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" +"கயிறு கூடுதல் உள்ளமைவைச் சேர்க்கும்: கோப்பு: `$ home/.pypirc`, கட்டளை வரி மற்றும் " +"சுற்றுச்சூழல் மாறிகள் இந்த இயல்புநிலை உள்ளமைவுக்கு." + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "பைபி கிள்ளாக்கைப் பயன்படுத்துதல்" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" +"PYPI க்கு உங்கள் `API டோக்கன்`_ ஐ அமைக்க, நீங்கள் ஒரு: கோப்பு:` $ home/.pypirc` " +"போன்றவற்றை உருவாக்கலாம்:" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" +"For: ref: `TestPypi `, `` [TestPypi] `` பகுதியைச் சேர்க்கவும், " +"உங்கள் டெச்ட்பை கணக்கிலிருந்து பநிஇ கிள்ளாக்கைப் பயன்படுத்தி." + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "மற்றொரு தொகுப்பு குறியீட்டைப் பயன்படுத்துதல்" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" +"கூடுதல் களஞ்சியத்தை உள்ளமைக்க, களஞ்சிய பெயரைச் சேர்க்க `` குறியீட்டு-சேவையகங்கள்` துறையை " +"மறுவரையறை செய்ய வேண்டும். ஒரு முழுமையான எடுத்துக்காட்டு இங்கே: கோப்பு: `$ " +"home/.pypirc` pypi, testpypi மற்றும் ஒரு தனியார் களஞ்சியத்திற்கு:" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" +"`` கடவுச்சொல்`` புலத்தைப் பயன்படுத்துவதற்குப் பதிலாக, உங்கள் பநிஇ டோக்கன்கள் மற்றும் " +"கடவுச்சொற்களை `கீரிங்`_ ஐப் பயன்படுத்தி பாதுகாப்பாக சேமிப்பதைக் கவனியுங்கள் (இது கயிறால் " +"நிறுவப்பட்டுள்ளது):" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "`` pyproject.toml`` விவரக்குறிப்பு" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" +"இது ஒரு ** தொழில்நுட்ப, முறையான விவரக்குறிப்பு **. `` Pyproject.toml`` க்கு " +"மென்மையான, பயனர் நட்பு வழிகாட்டிக்கு, காண்க: குறிப்பு: `எழுதுதல்-பிப்ரோசெக்ட்-டோம்`." + +#: ../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 "" +"`` Pyproject.toml`` கோப்பு பேக்கேசிங் தொடர்பான கருவிகளுக்கான (அத்துடன் பிற " +"கருவிகளுக்கான) உள்ளமைவு கோப்பாக செயல்படுகிறது." + +#: ../source/specifications/pyproject-toml.rst:17 +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 "" +"`` Pyproject.toml`` கோப்பு `டாம்ல் _ _ இல் எழுதப்பட்டுள்ளது. " +"மூன்று அட்டவணைகள் தற்போது குறிப்பிடப்பட்டுள்ளன, அதாவது: குறிப்பு: `[பில்ட்-சிச்டம்] " +"`,: ref: `[திட்டம்] ` " +"மற்றும்: ref: `[கருவி] `. பிற அட்டவணைகள் எதிர்கால " +"பயன்பாட்டிற்காக ஒதுக்கப்பட்டுள்ளன (கருவி-குறிப்பிட்ட உள்ளமைவு `` [கருவி] `` அட்டவணை) " +"பயன்படுத்த வேண்டும்." + +#: ../source/specifications/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "உருவாக்க அமைப்பு சார்புகளை அறிவித்தல்: `` [உருவாக்க-அமைப்பு] `` அட்டவணை" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" +"`` [பில்ட்-சிச்டம்] `` அட்டவணை எந்தவொரு பைதான் நிலை சார்புகளையும் அறிவிக்கிறது, இது " +"திட்டத்தின் உருவாக்க முறையை வெற்றிகரமாக இயக்குவதற்கு நிறுவப்பட வேண்டும்." + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" +"உருவாக்கம் தொடர்பான தரவைச் சேமிக்க `` [பில்ட்-சிச்டம்] `` அட்டவணை பயன்படுத்தப்படுகிறது. " +"ஆரம்பத்தில், அட்டவணையின் ஒரு விசை மட்டுமே செல்லுபடியாகும் மற்றும் அட்டவணைக்கு " +"கட்டாயமாகும்: `` தேவை``. இந்த விசையானது உருவாக்க அமைப்பை இயக்கத் தேவையான சார்புகளைக் " +"குறிக்கும் சரங்களின் பட்டியலின் மதிப்பைக் கொண்டிருக்க வேண்டும். இந்த பட்டியலில் உள்ள சரங்கள் " +"பின்வருமாறு: ref: `பதிப்பு விவரக்குறிப்பு விவரக்குறிப்பு <பதிப்பு-விவரக்குறிப்புகள்>`." + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" +"ஒரு எடுத்துக்காட்டு `` [பில்ட்-சிச்டம்] `` `` setuptools`` உடன் கட்டப்பட்ட ஒரு " +"திட்டத்திற்கான அட்டவணை:" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" +"`` Pyproject.toml`` கோப்பு இல்லாதபோது, மேலே உள்ள எடுத்துக்காட்டு உள்ளமைவு கோப்பை " +"அவற்றின் இயல்புநிலை சொற்பொருளாகப் பயன்படுத்தும் என்று எதிர்பார்க்கப்படுகிறது." + +#: ../source/specifications/pyproject-toml.rst:54 +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 "" +"கருவிகளுக்கு `` [பில்ட்-சிச்டம்] `` அட்டவணையின் இருப்பு தேவையில்லை. உருவாக்கம் தொடர்பான " +"தரவைத் தவிர வேறு உள்ளமைவு விவரங்களைச் சேமிக்க ஒரு `` pyproject.toml`` கோப்பு " +"பயன்படுத்தப்படலாம், இதனால் `` [உருவாக்க-அமைப்பு] `` சட்டபூர்வமாக அட்டவணை இல்லை. கோப்பு " +"உள்ளது, ஆனால் `` [பில்ட்-சிச்டம்] `` அட்டவணை இல்லாதிருந்தால், மேலே குறிப்பிடப்பட்டுள்ள " +"இயல்புநிலை மதிப்புகள் பயன்படுத்தப்பட வேண்டும். அட்டவணை குறிப்பிடப்பட்டாலும், தேவையான " +"புலங்களைக் காணவில்லை என்றால், கருவி அதை பிழையாகக் கருத வேண்டும்." + +#: ../source/specifications/pyproject-toml.rst:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" +"விளக்கமான நோக்கங்களுக்காக மட்டுமே டாம்ல் கோப்பிலிருந்து இதன் விளைவாக வரும் தரவின் வகை-" +"குறிப்பிட்ட பிரதிநிதித்துவத்தை வழங்க, பின்வரும் `json Schema ` _ தரவு வடிவத்துடன் பொருந்தும்:" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "திட்ட மெட்டாடேட்டாவை அறிவித்தல்: `` [திட்டம்] `` அட்டவணை" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" +"`` [திட்டம்] `` அட்டவணை திட்டத்தின் குறிப்பிடுகிறது: குறிப்பு: `கோர் மேனிலை தரவு <கோர்-" +"மெட்டாடேட்டா>`." + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" +"இரண்டு வகையான மேனிலை தரவு உள்ளன: *நிலையான *மற்றும் *டைனமிக் *. நிலையான மேனிலை " +"தரவு `` pyproject.toml`` கோப்பில் நேரடியாக குறிப்பிடப்பட்டுள்ளது, மேலும் இது ஒரு " +"கருவியால் குறிப்பிடப்படவோ அல்லது மாற்றவோ முடியாது (இதில் மெட்டாடேட்டாவால் " +"குறிப்பிடப்பட்ட தரவு * அடங்கும், எ.கா. மெட்டாடேட்டாவால் குறிப்பிடப்பட்ட கோப்புகளின் " +"உள்ளடக்கங்கள்). மாறும் மேனிலை தரவு `` டைனமிக்`` விசை வழியாக பட்டியலிடப்பட்டுள்ளது (இந்த " +"விவரக்குறிப்பில் பின்னர் வரையறுக்கப்படுகிறது) மற்றும் ஒரு கருவி பின்னர் வழங்கும் " +"மெட்டாடேட்டாவைக் குறிக்கிறது." + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" +"ஒரு `` [திட்டம்] `` அட்டவணை மறைமுகமாக: காலப்பகுதி: `பின்தளத்தில் உருவாக்கு " +"<பின்தளத்தில் உருவாக்கு>` எல்லா விசைகளையும் மாறும்." + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "சட்டப்பூர்வமாக வரையறுக்கப்பட வேண்டிய ஒரே விசைகள்:" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" +"தேவைப்படும் ஆனால் குறிப்பிடக்கூடிய விசைகள் * நிலையானவை அல்லது மாறும் என " +"பட்டியலிடப்பட்டுள்ளன:" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" +"மற்ற எல்லா விசைகளும் விருப்பமானதாகக் கருதப்படுகின்றன, மேலும் அவை நிலையான முறையில் " +"குறிப்பிடப்படலாம், மாறும் என பட்டியலிடப்பட்டிருக்கலாம் அல்லது குறிப்பிடப்படாதவை." + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "`` [திட்ட] `` அட்டவணையில் அனுமதிக்கப்பட்ட விசைகளின் முழுமையான பட்டியல்:" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "`` ஆசிரியர்கள்``" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "`` சார்புகள்``" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "`` டைனமிக்``" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "`` நுழைவு புள்ளிகள்``" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "`` குய்-ச்கிரிப்ட்ச்``" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +#, fuzzy +#| msgid "``name``" +msgid "``import-names``" +msgstr "`` பெயர்``" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "`` பராமரிப்பாளர்கள்``" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "`` விருப்ப-சார்புநிலைகள்``" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "TOML_ வகை: சரம்" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" +"தொடர்புடைய: குறிப்பு: `கோர் மேனிலை தரவு <கோர்-மெட்டாடேட்டா>` புலம் :: குறிப்பு: " +"`பெயர் <கோர்-மெட்டாடேட்டா-பெயர்>`" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "திட்டத்தின் பெயர்." + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" +"கருவிகள் செய்ய வேண்டும்: குறிப்பு: `இயல்பான <பெயர்-இயல்பாக்கம்>` இந்த பெயர் உள் " +"நிலைத்தன்மைக்கு படித்தவுடன்." + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" +"தொடர்புடைய: ref: `கோர் மேனிலை தரவு <கோர்-மெட்டாடேட்டா>` புலம் :: குறிப்பு: `பதிப்பு " +"<கோர்-மெட்டாடேட்டா-பதிப்பு>`" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" +"திட்டத்தின் பதிப்பு, இல் வரையறுக்கப்பட்டுள்ளது: ref: `பதிப்பு விவரக்குறிப்பு " +"விவரக்குறிப்பு <பதிப்பு-விவரக்குறிப்புகள்>`." + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "ஏற்கனவே இயல்பாக்கப்பட்ட பதிப்புகளைக் குறிப்பிட பயனர்கள் விரும்ப வேண்டும்." + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" +"தொடர்புடையது: ref: `கோர் மேனிலை தரவு <கோர்-மெட்டாடேட்டா>` புலம் :: குறிப்பு: " +"`சுருக்கம் <கோர்-மெட்டாடேட்டா-சுருக்கம்>`" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" +"திட்டத்தின் சுருக்க விளக்கம் ஒரு வரியில். இதில் பல வரிகள் இருந்தால் கருவிகள் பிழையாக " +"இருக்கலாம்." + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "TOML_ வகை: சரம் அல்லது அட்டவணை" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" +"தொடர்புடைய: `கோர் மேனிலை தரவு <கோர்-மெட்டாடேட்டா>` புலம் :: குறிப்பு: `விளக்கம் <கோர்-" +"மெட்டாடேட்டா-விளக்கப்படம்>` மற்றும்: குறிப்பு: `விளக்கம்-கண்டி-வகை <கோர்-மெட்டாடேட்டா-" +"விளக்கமளிப்பு-வகை>`" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "திட்டத்தின் முழு விளக்கம் (அதாவது README)." + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" +"விசை ஒரு சரம் அல்லது அட்டவணையை ஏற்றுக்கொள்கிறது. இது ஒரு சரம் என்றால், அது முழு " +"விளக்கத்தைக் கொண்ட உரை கோப்புடன் `` pyproject.toml`` உடன் தொடர்புடைய பாதையாகும். " +"கோப்புகளின் குறியாக்கம் UTF-8 என்று கருவிகள் கருத வேண்டும். கோப்பு பாதை ஒரு வழக்கு-" +"உணர்திறன் `.md`` பின்னொட்டில் முடிவடைந்தால், கருவிகள் உள்ளடக்க வகை` `உரை/மார்க் டவுன்`` " +"என்று கருத வேண்டும். கோப்பு பாதை ஒரு வழக்கு-உணர்வற்ற `` .rst`` இல் முடிவடைந்தால், " +"கருவிகள் உள்ளடக்க வகை `` உரை/x-rst`` என்று கருத வேண்டும். இந்த PEP ஐ விட ஒரு கருவி " +"அதிக நீட்டிப்புகளை அங்கீகரித்தால், இந்த விசையை `` டைனமிக்`` என்று குறிப்பிடாமல் " +"பயனருக்கான உள்ளடக்க வகையை அவை ஊகிக்கக்கூடும். அடையாளம் காணப்படாத அனைத்து " +"பின்னொட்டுகளுக்கும் உள்ளடக்க வகை வழங்கப்படாதபோது, கருவிகள் பிழையை உயர்த்த வேண்டும்." + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" +"`` ReadMe`` விசையும் ஒரு அட்டவணையை எடுக்கலாம். `` கோப்பு`` விசையானது முழு " +"விளக்கத்தைக் கொண்ட ஒரு கோப்பிற்கு `` pyproject.toml`` உடன் தொடர்புடைய பாதையை " +"குறிக்கும் சரம் மதிப்பைக் கொண்டுள்ளது. `` உரை`` விசையில் ஒரு சரம் மதிப்பு உள்ளது, இது " +"முழு விளக்கமாகும். இந்த விசைகள் இருவழி பிரத்தியேகமானவை, இதனால் மேனிலை தரவு இரண்டு " +"விசைகளையும் குறிப்பிடினால் கருவிகள் பிழையை எழுப்ப வேண்டும்." + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" +"`` ReadMe`` விசையில் குறிப்பிடப்பட்டுள்ள அட்டவணையில் `` உள்ளடக்க-வகை`` விசையும் உள்ளது, " +"இது முழு விளக்கத்தின் உள்ளடக்க வகையைக் குறிப்பிடும் ஒரு சரத்தை எடுக்கும். மேனிலை தரவு " +"இந்த விசையை அட்டவணையில் குறிப்பிடவில்லை என்றால் ஒரு கருவி பிழையை உயர்த்த வேண்டும். " +"மேனிலை தரவு `` சார்செட்`` அளவுருவைக் குறிப்பிடவில்லை என்றால், அது யுடிஎஃப் -8 என்று " +"கருதப்படுகிறது. கருவிகள் பிற குறியாக்கங்களை தேர்வு செய்தால் ஆதரிக்கலாம். கருவிகள் " +"மாற்று உள்ளடக்க வகைகளை ஆதரிக்கலாம், அவை உள்ளடக்க வகைக்கு மாற்றக்கூடியவை: ref: `கோர் " +"மேனிலை தரவு <கோர்-மெட்டாடேட்டா>`. இல்லையெனில் கருவிகள் ஆதரிக்கப்படாத உள்ளடக்க " +"வகைகளுக்கு பிழையை எழுப்ப வேண்டும்." + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" +"தொடர்புடையது: குறிப்பு: `கோர் மேனிலை தரவு <கோர்-மெட்டாடேட்டா>` புலம் :: குறிப்பு: `-" +"பைதான் <கோர்-மெட்டாடேட்டா-வேண்டுகோள்-பைதான்>` தேவை" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "திட்டத்தின் பைதான் பதிப்பு தேவைகள்." + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" +"தொடர்புடைய: ref: `கோர் மேனிலை தரவு <கோர்-மெட்டாடேட்டா>` புலம் :: குறிப்பு: `உரிம-" +"வெளிப்பாடு <கோர்-மெட்டாடேட்டா-லிசென்ச்-எக்ச்பிரசன்>`" + +#: ../source/specifications/pyproject-toml.rst:261 +#, fuzzy +#| msgid "" +#| "Text string that is a valid SPDX license expression as defined " +#| "in :pep:`639`. Tools SHOULD validate and perform case normalization of " +#| "the expression." +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" +"வரையறுக்கப்பட்டுள்ளபடி செல்லுபடியாகும் SPDX உரிம வெளிப்பாடு உரை சரம்: PEP: `639`. " +"கருவிகள் வெளிப்பாட்டின் வழக்கு இயல்பாக்கலை சரிபார்க்க வேண்டும் மற்றும் செய்ய வேண்டும்." + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +#, fuzzy +#| msgid "PyPA specifications" +msgid "Legacy specification" +msgstr "PYPA விவரக்குறிப்புகள்" + +#: ../source/specifications/pyproject-toml.rst:275 +#, fuzzy +#| msgid "TOML_ type: string or table" +msgid "TOML_ type: table" +msgstr "TOML_ வகை: சரம் அல்லது அட்டவணை" + +#: ../source/specifications/pyproject-toml.rst:276 +#, fuzzy +#| msgid "" +#| "Corresponding :ref:`core metadata ` field: :ref:`Name " +#| "`" +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" +"தொடர்புடைய: குறிப்பு: `கோர் மேனிலை தரவு <கோர்-மெட்டாடேட்டா>` புலம் :: குறிப்பு: " +"`பெயர் <கோர்-மெட்டாடேட்டா-பெயர்>`" + +#: ../source/specifications/pyproject-toml.rst:279 +#, fuzzy +#| 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." +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`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 "" +"`` ReadMe`` விசையும் ஒரு அட்டவணையை எடுக்கலாம். `` கோப்பு`` விசையானது முழு " +"விளக்கத்தைக் கொண்ட ஒரு கோப்பிற்கு `` pyproject.toml`` உடன் தொடர்புடைய பாதையை " +"குறிக்கும் சரம் மதிப்பைக் கொண்டுள்ளது. `` உரை`` விசையில் ஒரு சரம் மதிப்பு உள்ளது, இது " +"முழு விளக்கமாகும். இந்த விசைகள் இருவழி பிரத்தியேகமானவை, இதனால் மேனிலை தரவு இரண்டு " +"விசைகளையும் குறிப்பிடினால் கருவிகள் பிழையை எழுப்ப வேண்டும்." + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "டாம்_ வகை: சரங்களின் வரிசை" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" +"திட்ட ரூட் கோப்பகத்துடன் தொடர்புடைய திட்ட மூல மரத்தில் உள்ள பாதைகளைக் குறிப்பிடும் ஒரு " +"வரிசை (அதாவது அடைவு: கோப்பு: `pyproject.toml` அல்லது மரபு திட்ட உள்ளமைவு " +"கோப்புகள், எ.கா.: கோப்பு:` setup.py`,: `setup.cfg `, முதலியன) தொகுப்புடன் " +"விநியோகிக்கப்பட வேண்டிய உரிமங்கள் மற்றும் பிற சட்ட அறிவிப்புகளைக் கொண்ட (கள்)." + +#: ../source/specifications/pyproject-toml.rst:303 +#, fuzzy +#| msgid "The strings MUST contain valid glob patterns, as specified below:" +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" +"கீழே குறிப்பிடப்பட்டுள்ளபடி சரங்களில் செல்லுபடியாகும் குளோப் வடிவங்கள் இருக்க வேண்டும்:" + +#: ../source/specifications/pyproject-toml.rst:306 +#, fuzzy +#| msgid "" +#| "Patterns are relative to the directory containing :file:`pyproject.toml`, " +#| "and thus may not start with a slash character." +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" +"வடிவங்கள் கொண்ட கோப்பகத்துடன் தொடர்புடையவை: கோப்பு: `pyproject.toml`, இதனால் ஒரு ச்லாச் " +"பாத்திரத்துடன் தொடங்கக்கூடாது." + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" +"உரிமக் கோப்பு உள்ளடக்கம் செல்லுபடியாகும் UTF-8 குறியிடப்பட்ட உரை என்று கருவிகள் கருத " +"வேண்டும், மேலும் இதைச் சரிபார்த்து, இல்லையென்றால் பிழையை உயர்த்த வேண்டும்." + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "கருவிகளை உருவாக்கு:" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" +"அனைத்து விநியோக காப்பகங்களிலும் பட்டியலிடப்பட்ட வடிவத்தால் பொருந்தக்கூடிய அனைத்து " +"கோப்புகளையும் சேர்க்க வேண்டும்." + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" +"பொருந்திய ஒவ்வொரு கோப்பு பாதையும் கோர் மெட்டாடேட்டாவில் உரிம-கோப்பு புலத்தின் கீழ் " +"பட்டியலிட வேண்டும்." + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" +"`` உரிம-கோப்புகள்`` விசை இருந்தால், வெற்று வரிசையின் மதிப்பாக அமைக்கப்பட்டால், " +"கருவிகளில் எந்த உரிமக் கோப்புகளையும் கொண்டிருக்கக்கூடாது, பிழையை உயர்த்தக்கூடாது. `` " +"உரிம-கோப்புகள்`` விசை வரையறுக்கப்படவில்லை எனில், உரிமக் கோப்புகளை எவ்வாறு கையாள்வது " +"என்பதை கருவிகள் தீர்மானிக்க முடியும். எடுத்துக்காட்டாக, அவர்கள் எந்த கோப்புகளையும் சேர்க்க " +"வேண்டாம் என்று தேர்வு செய்யலாம் அல்லது விநியோகத்தில் பொருத்தமான கோப்புகளைக் கண்டறிய தங்கள் " +"சொந்த தர்க்கத்தைப் பயன்படுத்தலாம்." + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "TOML_ வகை: சரம் விசைகள் மற்றும் மதிப்புகளுடன் இன்லைன் அட்டவணைகளின் வரிசை" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" +"தொடர்புடைய: `கோர் மேனிலை தரவு <கோர்-மெட்டாடேட்டா>` புலம் :: குறிப்பு: `ஆசிரியர் <கோர்-" +"மெட்டாடேட்டா-ஆசிரியர்>`,: குறிப்பு: `ஆசிரியர்-எமெயில் <கோர்-மெட்டாடேட்டா-ஆசிரியர்-" +"எமெயில்>`,: குறிப்பு: `பராமரிப்பாளர் `, மற்றும்: ref: " +"`பராமரிப்பாளர்-எமெயில் `" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" +"திட்டத்தின் \"ஆசிரியர்கள்\" என்று கருதப்படும் நபர்கள் அல்லது அமைப்புகள். சரியான பொருள் " +"விளக்கத்திற்கு திறந்திருக்கும் - இது அசல் அல்லது முதன்மை ஆசிரியர்கள், தற்போதைய " +"பராமரிப்பாளர்கள் அல்லது தொகுப்பின் உரிமையாளர்களை பட்டியலிடலாம்." + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" +"\"பராமரிப்பாளர்கள்\" விசை \"ஆசிரியர்களுக்கு\" ஒத்ததாகும், அதன் சரியான பொருள் " +"விளக்கத்திற்கு திறந்திருக்கும்." + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" +"இந்த விசைகள் 2 விசைகள் கொண்ட அட்டவணைகளின் வரிசையை ஏற்றுக்கொள்கின்றன: `` பெயர்`` மற்றும் " +"`` மின்னஞ்சல்``. இரண்டு மதிப்புகளும் சரங்களாக இருக்க வேண்டும். `` பெயர்`` மதிப்பு " +"செல்லுபடியாகும் மின்னஞ்சல் பெயராக இருக்க வேண்டும் (அதாவது ஒரு பெயராக, மின்னஞ்சலுக்கு " +"முன், இல், இல்: rfc: `822`) மற்றும் காற்புள்ளிகள் இல்லை. `` மின்னஞ்சல்`` மதிப்பு சரியான " +"மின்னஞ்சல் முகவரியாக இருக்க வேண்டும். இரண்டு விசைகளும் விருப்பமானவை, ஆனால் குறைந்தபட்சம் " +"விசைகளில் ஒன்று அட்டவணையில் குறிப்பிடப்பட வேண்டும்." + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" +"நிரப்ப தரவைப் பயன்படுத்துதல்: ref: `கோர் மேனிலை தரவு <கோர்-மெட்டாடேட்டா>` பின்வருமாறு:" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" +"`` பெயர்`` மட்டுமே வழங்கப்பட்டால், மதிப்பு: குறிப்பு: `ஆசிரியர் <கோர்-மெட்டாடேட்டா-" +"ஆசிரியர்>` அல்லது: குறிப்பு: `பராமரிப்பாளர் <கோர்-மெட்டாடேட்டா-ஐன்டெய்னர்>` " +"பொருத்தமானதாகும்." + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" +"`` மின்னஞ்சல்`` மட்டுமே வழங்கப்பட்டால், மதிப்பு உள்ளே செல்கிறது: குறிப்பு: `ஆசிரியர்-" +"எமெயில் <கோர்-மெட்டாடேட்டா-ஆசிரியர்-எமெயில்>` அல்லது: குறிப்பு: `பராமரிப்பாளர்-எமெயில் " +"<கோர்-மெட்டாடேட்டா-திருவிழா-எமெயில்>` என பொருத்தமானது." + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" +"`` மின்னஞ்சல்`` மற்றும் `பெயர்`` இரண்டும் வழங்கப்பட்டால், மதிப்பு: ref:` ஆசிரியர்-எமெயில் " +"<கோர்-மெட்டாடேட்டா-ஆசிரியர்-எமெயில்> `அல்லது: குறிப்பு:` பராமரிப்பாளர்-எமெயில் <கோர்-" +"மெட்டாடேட்டா- `` {name} <{email}> `` வடிவத்துடன் பராமரிப்பாளர்-எமெயில்> " +"`பொருத்தமானது." + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "பல மதிப்புகள் காற்புள்ளிகளால் பிரிக்கப்பட வேண்டும்." + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" +"தொடர்புடைய: ref: `கோர் மேனிலை தரவு <கோர்-மெட்டாடேட்டா>` புலம் :: குறிப்பு: `முக்கிய " +"வார்த்தைகள் <கோர்-மெட்டாடேட்டா-கீவேர்டுகள்>`" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "திட்டத்திற்கான முக்கிய வார்த்தைகள்." + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" +"தொடர்புடைய: ref: `கோர் மேனிலை தரவு <கோர்-மெட்டாடேட்டா>` புலம் :: குறிப்பு: " +"`வகைப்படுத்தி <கோர்-மெட்டாடேட்டா-கிளாசிஃபையர்>`" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "திட்டத்திற்கு பொருந்தும் வகைப்படுத்திகள்." + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" +"`` உரிமம் :: `` வகைப்படுத்திகள் நீக்கப்படுகின்றன, மேலும் கருவிகள் அதைப் பற்றி பயனர்களுக்கு " +"தெரிவிக்கும் எச்சரிக்கையை வழங்கக்கூடும். `` உரிமம்` சரம் மதிப்பு (`` உரிமம்-வெளிப்பாடு`` " +"மேனிலை தரவு புலத்திற்கு மொழிபெயர்க்கிறது) மற்றும் `` உரிமம் :: `` வகைப்படுத்திகள் " +"பயன்படுத்தப்பட்டால் உருவாக்க கருவிகள் பிழையை எழுப்பக்கூடும்." + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "TOML_ வகை: சரங்களின் விசைகள் மற்றும் மதிப்புகள் கொண்ட அட்டவணை" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" +"தொடர்புடைய: ref: `கோர் மேனிலை தரவு <கோர்-மெட்டாடேட்டா>` புலம் :: குறிப்பு: `திட்டம்-" +"உர் <கோர்-மெட்டாடேட்டா-புரோசெக்ட்-உர்எல்>`" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" +"முகவரி களின் அட்டவணை முகவரி சிட்டை மற்றும் மதிப்பு முகவரி தானே. காண்க: குறிப்பு: " +"விளக்கக்காட்சிக்கான மெட்டாடேட்டாவை செயலாக்கும்போது இயல்பாக்குதல் விதிகள் மற்றும் நன்கு " +"அறியப்பட்ட விதிகளுக்கு `நன்கு அறியப்பட்ட-திட்ட-உர்எல்எச்`." + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "நுழைவு புள்ளிகள்" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" +"TOML_ வகை: அட்டவணை (`` [project.scripts] ``, `` [project.gui-scripts] ``, " +"மற்றும் `` [project.entry- புள்ளிகள்] ``)" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr ": Ref: `நுழைவு புள்ளிகள் விவரக்குறிப்பு <நுழைவு புள்ளிகள்>`" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" +"நுழைவு புள்ளிகள் தொடர்பான மூன்று அட்டவணைகள் உள்ளன. `` [Project.scripts] `` அட்டவணை " +"`` Console_scripts`` குழுவிற்கு ஒத்திருக்கிறது: ref: `நுழைவு புள்ளிகள் " +"விவரக்குறிப்பு <நுழைவு புள்ளிகள்>`. அட்டவணையின் விசை நுழைவு புள்ளியின் பெயர் மற்றும் " +"மதிப்பு பொருள் குறிப்பு." + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" +"`` [Project.gui-scripts] `` அட்டவணை `` gui_scripts`` குழுவிற்கு ஒத்திருக்கிறது: " +"ref: `நுழைவு புள்ளிகள் விவரக்குறிப்பு <நுழைவு புள்ளிகள்>`. அதன் வடிவம் `` " +"[project.scripts] `` போன்றது." + +#: ../source/specifications/pyproject-toml.rst:436 +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- புள்ளிகள்] `` அட்டவணை என்பது அட்டவணைகளின் தொகுப்பாகும். ஒவ்வொரு " +"துணை அட்டவணையின் பெயரும் ஒரு நுழைவு புள்ளி குழு. விசை மற்றும் மதிப்பு சொற்பொருள் `` " +"[project.scripts] `` போன்றவை. பயனர்கள் உள்ளமைக்கப்பட்ட துணை அட்டவணைகளை " +"உருவாக்கக்கூடாது, மாறாக நுழைவு புள்ளி குழுக்களை ஒரே ஒரு நிலைக்கு மட்டுமே ஆழமாக " +"வைத்திருக்க வேண்டும்." + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" +"மேனிலை தரவு ஒரு `` [project.entry- புள்ளிகள். `` [project.scripts] `` மற்றும் `` " +"[project.gui-scripts] ``." + +#: ../source/specifications/pyproject-toml.rst:455 +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` சரங்கள் (` `சார்புநிலைகள்``), மற்றும் வரிசைகளின் " +"மதிப்புகளைக் கொண்ட அட்டவணை: PEP:` 508` சரங்கள் (`` விருப்ப-சார்புநிலைகள்``)" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" +"தொடர்புடைய: `கோர் மேனிலை தரவு <கோர்-மெட்டாடேட்டா>` புலம் :: ref: `தேவைப்படுகிறது " +"<கோர்-மெட்டாடேட்டா-வேண்டுகோள்-டிச்ட்>` மற்றும்: குறிப்பு: `வழங்குகிறது-எக்ச்ட்ரா <கோர்-" +"மெட்டாடேட்டா-எக்ச்ட்ரா>`" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "திட்டத்தின் (விருப்ப) சார்புநிலைகள்." + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" +"`` சார்புகள்` `க்கு, இது ஒரு முக்கிய அம்சமாகும், அதன் மதிப்பு சரங்களின் வரிசை. ஒவ்வொரு " +"சரமும் திட்டத்தின் சார்புநிலையைக் குறிக்கிறது மற்றும் செல்லுபடியாகும் என வடிவமைக்கப்பட " +"வேண்டும்: PEP: `508` சரம். ஒவ்வொரு சரம் நேரடியாக A: ref: `தேவை-டிச்ட் <கோர்-" +"மெட்டாடேட்டா-வேண்டுகோள்-டிச்ட்>` நுழைவு தேவை." + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" +"`` விருப்ப-சார்புநிலைகளுக்கு`` க்கு, இது ஒரு அட்டவணை, ஒவ்வொரு விசையும் கூடுதல் " +"என்பதைக் குறிப்பிடுகிறது மற்றும் அதன் மதிப்பு சரங்களின் வரிசை. வரிசைகளின் சரங்கள் " +"செல்லுபடியாகும்: PEP: `508` சரங்கள். விசைகள் இதற்கான செல்லுபடியாகும் மதிப்புகளாக " +"இருக்க வேண்டும்: ref: `வழங்குகிறது-எக்ச்ட்ரா <கோர்-மெட்டாடேட்டா-வழங்கும்-எக்ச்ட்ரா>`. " +"வரிசையில் உள்ள ஒவ்வொரு மதிப்பும் தொடர்புடையது: ref: `தேவைப்படுகிறது <கோர்-மெட்டாடேட்டா-" +"வேண்டுகோள்-டிச்ட்>` பொருத்தத்திற்கான நுழைவு: ref: `வழங்கும்-எக்ச்ட்ரா <கோர்-மெட்டாடேட்டா-" +"வழங்கும்-எக்ச்ட்ரா>` மேனிலை தரவு." + +#: ../source/specifications/pyproject-toml.rst:485 +#, fuzzy +#| msgid "" +#| "Corresponding :ref:`core metadata ` field: :ref:`Name " +#| "`" +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" +"தொடர்புடைய: குறிப்பு: `கோர் மேனிலை தரவு <கோர்-மெட்டாடேட்டா>` புலம் :: குறிப்பு: " +"`பெயர் <கோர்-மெட்டாடேட்டா-பெயர்>`" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +#, fuzzy +#| msgid "Examples::" +msgid "Examples:" +msgstr "எடுத்துக்காட்டுகள் ::" + +#: ../source/specifications/pyproject-toml.rst:536 +#, fuzzy +#| msgid "" +#| "Corresponding :ref:`core metadata ` field: :ref:`Name " +#| "`" +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" +"தொடர்புடைய: குறிப்பு: `கோர் மேனிலை தரவு <கோர்-மெட்டாடேட்டா>` புலம் :: குறிப்பு: " +"`பெயர் <கோர்-மெட்டாடேட்டா-பெயர்>`" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +#, fuzzy +#| msgid "Example::" +msgid "Example:" +msgstr "எடுத்துக்காட்டு ::" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "TOML_ வகை: சரத்தின் வரிசை" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" +"தொடர்புடைய: ref: `கோர் மேனிலை தரவு <கோர்-மெட்டாடேட்டா>` புலம் :: குறிப்பு: `டைனமிக் " +"<கோர்-மெட்டாடேட்டா-டைனமிக்>`" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" +"இந்த PEP ஆல் பட்டியலிடப்பட்ட எந்த விசைகள் வேண்டுமென்றே குறிப்பிடப்படவில்லை என்பதைக் " +"குறிப்பிடுகிறது, எனவே மற்றொரு கருவி அத்தகைய மெட்டாடேட்டாவை மாறும் வகையில் வழங்க " +"முடியும். இது எந்த மேனிலை தரவு வேண்டுமென்றே குறிப்பிடப்படவில்லை மற்றும் பின்னர் கருவி " +"மூலம் வழங்கப்படுவதை ஒப்பிடும்போது குறிப்பிடப்படாமல் இருக்கும் என்று எதிர்பார்க்கப்படுகிறது." + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" +"ஒரு உருவாக்க பின்-இறுதி-குறிப்பிட்ட மெட்டாடேட்டாவை மதிக்க வேண்டும் (அதாவது மேனிலை " +"தரவு விசையை `` டைனமிக்`` இல் பட்டியலிடவில்லை)." + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" +"மேனிலை தரவு `` பெயர்`` இல் `` டைனமிக்`` ஐக் குறிப்பிடினால் ஒரு கட்டமைப்பை பின்-முடிவு " +"பிழையை உயர்த்த வேண்டும்." + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" +": Ref: `கோர் மேனிலை தரவு <கோர்-மெட்டாடேட்டா>` விவரக்குறிப்பு ஒரு துறையை \"தேவை\" " +"என்று பட்டியலிடுகிறது என்றால், மேனிலை தரவு விசையை சட்டப்பூர்வமாக குறிப்பிட வேண்டும் " +"அல்லது அதை `` டைனமிக்`` இல் பட்டியலிட வேண்டும் (பின்-முனைகளை உருவாக்குங்கள் இல்லையெனில் " +"பிழையை உயர்த்த வேண்டும் , அதாவது `` [திட்டம்] `` அட்டவணை) எப்படியாவது பட்டியலிடப்படாமல் " +"இருக்க முடியாது." + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" +"The: ref: `கோர் மேனிலை தரவு <கோர்-மெட்டாடேட்டா>` விவரக்குறிப்பு ஒரு துறையை " +"\"விருப்பமானது\" என்று பட்டியலிடுகிறது, மேனிலை தரவு அதை `` டைனமிக்`` இல் " +"பட்டியலிடலாம் என்றால், எதிர்பார்ப்பு ஒரு கட்டமைப்பை உருவாக்கினால் விசைக்கான தரவை வழங்கும் " +"பின்னர்." + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" +"மேனிலை தரவு ஒரு விசையை நிலையான முறையில் குறிப்பிடினால், `` டைனமிக்`` இல் " +"பட்டியலிடப்பட்டால் பின்-முனைகளை உருவாக்குங்கள் பிழையை உயர்த்த வேண்டும்." + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" +"மேனிலை தரவு ஒரு விசையை `` டைனமிக்`` இல் பட்டியலிடவில்லை என்றால், பயனரின் சார்பாக " +"தேவையான மெட்டாடேட்டாவை ஒரு கட்டமைப்பால் நிரப்ப முடியாது (அதாவது மெட்டாடேட்டாவை நிரப்ப " +"ஒரு கருவியை அனுமதிப்பதற்கான ஒரே வழி `` டைனமிக்`` மற்றும் பயனர் நிரப்பப்பட வேண்டும்)." + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" +"மேனிலை தரவு ஒரு விசையை `` டைனமிக்`` இல் குறிப்பிடினால், பின்-முனைகளை உருவாக்க " +"வேண்டும், ஆனால் அதற்கான தரவைத் தீர்மானிக்க முடியவில்லை (தரவைத் தவிர்ப்பது, துல்லியமான " +"மதிப்பாக தீர்மானிக்கப்பட்டால், ஏற்றுக்கொள்ளத்தக்கது) ." + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "தன்னிச்சையான கருவி உள்ளமைவு: `` [கருவி] `` அட்டவணை" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" +"`` [கருவி] `` அட்டவணை என்பது உங்கள் பைதான் திட்டத்துடன் தொடர்புடைய எந்தவொரு கருவியும், " +"கருவிகளை உருவாக்குவது மட்டுமல்லாமல், பயனர்கள் `` [கருவி] ``, எ.கா. `flit _ கருவி அதன் உள்ளமைவை` `[கருவி.ஃப்ளிட்]` `இல் சேமிக்கும்." + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" +"A mechanism is needed பெறுநர் allocate names within the ``tool.*`` namespace, " +"பெறுநர் make sure that different திட்டங்கள் do not attempt பெறுநர் use the same " +"sub-table and collide. Our விதி is that a திட்டம் can use the subtable ``tool." +"$NAME`` if, and only if, they own the நுழைவு க்கு ``$NAME`` in the Cheeseshop/" +"PyPI." + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" +"மே 2016: `` [பில்ட்-சிச்டம்] `` `` தேவை` `` விசையும் ஒரு `` [கருவி] `அட்டவணை, ஒரு` " +"`[பில்ட்-சிச்டம்]` `` அட்டவணை ஆகியவற்றைக் கொண்ட `` pyproject.toml`` கோப்பின் ஆரம்ப " +"விவரக்குறிப்பு அங்கீகரிக்கப்பட்டது மூலம்: PEP: `518`." + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" +"நவம்பர் 2020: `` [திட்டம்] `` அட்டவணையின் விவரக்குறிப்பு மூலம் அங்கீகரிக்கப்பட்டது: PEP: " +"`621`." + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" +"டிசம்பர் 2024: `` உரிமம்`` விசை மறுவரையறை செய்யப்பட்டது, `` உரிம-கோப்புகள்`` விசை " +"சேர்க்கப்பட்டு `` உரிமம் :: `` வகைப்படுத்திகள் நீக்கப்பட்டன: பெப்: `639`." + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "நிறுவப்பட்ட திட்டங்களை பதிவு செய்தல்" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" +"இந்த ஆவணம் பைதான் பற்றிய தகவல்களைப் பதிவுசெய்வதற்கான பொதுவான வடிவமைப்பைக் " +"குறிப்பிடுகிறது: கால: `திட்டங்கள் <திட்டம்>` சூழலில் நிறுவப்பட்டுள்ளது. ஒரு பொதுவான " +"மேனிலை தரவு வடிவம் திட்டங்களை எவ்வாறு நிறுவினாலும் அவற்றை வினவ, நிர்வகிக்க அல்லது " +"நிறுவல் நீக்க கருவிகளை அனுமதிக்கிறது." + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" +"கிட்டத்தட்ட எல்லா தகவல்களும் விருப்பமானவை. இது பைதான் சுற்றுச்சூழல் அமைப்புக்கு வெளியே " +"உள்ள கருவிகளை லினக்ச் தொகுப்பு மேலாளர்கள் போன்ற கருவிகளை பைதான் கருவியுடன் முடிந்தவரை " +"ஒருங்கிணைக்க அனுமதிக்கிறது. எடுத்துக்காட்டாக, பைதான் கருவிக்கு குறிப்பிட்ட வடிவத்தில் " +"நிறுவப்பட்ட கோப்புகளின் பட்டியலை ஒரு நிறுவி எளிதாக வழங்க முடியாவிட்டாலும், அது " +"நிறுவப்பட்ட திட்டத்தின் பெயர் மற்றும் பதிப்பை இன்னும் பதிவு செய்ய வேண்டும்." + +#: ../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``\" கோப்பகத்தை நிறுவ வேண்டும்." + +#: ../source/specifications/recording-installed-packages.rst:29 +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``,` `பெயர்`` மற்றும்` `பதிப்பு`` உடன் " +"தொடர்புடைய புலங்களுடன் பெயரிடப்பட்டுள்ளது: ref:` கோர்-மெட்டாடேட்டா`. இரண்டு புலங்களும் " +"இயல்பாக்கப்பட வேண்டும் (பார்க்க: ref: `பெயர் இயல்பாக்குதல் விவரக்குறிப்பு <பெயர்-" +"இயல்பாக்கம்>` மற்றும்: ref: `பதிப்பு இயல்பாக்கம் விவரக்குறிப்பு <பதிப்பு-விவரித்தல்-" +"இயல்பாக்கம்>`), மற்றும் டாசை மாற்றவும் (`` -``) அண்டர்ச்கோர் (`` _``) எழுத்துக்களைக் கொண்ட " +"எழுத்துக்கள், எனவே `` .டிச்ட்-இன்ஃபோ`` கோப்பகத்தில் எப்போதும் ஒரு கோடு (`` -``) அதன் " +"தண்டுகளில் உள்ள தன்மை, `` பெயர்`` மற்றும் `` பதிப்பு`` புலங்களை பிரிக்கிறது." + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" +"வரலாற்று ரீதியாக, கருவிகள் டாட் எழுத்துக்களை மாற்றவோ அல்லது வழக்கை `` பெயர்`` துறையில் " +"இயல்பாக்கவோ தவறிவிட்டன, அல்லது `` பதிப்பு`` புலத்தில் இயல்பாக்கத்தை செய்யக்கூடாது. " +"`` .Dist-info`` கோப்பகங்களை உட்கொள்ளும் கருவிகள் அந்தத் துறைகள் அசாதாரணப்படுத்தப்படும் " +"என்று எதிர்பார்க்க வேண்டும், மேலும் அவற்றை அவற்றின் இயல்பாக்கப்பட்ட சகாக்களுக்கு சமமாக " +"கருதுகின்றன. `` .Dist-info`` கோப்பகங்களை எழுதும் புதிய கருவிகள் மேலே விவரிக்கப்பட்ட " +"விதிகளைப் பயன்படுத்தி `` பெயர்``` மற்றும் `` பதிப்பு`` இரண்டையும் இயல்பாக்க வேண்டும், " +"மேலும் ஏற்கனவே இருக்கும் கருவிகள் அந்த துறைகளை இயல்பாக்கத் தொடங்க ஊக்குவிக்கப்படுகின்றன." + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" +"`` .Dist-info`` கோப்பகத்தின் பெயர் வடிவமைக்கப்பட்டுள்ளது, இது ஒரு விநியோகத்தை ஒரு " +"கோப்பு முறைமை பாதையாக பிரதிநிதித்துவப்படுத்துகிறது. ஒரு பயனருக்கு விநியோக பெயரை " +"வழங்கும் கருவிகள் இயல்பாக்கப்பட்ட பெயரைப் பயன்படுத்துவதைத் தவிர்க்க வேண்டும், அதற்கு பதிலாக " +"குறிப்பிட்ட பெயரை வழங்க வேண்டும் (நிறுவப்பட்ட தொகுப்புக்கு தீர்வு காண்பதற்கு முன்பு " +"தேவைப்படும்போது), அல்லது அந்தந்த புலங்களை கோர் மெட்டாடேட்டாவில் படிக்கவும், ஏனெனில் அங்கு " +"பட்டியலிடப்பட்ட மதிப்புகள் வெளியிடப்படாதவை மற்றும் துல்லியமாக உள்ளன விநியோகத்தை " +"பிரதிபலிக்கிறது. அத்தகைய கருவிகளை உட்கொள்வதற்கு நூலகங்கள் பநிஇ ஐ வழங்க வேண்டும், எனவே " +"விநியோக தகவல்களைக் காண்பிக்கும் போது கருவிகள் சிறப்பான பெயரை அணுகலாம்." + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" +"இந்த `.dist-info`` கோப்பகத்தில் பின்வரும் கோப்புகள் இருக்கலாம், இது கீழே விரிவாக " +"விவரிக்கப்பட்டுள்ளது:" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "`` மெட்டாடேட்டா``: திட்ட மெட்டாடேட்டாவைக் கொண்டுள்ளது" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "`` பதிவு``: நிறுவப்பட்ட கோப்புகளின் பட்டியலை பதிவு செய்யுங்கள்." + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" +"`` நிறுவி``: திட்டத்தை நிறுவ பயன்படுத்தப்படும் கருவியின் பெயரை பதிவு செய்கிறது." + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "`` entry_points.txt``: காண்க: குறிப்பு: விவரங்களுக்கு `நுழைவு புள்ளிகள்`" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "`` stread_url.json``: காண்க: குறிப்பு: விவரங்களுக்கு `நேரடி-உர்எல்`" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" +"`` மெட்டாடேட்டா`` கோப்பு கட்டாயமாகும். நிறுவும் கருவியின் விருப்பப்படி மற்ற எல்லா " +"கோப்புகளும் தவிர்க்கப்படலாம். கூடுதல் நிறுவி-குறிப்பிட்ட கோப்புகள் இருக்கலாம்." + +#: ../source/specifications/recording-installed-packages.rst:69 +#, fuzzy +#| msgid "" +#| "This :file:`.dist-info/` directory may contain the following directory, " +#| "described in detail below:" +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" +"இது: கோப்பு: `.dist-info/` கோப்பகத்தில் பின்வரும் கோப்பகத்தைக் கொண்டிருக்கலாம், இது கீழே " +"விரிவாக விவரிக்கப்பட்டுள்ளது:" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr ": கோப்பு: `உரிமங்கள்/`: உரிமக் கோப்புகளைக் கொண்டுள்ளது." + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" +"தி: ref: `பைனரி-விநியோக-வடிவ விவரக்குறிப்பு` விவரக்குறிப்பு `` .dist-info`` " +"கோப்பகத்தில் தோன்றக்கூடிய கூடுதல் கோப்புகளை விவரிக்கிறது: கால: `சக்கரம்`. இத்தகைய " +"கோப்புகள் நிறுவப்பட்ட திட்டத்தின் `` .dist-info`` கோப்பகத்திற்கு நகலெடுக்கப்படலாம்." + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" +"இந்த விவரக்குறிப்பின் முந்தைய பதிப்புகள் ஒரு `` கோரப்பட்ட`` கோப்பையும் குறிப்பிடுகின்றன. " +"இந்த கோப்பு இப்போது கருவி சார்ந்த நீட்டிப்பாக கருதப்படுகிறது, ஆனால் எதிர்காலத்தில் மீண்டும் " +"தரப்படுத்தப்படலாம். `PEP 376 ` _ அதன் அசல் அர்த்தத்திற்கு பார்க்கவும்." + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "மேனிலை தரவு கோப்பு" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" +"`` மெட்டாடேட்டா`` கோப்பில் விவரிக்கப்பட்டுள்ளபடி மேனிலை தரவு உள்ளது: ref: `கோர்-" +"மெட்டாடேட்டா` விவரக்குறிப்பு, பதிப்பு 1.1 அல்லது அதற்கு மேற்பட்டது." + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" +"`` மெட்டாடேட்டா`` கோப்பு கட்டாயமாகும். அதை உருவாக்க முடியாவிட்டால், அல்லது தேவைப்படும் " +"கோர் மேனிலை தரவு கிடைக்கவில்லை என்றால், நிறுவிகள் பிழையைப் புகாரளித்து திட்டத்தை " +"நிறுவத் தவறிவிட்டன." + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "பதிவு கோப்பு" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" +"`` பதிவு`` கோப்பு நிறுவப்பட்ட கோப்புகளின் பட்டியலைக் கொண்டுள்ளது. இது நிறுவப்பட்ட " +"கோப்புக்கு ஒரு பதிவு (வரி) கொண்ட காபிம கோப்பு." + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" +"சி.எச்.வி பேச்சுவழக்கு பைத்தானின் `` சி.எச்.வி`` தொகுதியின் இயல்புநிலை `` ரீடர்`` உடன் " +"படிக்கக்கூடியதாக இருக்க வேண்டும்:" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "புலம் டிலிமிட்டர்: ``, `` (கமா)," + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "கரியை மேற்கோள் காட்டுதல்: `` \"` `(நேராக இரட்டை மேற்கோள்)," + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "வரி டெர்மினேட்டர்: ஒன்று `` \\ r \\ n`` அல்லது `` \\ n``." + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" +"ஒவ்வொரு பதிவும் மூன்று கூறுகளால் ஆனது: கோப்பின் ** பாதை **, உள்ளடக்கங்களின் ** ஆச் ** " +"மற்றும் அதன் ** அளவு **." + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" +"* பாதை * முழுமையானதாக இருக்கலாம், அல்லது `.dist-info`` கோப்பகத்தைக் கொண்ட " +"கோப்பகத்துடன் தொடர்புடையதாக இருக்கலாம் (பொதுவாக,` `தள-பேக்கேச்கள்` கோப்பகம்). " +"சாளரங்களில், கோப்பகங்கள் முன்னோக்கி அல்லது பின்வாங்குவதன் மூலம் பிரிக்கப்படலாம் (``/`` " +"அல்லது `` \\ ``)." + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" +"* ஆச் * என்பது ஒரு வெற்று சரம் அல்லது ஒரு ஆச் வழிமுறையின் பெயர்: py: தரவு: " +"`hashlib.algorithms_guaranded`, அதைத் தொடர்ந்து சமமான தன்மை` `=` `மற்றும் கோப்பின் " +"உள்ளடக்கங்களின் டைசச்ட், URLSAFE உடன் குறியிடப்பட்டுள்ளது -பேச் 64-நோபாட் குறியாக்கம் (: " +"py: func: `base64.urlsafe_b64encode (டைசச்ட்) " +"`பின்னால்` `=` `அகற்றப்பட்டது)." + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" +"* அளவு * என்பது வெற்று சரம் அல்லது பைட்டுகளில் உள்ள கோப்பின் அளவு, அடிப்படை 10 முழு " +"எண்ணாக உள்ளது." + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" +"எந்தவொரு கோப்பிற்கும், அல்லது * ஆச் * மற்றும் * அளவு * புலங்கள் காலியாக விடப்படலாம். " +"பொதுவாக, `` .பிசி`` கோப்புகளுக்கான உள்ளீடுகள் மற்றும் `` பதிவு`` கோப்பில் வெற்று *ஆச் " +"*மற்றும் *அளவு *உள்ளன. மற்ற கோப்புகளுக்கு, நிறுவப்பட்ட திட்டத்தின் ஒருமைப்பாட்டை " +"சரிபார்க்கத் தடுக்கும் என்பதால், தகவல்களை வெளியே விட்டுவிடுவது ஊக்கமளிக்கிறது." + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" +"`` பதிவு`` கோப்பு இருந்தால், அது விருப்பமான `` பதிவு`` இல் பட்டியலிடப்பட்ட `` .பீ`` " +"கோப்புகளுடன் தொடர்புடைய `` .பிசி`` கோப்புகளைத் தவிர, திட்டத்தின் அனைத்து நிறுவப்பட்ட " +"கோப்புகளையும் பட்டியலிட வேண்டும். குறிப்பிடத்தக்க வகையில், `` .டிச்ட்-இன்ஃபோ`` கோப்பகத்தின் " +"உள்ளடக்கங்கள் (`` பதிவு`` கோப்பு உட்பட) பட்டியலிடப்பட வேண்டும். கோப்பகங்கள் " +"பட்டியலிடப்படக்கூடாது." + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" +"ஒரு தொகுப்பை முழுமையாக நிறுவல் நீக்க, ஒரு கருவி `` பதிவு``, அனைத்து `` .பிசி`` " +"கோப்புகள் (அனைத்து தேர்வுமுறை நிலைகளிலும்) அகற்றப்பட்ட `` .பீ`` கோப்புகளுடன் தொடர்புடைய " +"அனைத்து கோப்புகளையும் அகற்ற வேண்டும், மேலும் எந்த கோப்பகங்களும் காலியாகிவிட்டன நிறுவல் " +"நீக்குவதன் மூலம்." + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "சாத்தியமான `` பதிவு`` கோப்பின் சான்று இங்கே ::" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" +"`` பதிவு`` கோப்பு காணவில்லை என்றால், `` .dist-info`` ஐ நம்பியிருக்கும் கருவிகள் " +"தொகுப்பை நிறுவல் நீக்கவோ மேம்படுத்தவோ முயற்சிக்கக்கூடாது. (லினக்ச் டிச்ட்ரோசில் கணினி " +"தொகுப்பு மேலாளர்கள் போன்ற பிற தகவல்களின் ஆதாரங்களை நம்பியிருக்கும் கருவிகளுக்கு இந்த " +"கட்டுப்பாடு பொருந்தாது.)" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "நிறுவி கோப்பு" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" +"இருந்தால், `` நிறுவி`` என்பது திட்டத்தை நிறுவ பயன்படும் கருவியை பெயரிடும் ஒற்றை வரி " +"உரை கோப்பு. நிறுவி கட்டளை வரியிலிருந்து இயங்கக்கூடியதாக இருந்தால், `` நிறுவி`` " +"கட்டளை பெயரைக் கொண்டிருக்க வேண்டும். இல்லையெனில், அதில் அச்சிடக்கூடிய ASCII சரம் இருக்க " +"வேண்டும்." + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" +"கோப்பை பூச்சியம் அல்லது அதற்கு மேற்பட்ட ASCII வைட்ச்பேச் எழுத்துக்கள் மூலம் நிறுத்தலாம்." + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "சாத்தியமான இரண்டு `` நிறுவி` கோப்புகளின் எடுத்துக்காட்டுகள் இங்கே ::" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" +"இந்த மதிப்பு செய்தி நோக்கங்களுக்காக மட்டுமே பயன்படுத்தப்பட வேண்டும். எடுத்துக்காட்டாக, ஒரு " +"திட்டத்தை நிறுவல் நீக்க ஒரு கருவி கேட்கப்பட்டால், ஆனால் `` பதிவு`` கோப்பைக் கண்டறிந்தால், " +"`` நிறுவி`` இல் பெயரிடப்பட்ட கருவி நிறுவல் நீக்குதலைச் செய்ய முடியும் என்று அது " +"பரிந்துரைக்கலாம்." + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "Entery_points.txt கோப்பு" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" +"இந்த கோப்பு நிறுவிகளால் உருவாக்கப்படலாம், தொகுப்புகளில் கண்டுபிடிப்பு மற்றும் பிற " +"குறியீட்டால் பயன்படுத்தப்பட்ட கூறுகள் இருக்கும்போது, கன்சோல் ச்கிரிப்ட்கள் மற்றும் நிறுவி " +"செயல்படுத்தலுக்கு கிடைக்கக்கூடிய பிற பயன்பாடுகள் உள்ளிட்ட பிற குறியீடுகளால் " +"பயன்படுத்தப்படும் கூறுகள் இருக்கும்போது குறிக்கலாம்." + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "அதன் விரிவான விவரக்குறிப்பு: ref: `நுழைவு புள்ளிகள்`." + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "Direct_url.json கோப்பு" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" +"நேரடி முகவரி குறிப்பைக் குறிப்பிடும் தேவையிலிருந்து விநியோகத்தை நிறுவும் போது இந்த " +"கோப்பு நிறுவிகளால் உருவாக்கப்பட வேண்டும் (VCS முகவரி உட்பட)." + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "அதன் விரிவான விவரக்குறிப்பு உள்ளது: குறிப்பு: `நேரடி-உர்எல்`." + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "தி: கோப்பு: `உரிமங்கள்/` துணை அடைவு" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" +"மேனிலை தரவு பதிப்பு 2.4 அல்லது அதற்கு மேற்பட்டது மற்றும் ஒன்று அல்லது அதற்கு மேற்பட்ட `` " +"உரிம-கோப்பு` `புலங்கள் குறிப்பிடப்பட்டால்,: கோப்பு:` .டிச்ட்-இன்ஃபோ/`கோப்பகத்தில் ஒரு: " +"கோப்பு:` உரிமங்கள்/`துணை அடைவு இருக்க வேண்டும், அவை கொண்டிருக்க வேண்டும் `` உரிம-" +"கோப்பு`` புலங்களில் பட்டியலிடப்பட்ட கோப்புகள்: கோப்பு: `மெட்டாடேட்டா` அந்தந்த பாதைகளில்: " +"கோப்பு:` உரிமங்கள்/` அடைவு. இந்த கோப்பகத்தில் உள்ள எந்த கோப்புகளும் நிறுவும் கருவிகளால் " +"சக்கரங்களிலிருந்து நகலெடுக்கப்பட வேண்டும்." + +#: ../source/specifications/recording-installed-packages.rst:240 +#, fuzzy +#| msgid "The :file:`licenses/` subdirectory" +msgid "The :file:`sboms/` subdirectory" +msgstr "தி: கோப்பு: `உரிமங்கள்/` துணை அடைவு" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "நிறுவப்பட்ட தொகுப்புகளில் மாற்றங்களை வேண்டுமென்றே தடுக்கிறது" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" +"சில சந்தர்ப்பங்களில் (பைத்தான் சுற்றுச்சூழல் சார்புநிலைகளுக்கு கூடுதலாக வெளிப்புற " +"சார்புகளை நிர்வகிக்க வேண்டியிருக்கும் போது), பைதான் சூழலில் தொகுப்புகளை நிறுவும் ஒரு " +"கருவிக்கு இது விரும்பத்தக்கது, மற்ற கருவிகள் நிறுவப்பட்ட தொகுப்பை மாற்றியமைக்கவோ அல்லது " +"மாற்றியமைக்கவோ பயன்படுத்தப்படுவதில்லை என்பதை உறுதிப்படுத்த, அவ்வாறு செய்வது வைர சூழலில் " +"இணக்கத்தன்மை சிக்கல்களை ஏற்படுத்தக்கூடும்." + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "இதை அடைய, பாதிக்கப்பட்ட கருவிகள் பின்வரும் நடவடிக்கைகளை எடுக்க வேண்டும்:" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" +"பிற கருவிகள் வழியாக மாற்றங்களைத் தடுக்க `` பதிவு` `கோப்பை மறுபெயரிடுங்கள் அல்லது " +"அகற்றவும் (எ.கா. தரமற்ற` `பதிவு." + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" +"தொகுப்பை நிர்வகிக்கப் பயன்படுத்த வேண்டிய கருவியின் பெயரைக் குறிக்கும் `` நிறுவி`` கோப்பை " +"எழுதுங்கள் (பாதிக்கப்பட்ட தொகுப்புகளை மாற்றும்படி கேட்கும்போது `` பதிவு``-விழிப்புணர்வை " +"சிறந்த பிழை அறிவிப்புகளை வழங்க இது அனுமதிக்கிறது)" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" +"பைதான் இயக்க நேர வழங்குநர்கள் இயங்குதளம் வழங்கப்பட்ட தொகுப்புகளை மாற்றியமைப்பதன் மூலம் " +"இயங்குதளத்தின் கவனக்குறைவான மாற்றத்தைத் தடுக்கலாம், இயல்புநிலை பைதான் தொகுப்பு நிறுவல் " +"திட்டத்தை மேடையில் வழங்கப்பட்ட தொகுப்புகளால் பயன்படுத்தப்படுவதைத் தவிர வேறு இடத்தைப் " +"பயன்படுத்தலாம் (அதே நேரத்தில் இரு இடங்களும் இயல்புநிலை பைதான் இறக்குமதி பாதையில் " +"தோன்றுவதை உறுதிசெய்கின்றன)." + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" +"சில சூழ்நிலைகளில், பைதான்-குறிப்பிட்ட கருவிகள் வழியாக கூடுதல் தொகுப்புகளை நிறுவுவதைத் " +"தடுப்பது விரும்பத்தக்கதாக இருக்கலாம். இந்த நிகழ்வுகளுக்கு: ref: `வெளிப்புறமாக " +"நிர்வகிக்கப்பட்ட-சூழல்கள்`" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" +"சூன் 2009: இந்த விவரக்குறிப்பின் அசல் பதிப்பு அங்கீகரிக்கப்பட்டது: PEP: `376`. அந்த " +"நேரத்தில், இது நிறுவப்பட்ட பைதான் விநியோகங்களின் *தரவுத்தளமாக அறியப்பட்டது *." + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" +"மார்ச் 2020: `` `direct_url.json`` கோப்பின் விவரக்குறிப்பு மூலம் அங்கீகரிக்கப்பட்டது: " +"PEP:` 610`. இது இந்த பக்கத்தில் மட்டுமே குறிப்பிடப்பட்டுள்ளது; காண்க: குறிப்பு: முழு " +"வரையறைக்கு `நேரடி-உர்எல்`." + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" +"செப்டம்பர் 2020: பல்வேறு திருத்தங்கள் மற்றும் விளக்கங்கள் மூலம் அங்கீகரிக்கப்பட்டன: PEP: `627`." + +#: ../source/specifications/schemas/index.rst:4 +#, fuzzy +#| msgid "Data schema" +msgid "PyPA schemas" +msgstr "தரவுத் திட்டம்" + +#: ../source/specifications/schemas/index.rst:6 +#, fuzzy +#| msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgid "`direct_url.json `_" +msgstr "`` stread_url.json``: காண்க: குறிப்பு: விவரங்களுக்கு `நேரடி-உர்எல்`" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "தொகுப்பு நிறுவல் மேனிலை தரவு" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "தொகுப்பு குறியீட்டு இடைமுகங்கள்" + +#: ../source/specifications/section-python-description-formats.rst:3 +#, fuzzy +#| msgid "Python versions over time" +msgid "Python Description Formats" +msgstr "காலப்போக்கில் பைதான் பதிப்புகள்" + +#: ../source/specifications/section-reproducible-environments.rst:3 +#, fuzzy +#| msgid "Virtual Environment" +msgid "Reproducible Environments" +msgstr "மெய்நிகர் சூழல்" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "எளிய களஞ்சிய பநிஇ" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +#, fuzzy +#| msgid "" +#| "The interface for querying available package versions and retrieving " +#| "packages from an index server comes in two forms: HTML and JSON." +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" +"கிடைக்கக்கூடிய தொகுப்பு பதிப்புகளை வினவுவதற்கும், குறியீட்டு சேவையகத்திலிருந்து " +"தொகுப்புகளை மீட்டெடுப்பதற்கும் இடைமுகம் இரண்டு வடிவங்களில் வருகிறது: உஉகுமொ மற்றும் சேசன்." + +#: ../source/specifications/simple-repository-api.rst:21 +#, fuzzy +#| msgid "Base HTML API" +msgid "Base API" +msgstr "அடிப்படை உஉகுமொ பநிஇ" + +#: ../source/specifications/simple-repository-api.rst:23 +#, fuzzy +#| 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/``." +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/``." +msgstr "" +"எளிய பநிஇ ஐ செயல்படுத்தும் ஒரு களஞ்சியம் அதன் அடிப்படை முகவரி ஆல் வரையறுக்கப்படுகிறது, " +"இது அனைத்து கூடுதல் முகவரி களும் கீழே உள்ளது. பைபியின் அடிப்படை முகவரி `` https: // " +"pypi.org/simple/`` என்ற காரணத்தினால் பநிஇ க்கு \"எளிய\" களஞ்சியம் என்று " +"பெயரிடப்பட்டுள்ளது." + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" +"இந்த ஆவணத்தில் உள்ள அனைத்து அடுத்தடுத்த முகவரி களும் இந்த அடிப்படை முகவரி உடன் " +"தொடர்புடையதாக இருக்கும் (எனவே பைபியின் முகவரி கொடுக்கப்பட்டால், ``/foo/`` முகவரி `` " +"https: // pypi.org/simple/foo/`` ஆக இருக்கும்." + +#: ../source/specifications/simple-repository-api.rst:33 +msgid "Normalized Names" +msgstr "இயல்பாக்கப்பட்ட பெயர்கள்" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" +"இந்த விவரக்குறிப்பு \"இயல்பாக்கப்பட்ட\" திட்ட பெயரின் கருத்தை குறிக்கிறது. படி: ref: " +"`பெயர் இயல்பாக்குதல் விவரக்குறிப்பு <பெயர்-இயல்பாக்கம்>` ஒரு பெயரில் உள்ள ஒரே " +"செல்லுபடியாகும் எழுத்துக்கள் தபஅஇகு எழுத்துக்கள், தபஅஇகு எண்கள், `` .``, `` -``, மற்றும் " +"`` _``. ```,` `-``, அல்லது` `_`` ஒரு ஒற்றை` `-`` எழுத்துடன் மாற்றப்பட்ட எழுத்துக்களின் " +"அனைத்து ரன்களிலும் பெயர் குறைவாக இருக்க வேண்டும். இதை பைத்தானில் `` ரீ`` தொகுதி :: உடன் " +"செயல்படுத்தலாம்" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "பதிப்பு PYPI எளிய பநிஇ" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "களஞ்சிய பதிப்பை விளக்கும் போது:" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" +"முக்கிய பதிப்பை அதிகரிப்பது பின்னோக்கி பொருந்தாத மாற்றத்தை சமிக்ஞை செய்யப் பயன்படுகிறது, " +"அதாவது இருக்கும் வாடிக்கையாளர்கள் இனி பநிஇ ஐ அர்த்தமுள்ளதாக பயன்படுத்த முடியும் என்று " +"எதிர்பார்க்க முடியாது." + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" +"சிறிய பதிப்பை அதிகரிப்பது பின்னோக்கி இணக்கமான மாற்றத்தைக் குறிக்கப் பயன்படுகிறது, " +"அதாவது இருக்கும் வாடிக்கையாளர்கள் பநிஇ ஐ அர்த்தமுள்ளதாக பயன்படுத்த முடியும் என்று " +"எதிர்பார்க்கப்படுகிறது." + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" +"தற்போதுள்ள வாடிக்கையாளர்கள் பநிஇ ஐ \"அர்த்தமுள்ள வகையில்\" பயன்படுத்த முடியும் என்ற பரந்த " +"பரிந்துரைக்கு அப்பால் பின்னோக்கி பொருந்தாத Vs இணக்கமான மாற்றத்தை குறிப்பாக உருவாக்குவது " +"குறித்து எதிர்கால விவரக்குறிப்புகளின் விருப்பப்படி இது விடப்படுகிறது, மேலும் ஏற்கனவே " +"உள்ள அம்சங்களைச் சேர்ப்பது, மாற்றியமைப்பது அல்லது அகற்றுவது ஆகியவை அடங்கும்." + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" +"முக்கிய பதிப்பு ஒருபோதும் அதிகரிக்கப்படாது என்பது இந்த விவரக்குறிப்பின் எதிர்பார்ப்பாகும், " +"மேலும் எதிர்கால பெரிய பநிஇ பரிணாமங்கள் பநிஇ படிமலர்ச்சி வளர்ச்சிக்கு வேறுபட்ட " +"வழிமுறையைப் பயன்படுத்தும். எவ்வாறாயினும், எதிர்கால பதிப்புகளுடன் (எ.கா.." + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "வாடிக்கையாளர்கள்" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" +"எளிய பநிஇ உடன் தொடர்பு கொள்ளும் வாடிக்கையாளர்கள் ** களஞ்சிய பதிப்பிற்கான ஒவ்வொரு " +"பதிலையும் ** உள்நோக்கிக் கொள்ள வேண்டும், மேலும் அந்த தரவு இல்லை என்றால் ** ** இது பதிப்பு " +"1.0 என்று கருத வேண்டும்." + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" +"ஒரு சிறிய பதிப்பை எதிர்பார்த்ததை விட அதிகமாக எதிர்கொள்ளும்போது, வாடிக்கையாளர்கள் ** ** " +"பொருத்தமான செய்தியுடன் பயனர்களை எச்சரிக்க வேண்டும்." + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +#, fuzzy +#| msgid "JSON Serialization" +msgid "HTML Serialization" +msgstr "சாதொபொகு சீரியலைசேசன்" + +#: ../source/specifications/simple-repository-api.rst:125 +#, fuzzy +#| msgid "" +#| "The following constraints apply to all JSON serialized responses " +#| "described in this spec:" +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" +"இந்த விவரக்குறிப்பில் விவரிக்கப்பட்டுள்ள அனைத்து சாதொபொகு தொடர் பதில்களுக்கும் பின்வரும் " +"தடைகள் பொருந்தும்:" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +msgid "Project List" +msgstr "திட்ட பட்டியல்" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +msgid "Project Detail" +msgstr "திட்ட விவரம்" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +#, fuzzy +#| 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." +msgid "" +"Each file 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 "" +"களஞ்சியமான ** ** கோர் மேனிலை தரவு கோப்பின் ஆசை `` = `` " +"என்ற தொடரியல் பயன்படுத்தி `` = , அங்கு `` `` `` `` " +"`=``, 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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" +"ஒரு களஞ்சியம் ** ஒரு சிபிசி கையொப்பம் உள்ளதா இல்லையா என்பதைக் குறிக்க `` உண்மை`` அல்லது " +"`` தவறு` ஆகியவற்றின் மதிப்புடன் ஒரு கோப்பு இணைப்பில் `` தரவு-சிபிசி-சிக்`` பண்புக்கூறு " +"இருக்கலாம். இதைச் செய்யும் களஞ்சியங்கள் ** ** ஒவ்வொரு இணைப்பிலும் இதை சேர்க்க வேண்டும்." + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" +"பண்புக்கூறு மதிப்பில், <மற்றும்> உஉகுமொ முறையே `` & lt; `` மற்றும் `` & gt; `` என " +"குறியிடப்பட வேண்டும்." + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +#, fuzzy +#| 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." +msgid "" +"The ``data-yanked`` attribute 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:253 +#, fuzzy +#| 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." +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." +msgstr "" +"`` டேட்டா-யாங்கட்`` பண்புக்கூறின் மதிப்பு, இருந்தால், ஒரு தன்னிச்சையான சரம், இது கோப்பு " +"ஏன் அசைக்கப்பட்டது என்பதற்கான காரணத்தைக் குறிக்கிறது. எளிய களஞ்சிய பநிஇ ** செயலாக்கும் " +"கருவிகள் ** இந்த சரத்தை இறுதி பயனர்களுக்கு மேற்பரப்பு செய்யலாம்." + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" +"ஒரு களஞ்சியம் ** ஒரு கோப்பு இணைப்பில் ஒரு `` தரவு-ஆதாரம்`` பண்புக்கூறு சேர்க்கப்படலாம். " +"இந்த பண்புக்கூறு ** ** ஒரு முழுமையான தகுதி வாய்ந்த முகவரி ஆக இருக்க வேண்டும், இது " +"கோப்பின் ஆதாரத்தை அந்த முகவரி இல் காணலாம் என்பதைக் குறிக்கிறது. இந்த முகவரி ** ** ஒரு " +"`பாதுகாப்பான தோற்றத்தை ` _ ஆகியவற்றைக் குறிக்க வேண்டும்." + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" +"இணைக்கப்பட்ட ஆதாரத்தின் வடிவம் இதில் வரையறுக்கப்பட்டுள்ளது: குறிப்பு: `குறியீட்டு-ஓச்ட்-" +"அட்டெச்டெச்டேசன்ச்`." + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "எளிய களஞ்சிய பநிஇ இல் விநியோக மெட்டாடேட்டாவை பரிமாறவும்" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" +"ஒரு `` தரவு-டிச்ட்-இன்ஃபோ-மெட்டாடேட்டா`` பண்புக்கூறு இருந்தால், களஞ்சியம் ** " +"விநியோகத்தின் கோர் மேனிலை தரவு கோப்பை விநியோகிப்பதன் மூலம் விநியோகத்தின் கோப்பு " +"பெயருடன் சேர்க்கப்பட்ட விநியோகத்தின் முக்கிய மேனிலை தரவு கோப்பை வழங்க வேண்டும். " +"எடுத்துக்காட்டாக, ``/கோப்புகள்/விநியோகம் -1.0-py3.none.non.whl`` இல் வழங்கப்படும் ஒரு " +"விநியோகத்தின் முக்கிய மேனிலை தரவு ``/கோப்புகள்/விநியோகம் -1.0-" +"py3.none.non.whl.metadata`` இல் அமைந்திருக்கும். இது எப்படி: ref: `அடிப்படை உஉகுமொ " +"பநிஇ விவரக்குறிப்பு <எளிய-ரெபோசிட்டரி-API-BASE>` சிபிசி கையொப்பக் கோப்பின் " +"இருப்பிடத்தைக் குறிப்பிடுகிறது." + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" +"களஞ்சியமான ** ** கோர் மேனிலை தரவு கோப்பின் ஆசை `` = `` " +"என்ற தொடரியல் பயன்படுத்தி `` = , அங்கு `` `` `` `` " +"``) should be serialized using `JSON `_." +msgstr "" +"நிலையான நூலகத்துடன் மட்டுமே பாகுபடுத்தலை இயக்க, இந்த விவரக்குறிப்பு அனைத்து " +"பதில்களையும் (கோப்புகளும் தவிர, மற்றும் உஉகுமொ பதில்கள் இதிலிருந்து: ref: `அடிப்படை " +"உஉகுமொ பநிஇ விவரக்குறிப்பு `) `json ` 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 "" +"சுழிய உள்ளமைவு கண்டுபிடிப்பை செயல்படுத்தவும், கூடுதல் HTTP கோரிக்கைகளின் அளவைக் " +"குறைக்கவும், இந்த விவரக்குறிப்பு நீட்டிக்கப்படுகிறது: ref: `அடிப்படை உஉகுமொ பநிஇ " +"விவரக்குறிப்பு <எளிய-ரெபோசிட்டரி-API-BASE>` அதாவது அனைத்து பநிஇ முடிவுப்புள்ளிகளும் " +"(கோப்புகளைத் தவிர) HTTP உள்ளடக்க பேச்சுவார்த்தை மற்றும் சேவையகத்தை அனுமதிக்க மற்றும் " +"சேவையகத்தை அனுமதிக்கும்." + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" +"பதிப்பு இதைக் கடைப்பிடிக்கும்: குறிப்பு: `ஏபிஐ பதிப்பு விவரக்குறிப்பு <எளிய-" +"ரோபோசிட்டரி-ஆப்-ப்ரிசர்னிங்>` வடிவமைப்பு (`` மேசர்.மினோர்``), இது தற்போதுள்ள உஉகுமொ " +"பதில்களை `` 1.0`` என்று வரையறுத்துள்ளது. இந்த விவரக்குறிப்பு பநிஇ இல் புதிய அம்சங்களை " +"அறிமுகப்படுத்தவில்லை என்பதால், இது தற்போதுள்ள அம்சங்களுக்கான வேறுபட்ட சீரியலைசேசன் " +"வடிவமைப்பை விவரிக்கிறது, இந்த விவரக்குறிப்பு தற்போதுள்ள `` 1.0`` பதிப்பை மாற்றாது, " +"அதற்கு பதிலாக அதை சாதொபொகு இல் எவ்வாறு வரிசைப்படுத்துவது என்பதை விவரிக்கிறது." + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" +"ஒத்தது: குறிப்பு: `ஏபிஐ பதிப்பு விவரக்குறிப்பு <எளிய-ரோபோசிட்டரி-ஆப்-ப்ரிசர்னிங்>`, " +"புதிய வடிவத்தில் ஏதேனும் மாற்றங்கள் இருந்தால், தற்போதுள்ள வாடிக்கையாளர்கள் வடிவமைப்பை " +"அர்த்தமுள்ளதாக புரிந்துகொள்வார்கள் என்று எதிர்பார்க்க முடியாது என்றால் முக்கிய பதிப்பு எண் " +"** ** அதிகரிக்கப்பட வேண்டும்." + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" +"அதேபோல், நற்பொருத்தங்கள் சேர்க்கப்பட்டால் அல்லது வடிவமைப்பிலிருந்து அகற்றப்பட்டால் சிறிய " +"பதிப்பு ** ** அதிகரிக்கப்பட வேண்டும், ஆனால் தற்போதுள்ள வாடிக்கையாளர்கள் தொடர்ந்து " +"வடிவமைப்பை அர்த்தமுள்ளதாக புரிந்துகொள்வார்கள் என்று எதிர்பார்க்கப்படுகிறது." + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" +"தற்போதுள்ள வாடிக்கையாளர்கள் வடிவமைப்பை அர்த்தமுள்ளதாக புரிந்து கொள்ள முடியாமல் போகாத " +"மாற்றங்கள் மற்றும் சேர்க்கப்படும் அல்லது அகற்றப்படும் அம்சங்களைக் குறிக்காத மாற்றங்கள் பதிப்பு " +"எண்ணை மாற்றாமல் ஏற்படலாம்." + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" +"இது வேண்டுமென்றே தெளிவற்றது, ஏனெனில் இந்த விவரக்குறிப்பு எதிர்கால விவரக்குறிப்புகளுக்கு " +"சிறந்தது என்று நம்புகிறது, இது ஏபிஐக்கு ஏதேனும் மாற்றங்களைச் செய்து, அந்த மாற்றம் பெரிய " +"அல்லது சிறிய பதிப்பை அதிகரிக்க வேண்டுமா இல்லையா என்பதை தீர்மானிக்க வேண்டும்." + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" +"பநிஇ இன் எதிர்கால பதிப்புகள் அந்த பதிப்பின் கிடைக்கக்கூடிய சீரியலைசேசன்களின் " +"துணைக்குழுவில் மட்டுமே குறிப்பிடக்கூடிய விசயங்களைச் சேர்க்கலாம். அனைத்து சீரியலைசேசன்ச் " +"பதிப்பு எண்களும், ஒரு பெரிய பதிப்பிற்குள், ** ** ஒத்திசைவில் இருக்க வேண்டும், ஆனால் " +"ஒவ்வொரு வடிவமைப்பிலும் ஒரு நற்பொருத்தம் எவ்வாறு வரிசைப்படுத்துகிறது என்பதற்கான விவரங்கள், " +"அந்த நற்பொருத்தம் உள்ளதா இல்லையா என்பது உட்பட." + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" +"இந்த விவரக்குறிப்பின் நோக்கம், பநிஇ தரவைத் தரும் முகவரி இறுதிப் புள்ளிகளாக கருதப்பட " +"வேண்டும், அதன் விளக்கம் அந்த தரவின் பதிப்பால் வரையறுக்கப்படுகிறது, பின்னர் இலக்கு " +"சீரியலைசேசன் வடிவத்தில் வரிசைப்படுத்தப்படுகிறது." + +#: ../source/specifications/simple-repository-api.rst:390 +msgid "JSON Serialization" +msgstr "சாதொபொகு சீரியலைசேசன்" + +#: ../source/specifications/simple-repository-api.rst:392 +#, fuzzy +#| 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." +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 "" +"முகவரி அமைப்பு: ref: `அடிப்படை உஉகுமொ பநிஇ விவரக்குறிப்பு <எளிய-ரெபோசிட்டரி-API-" +"BASE>` இன்னும் பொருந்தும், ஏனெனில் இந்த விவரக்குறிப்பு ஏற்கனவே இருக்கும் பநிஇ க்கு " +"கூடுதல் சீரியலைசேசன் வடிவமைப்பை மட்டுமே சேர்க்கிறது." + +#: ../source/specifications/simple-repository-api.rst:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" +"இந்த விவரக்குறிப்பில் விவரிக்கப்பட்டுள்ள அனைத்து சாதொபொகு தொடர் பதில்களுக்கும் பின்வரும் " +"தடைகள் பொருந்தும்:" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" +"அனைத்து சாதொபொகு பதில்களும் * எப்போதும் * ஒரு வரிசை அல்லது பிற வகையை விட சாதொபொகு " +"பொருளாக இருக்கும்." + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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 "" +"அனைத்து சாதொபொகு பதில்களிலும் `` meta.api-version`` விசைக் கொண்டிருக்கும், இது: " +"ref: `ஏபிஐ பதிப்பு விவரக்குறிப்பு <எளிய-ரோபோசிட்டரி-ஆபி-புரிதல்>` `` `மேசர்.மினோர்` " +"பதிப்பு எண், அதே தோல்வி/எச்சரிக்கை சொற்பொருள்கள்:` ஆப்-டெவிங்-டெவிங்-டெவிங்-டி-அப்-டெவிங்-" +"டி-அப்-டெவிங்-டெவிங்-டெவிங்-டெவிங்-டெவிங்-டெவிங்-டெவிங்-டன்-ரெசோரிங்-டோரிங்-டன்-ரெசோரிச்" + +#: ../source/specifications/simple-repository-api.rst:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" +"இதன் அனைத்து தேவைகளும்: Ref: `அடிப்படை உஉகுமொ பநிஇ விவரக்குறிப்பு ` அவை உஉகுமொ குறிப்பிட்டவை அல்ல." + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" +"ஒரு முன்னணி அடிக்கோடிட்டுக் கொண்ட விசைகள் (எந்த மட்டத்திலும்) குறியீட்டு சேவையக " +"பயன்பாட்டிற்கு தனிப்பட்டதாக ஒதுக்கப்பட்டுள்ளன. அத்தகைய எந்தவொரு விசைக்கும் எதிர்கால தரநிலை " +"ஒரு அர்த்தத்தை ஒதுக்காது." + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" +"`` மெட்டா``: முன்னர் விவரிக்கப்பட்டுள்ள பொதுவான மறுமொழி மேனிலை தரவு ____." + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "உதாரணமாக:" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" +"`` பெயர்`` புலம் இதிலிருந்து சமம்: ref: `அடிப்படை உஉகுமொ பநிஇ விவரக்குறிப்பு <எளிய-" +"ரெபோசிட்டரி-API-BASE>`, இது இயல்பாக்கப்படாத காட்சி பெயர் அல்லது இயல்பாக்கப்பட்ட பெயர் " +"என்பதைக் குறிப்பிடவில்லை. நடைமுறையில் இந்த விவரக்குறிப்புகளின் வெவ்வேறு செயலாக்கங்கள் " +"இங்கே வித்தியாசமாகத் தேர்வு செய்கின்றன, எனவே அதை இயல்பாக்காத அல்லது இயல்பாக்கப்படுவதை " +"நம்பியிருப்பது கேள்விக்குரிய களஞ்சியத்தின் செயல்படுத்தல் விவரத்தை நம்பியுள்ளது." + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" +"`` திட்டங்கள்`` விசை ஒரு வரிசை, இதனால் ஒருவித வரிசையில் இருக்க வேண்டும், மேலும்: ref: " +"`அடிப்படை உஉகுமொ பநிஇ விவரக்குறிப்பு <எளிய-ரோபோசிட்டரி-API-BASE>` அல்லது இந்த " +"விவரக்குறிப்புக்கு ஏதேனும் குறிப்பிட்ட வரிசைப்படுத்தல் தேவைப்படுகிறது அல்லது " +"வரிசைப்படுத்தல் ஒரு கோரிக்கையிலிருந்து அடுத்ததாக ஒத்துப்போகிறது. மனரீதியாக இது ஒரு " +"தொகுப்பாக சிறந்ததாக கருதப்படுகிறது, ஆனால் சாதொபொகு மற்றும் உஉகுமொ இரண்டுமே " +"தொகுப்புகளைக் கொண்டிருப்பதற்கான செயல்பாட்டைக் கொண்டிருக்கவில்லை." + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" +"இந்த முகவரி இன் வடிவம் ``//`` `` `<திட்டம்>` `என்பதன் மூலம் மாற்றப்படுகிறது: " +"ref:` அடிப்படை உஉகுமொ பநிஇ விவரக்குறிப்பு <எளிய-ரோபோசிட்டரி-API-BASE> `அந்த " +"திட்டத்திற்கான இயல்பாக்கப்பட்ட பெயர், எனவே\" சில்லி_வல் \"போன்ற ஒரு திட்டம்` `` `` `` `` " +"`` `` `` `." + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "`` பெயர்``: திட்டத்தின் இயல்பாக்கப்பட்ட பெயர்." + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "`` கோப்புகள்``: அகராதிகளின் பட்டியல், ஒவ்வொன்றும் ஒரு தனிப்பட்ட கோப்பைக் குறிக்கும்." + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" +"`` கோப்புகள்` விசையில் பட்டியலிடப்பட்டுள்ள அனைத்து கோப்புகளும் `` பதிப்புகள்` `விசையில் " +"உள்ள பதிப்புகளில் ஒன்றோடு தொடர்புடையதாக இருக்க வேண்டும். `` பதிப்புகள்`` விசையில் " +"தொடர்புடைய கோப்புகள் இல்லாத பதிப்புகள் இருக்கலாம் (சேவையகத்திற்கு அத்தகைய கருத்து " +"இருந்தால், கோப்புகள் பதிவேற்றப்படாத பதிப்புகளைக் குறிக்க)." + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "ஒவ்வொரு தனிப்பட்ட கோப்பு அகராதியிலும் பின்வரும் விசைகள் உள்ளன:" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "`` கோப்பு பெயர்``: பிரதிநிதித்துவப்படுத்தப்படும் கோப்பு பெயர்." + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "`` url``: கோப்பிலிருந்து பெறக்கூடிய முகவரி." + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" +"`` ஆச்கள்``: கோப்பின் ஃச் குறியிடப்பட்ட டைசெச்டுக்கு ஒரு ஆச் பெயரை மேப்பிங் செய்வது ஒரு " +"அகராதி. பல ஆச்களைச் சேர்க்கலாம், மேலும் பல ஆச்களை என்ன செய்வது என்று வாடிக்கையாளரின் " +"தீர்மானிக்க வேண்டும் (இது அவை அனைத்தையும் அல்லது அவற்றின் துணைக்குழுவை சரிபார்க்கக்கூடும், " +"அல்லது ஒன்றும் இல்லை). இந்த ஆச் பெயர்கள் ** ** எப்போதும் சிறிய எழுத்துக்களாக இயல்பாக்கப்பட " +"வேண்டும்." + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" +"இயல்பாக, எந்த ஆச் வழிமுறையும் மூலம் கிடைக்கும்: PY: MOD: `Hashlib` (குறிப்பாக ஏதேனும் " +"தேர்ச்சி பெறக்கூடியது: PY: FUNC:` Hashlib.new () `மற்றும் கூடுதல் அளவுருக்கள் " +"தேவையில்லை) ஆசேச் அகராதிக்கு ஒரு திறவுகோலாகப் பயன்படுத்தப்படலாம். இருந்து குறைந்தது " +"ஒரு பாதுகாப்பான வழிமுறை: PY: தரவு: `hashlib.algorithms_ugranaled` ** ** " +"எப்போதும் சேர்க்கப்பட வேண்டும். இந்த விவரக்குறிப்பின் போது, `` சா 256`` குறிப்பாக " +"பரிந்துரைக்கப்படுகிறது." + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" +"``-பைதான் தேவை ``: ஒரு ** விருப்ப ** விசை: ref: `கோர்-மெட்டாடேட்டா-முன்நிபந்தனைகள்-" +"மெட்டாடேட்டா புலம். இது இருக்கும் இடத்தில், நிறுவி கருவிகள் ** ** தேவையை நிறைவு " +"செய்யாத பைதான் பதிப்பில் நிறுவும் போது பதிவிறக்கத்தை புறக்கணிக்க வேண்டும்." + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" +"`` தரவு-வேண்டுகோள்கள்-பைதான்`` இல்: குறிப்பு: `அடிப்படை உஉகுமொ பநிஇ விவரக்குறிப்பு " +"` `,` `-` விசைக்கு தேவையில்லை சாதொபொகு இயல்பாகவே " +"எதையும் தவிர வேறு எந்த சிறப்பு தப்பிப்பும் தேவையில்லை." + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" +"இது ஒரு பூலியனுக்கு பதிலாக ஆச்களின் அகராதியாக இருக்கும்போது, `` ஆச்கள்`` விசையின் " +"அதே தேவைகள் மற்றும் பரிந்துரைகள் அனைத்தும் இந்த விசையிலும் உண்மையாகவே இருக்கின்றன." + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" +"இந்த விசை காணவில்லை என்றால், மேனிலை தரவு கோப்பு இருக்கலாம் அல்லது இல்லாமல் இருக்கலாம். " +"முக்கிய மதிப்பு உண்மையாக இருந்தால், மேனிலை தரவு கோப்பு உள்ளது, அது பொய்யானது என்றால் " +"அது இல்லை." + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" +"சேவையகங்கள் மேனிலை தரவு கோப்பின் ஆச்களை முடிந்தால் கிடைக்கச் செய்ய பரிந்துரைக்கப்படுகிறது." + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" +"`` gpg-sig``: கோப்பில் தொடர்புடைய சிபிசி கையொப்பம் உள்ளதா இல்லையா என்பதைக் குறிக்க ஒரு " +"பூலியன் செயல்படும் ஒரு ** விருப்ப ** விசை. கையொப்பக் கோப்பிற்கான முகவரி இதில் " +"குறிப்பிடப்பட்டுள்ளதைப் பின்பற்றுகிறது: ref: `அடிப்படை உஉகுமொ பநிஇ விவரக்குறிப்பு " +"` (`{file_url} .asc``). இந்த விசை இல்லை என்றால், " +"கையொப்பம் இருக்கலாம் அல்லது இல்லாமல் இருக்கலாம்." + +#: ../source/specifications/simple-repository-api.rst:595 +#, fuzzy +#| 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 `." +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\"." +msgstr "" +"`` yanked``: ஒரு ** விருப்பமான ** விசை, இது கோப்பு அலறப்பட்டதா என்பதைக் குறிக்க ஒரு " +"பூலியனாக இருக்கலாம், அல்லது காலியாக இல்லாதது, ஆனால் இல்லையெனில் தன்னிச்சையானது, ஒரு " +"குறிப்பிட்ட காரணத்துடன் ஒரு கோப்பு அலறப்பட்டிருப்பதைக் குறிக்க. `` யங்க் செய்யப்பட்ட`` " +"விசையானது ஒரு உண்மை மதிப்பாக இருந்தால், அது ** ** ** `` url`` புலத்தால் " +"சுட்டிக்காட்டப்பட்ட கோப்பு \"அசைக்கப்பட்டுள்ளது\" என்பதைக் குறிக்கும் வகையில் விளக்கப்பட " +"வேண்டும்: ref: `api yank விவரக்குறிப்பு <எளிய-ச்பிரோபோசிட்டரி-அபி-யாங்க்>`." + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" +"`` ஆதாரம்``: ஒரு ** விருப்ப ** விசை, இது இருந்தால் ** ** ** ஒரு சாதொபொகு சரம் " +"அல்லது `` null``. `` Null`` இல்லையென்றால், அது ** ** கோப்பின் தொடர்புடைய ஆதாரத்திற்கு " +"ஒரு முகவரி ஆக இருக்க வேண்டும், இதில் `` தரவு-முன்னேற்றம்`` போன்ற விதிமுறைகள்: rew: " +"`அடிப்படை உஉகுமொ பநிஇ விவரக்குறிப்பு `." + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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 "" +"`` கோப்புகள்` `விசை ஒரு வரிசை, இதனால் ஒருவித வரிசையில் இருக்க வேண்டும், எதுவும் " +"இல்லை: ref:` அடிப்படை உஉகுமொ பநிஇ விவரக்குறிப்பு <எளிய-ரோபோசிட்டரி-API-BASE> " +"`அல்லது இந்த விவரக்குறிப்புக்கு ஏதேனும் குறிப்பிட்ட வரிசைப்படுத்தல் தேவைப்படுகிறது அல்லது " +"வரிசைப்படுத்துதல் ஒரு கோரிக்கையிலிருந்து அடுத்ததாக ஒத்துப்போகிறது. மனரீதியாக இது ஒரு " +"தொகுப்பாக சிறந்ததாக கருதப்படுகிறது, ஆனால் சாதொபொகு மற்றும் உஉகுமொ இரண்டுமே " +"தொகுப்புகளைக் கொண்டிருப்பதற்கான செயல்பாட்டைக் கொண்டிருக்கவில்லை." + +#: ../source/specifications/simple-repository-api.rst:679 +msgid "Content-Types" +msgstr "உள்ளடக்க வகைகள்" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" +"எளிய பநிஇ இன் அனைத்து பதில்களுக்கும் ஒரு நிலையான உள்ளடக்க வகை இருக்கும் என்று இந்த " +"விவரக்குறிப்பு முன்மொழிகிறது, இது பதில் என்ன என்பதை விவரிக்கும் (ஒரு எளிய பநிஇ " +"பதில்), இது பநிஇ இன் எந்த பதிப்பைக் குறிக்கிறது, மற்றும் சீரியலைசேசன் வடிவம் என்ன " +"பயன்படுத்தப்பட்டுள்ளது." + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "இந்த உள்ளடக்க வகையின் கட்டமைப்பு:" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" +"இந்த பநிஇ பதில்களில் ஒன்றைப் புரிந்துகொள்ள முயற்சிக்கும் வாடிக்கையாளர்களுக்கு பெரிய " +"பதிப்புகள் மட்டுமே சீர்குலைக்கப்பட வேண்டும் என்பதால், முக்கிய பதிப்பு மட்டுமே உள்ளடக்க " +"வகையில் சேர்க்கப்படும், மேலும் இது ஒரு பதிப்பு எண் என்பதை தெளிவுபடுத்துவதற்கு `` வி`` " +"உடன் முன்னொட்டு இருக்கும்." + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "இதன் பொருள் தற்போதுள்ள 1.0 பநிஇ க்கு, உள்ளடக்க வகைகள் இருக்கும்:" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "**JSON:** ``application/vnd.pypi.simple.v1+json``" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "** html: ** `` பயன்பாடு/vnd.pypi.simple.v1+html``" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" +"மேற்கூறியவற்றைத் தவிர, ஒரு சிறப்பு \"மேவு\" பதிப்பு `` சமீபத்திய`` என்று " +"பெயரிடப்பட்டது, இதன் நோக்கம் வாடிக்கையாளர்களுக்கு முழுமையான அண்மைக் கால பதிப்பைக் கோர " +"அனுமதிப்பதாகும், அந்த பதிப்பு என்ன என்பதை நேரத்திற்கு முன்பே தெரிந்து கொள்ளாமல். " +"எவ்வாறாயினும், வாடிக்கையாளர்கள் அவர்கள் எந்த பதிப்புகளை ஆதரிக்கிறார்கள் என்பது குறித்து " +"வெளிப்படையாக இருக்க பரிந்துரைக்கப்படுகிறது." + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" +"தற்போதுள்ள வாடிக்கையாளர்களை ஆதரிக்க: Ref: `அடிப்படை உஉகுமொ பநிஇ விவரக்குறிப்பு " +"` `உரை/HTML`` உள்ளடக்க வகையைப் பயன்படுத்த பநிஇ " +"பதில்கள், இந்த விவரக்குறிப்பு` `` உரை/html`` `` `` `` `conternt." + +#: ../source/specifications/simple-repository-api.rst:713 +msgid "Version + Format Selection" +msgstr "பதிப்பு + வடிவமைப்பு தேர்வு" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" +"இப்போது பல சாத்தியமான சீரியலைசேசன்கள் இருப்பதால், வாடிக்கையாளர்களுக்கு அவர்கள் புரிந்து " +"கொள்ளக்கூடிய சீரியலைசேசன் வடிவங்களைக் குறிக்க அனுமதிக்க எங்களுக்கு ஒரு வழிமுறை தேவை. " +"கூடுதலாக, முந்தைய பநிஇ பதிப்பை எதிர்பார்க்கும் வாடிக்கையாளர்களுக்கு இடையூறு " +"விளைவிக்காமல் பநிஇ க்கு சாத்தியமான புதிய முக்கிய பதிப்பைச் சேர்க்க முடிந்தால் அது நன்மை " +"பயக்கும்." + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" +"இதை இயக்க, இந்த விவரக்குறிப்பு HTTP இன் `சேவையகத்தால் இயக்கப்படும் உள்ளடக்க பேச்சுவார்த்தை " +" _ _." + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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 "" +"கிளையன்ட் ஒரு `` ஏற்றுக்கொள்` தலைப்பு கொண்ட ஒரு HTTP கோரிக்கையை அவர்கள் புரிந்து " +"கொள்ளக்கூடிய அனைத்து பதிப்பு+வடிவமைப்பு உள்ளடக்க வகைகளையும் பட்டியலிடுகிறது." + +#: ../source/specifications/simple-repository-api.rst:728 +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: */*``)." +msgstr "" +"சேவையகம் அந்த தலைப்பை ஆய்வு செய்கிறது, பட்டியலிடப்பட்ட உள்ளடக்க வகைகளில் ஒன்றைத் " +"தேர்ந்தெடுக்கிறது, பின்னர் அந்த உள்ளடக்க வகையைப் பயன்படுத்தி ஒரு பதிலை வழங்குகிறது (`` " +"ஏற்றுக்கொள்` தலைப்பு `` ஏற்றுக்கொள்: */ *``)." + +#: ../source/specifications/simple-repository-api.rst:731 +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 "" +"`` ஏற்றுக்கொள்` தலைப்பில் உள்ள எந்த உள்ளடக்க வகைகளையும் சேவையகம் ஆதரிக்கவில்லை என்றால், " +"அவர்கள் எவ்வாறு பதிலளிக்க வேண்டும் என்பதற்கான 3 வெவ்வேறு விருப்பங்களுக்கு இடையில் அவர்கள் " +"தேர்வு செய்ய முடியும்:" + +#: ../source/specifications/simple-repository-api.rst:735 +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:737 +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." +msgstr "" +"கோரப்பட்ட உள்ளடக்க வகைகள் எதுவும் கிடைக்கவில்லை என்பதைக் குறிக்க ஒரு HTTP `` 406 " +"ஏற்றுக்கொள்ள முடியாதது `` பதிலைத் தரவும், மேலும் பதிலளிக்க இயல்புநிலை உள்ளடக்க வகையைத் " +"தேர்ந்தெடுக்க சேவையகம் முடியவில்லை அல்லது விரும்பவில்லை." + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"Return a HTTP ``300 Multiple Choices`` response that contains a list of all " +"of the possible responses that could have been chosen." +msgstr "" +"ஒரு HTTP `` 300 பல தேர்வுகள்` `பதிலைத் தரவும், இது தேர்ந்தெடுக்கப்பட்ட சாத்தியமான " +"அனைத்து பதில்களின் பட்டியலையும் கொண்டுள்ளது." + +#: ../source/specifications/simple-repository-api.rst:742 +msgid "" +"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:745 +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." +msgstr "" +"உள்ளடக்க வகையை திரும்பப் பெற முடியாத ஒரு உள்ளடக்க வகையை கையாள்வதில் சேவையகம் எந்தத் " +"தேர்வுகளைச் செய்கிறது என்பதை இந்த விவரக்குறிப்பு குறிப்பிடவில்லை, மேலும் வாடிக்கையாளர்கள் " +"** சாத்தியமான எல்லா பதில்களையும் கையாளத் தயாராக இருக்க வேண்டும், அந்த கிளையண்டிற்கு எந்த " +"வகையிலும் மிகவும் அர்த்தமுள்ளதாக இருக்கும்." + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" +"எவ்வாறாயினும், ஒரு `` 300 பல தேர்வுகள்` `பதிலை எவ்வாறு விளக்க முடியும் என்பதற்கான " +"நிலையான வடிவம் இல்லாததால், அந்த விருப்பத்தைப் பயன்படுத்துவதில் இருந்து சேவையகங்களை இந்த " +"விவரக்குறிப்புகள் மிகவும் ஊக்கப்படுத்துகின்றன, ஏனெனில் வாடிக்கையாளர்களுக்கு கோரிக்கைக்கு " +"வேறு உள்ளடக்க வகையைப் புரிந்துகொள்வதற்கும் தேர்ந்தெடுப்பதற்கும் வழி இருக்காது. கூடுதலாக, " +"வாடிக்கையாளர் * எப்படியிருந்தாலும் வேறு உள்ளடக்க வகையைப் புரிந்து கொள்ள முடியும் என்பது " +"சாத்தியமில்லை, எனவே சிறந்த முறையில் இந்த பதில் `` 406 ஏற்றுக்கொள்ள முடியாத `` பிழை " +"போலவே கருதப்படும்." + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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 "" +"இந்த ச்பெக் ** ** மேவு பதிப்பு `` சமீபத்திய`` பயன்படுத்தப்பட்டால், சேவையகம் ** பதிலில் " +"உள்ள உண்மையான பதிப்பிற்கான உள்ளடக்க வகையுடன் ** பதிலளிக்க வேண்டும் (அதாவது ஒரு `` " +"ஏற்றுக்கொள்ளுங்கள்: பயன்பாடு/vnd.pypi.simple.latest+json` `` `` `` `` `` `` `` ` " +"`` பயன்பாடு/vnd.pypi.simple.v1+json```)." + +#: ../source/specifications/simple-repository-api.rst:764 +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:768 +msgid "``$type/$subtype``" +msgstr "`` $ type/$ subtype``" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "`` $ type/*``" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "``*/*``" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" +"ஒரு பதிப்பு+வடிவமைப்பைத் தேர்ந்தெடுப்பதைப் பயன்படுத்துவதற்கு, இவற்றில் மிகவும் பயனுள்ளதாக " +"இருக்கும் `` $ வகை/$ துணை வகை``, ஏனெனில் நீங்கள் விரும்பும் பதிப்பு மற்றும் வடிவமைப்பைக் " +"குறிப்பிடுவதற்கான ஒரே வழி இதுதான்." + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" +"ஒரு கிளையன்ட் ஒரு குறிப்பிட்ட நுழைவுக்கான முன்னுரிமையை அவர்களின் `` ஏற்றுக்கொள்` " +"`தலைப்பில் குறிப்பிட அனுமதிக்கிறது,` `; q =` `தொடர்ந்து` `0`` மற்றும்` 1`` உள்ளடக்கிய, " +"3 தசம இலக்கங்களுடன். இந்த மதிப்பை விளக்கும் போது, உயர் தரத்துடன் கூடிய நுழைவுக்கு " +"குறைந்த தரத்துடன் நுழைவதை விட முன்னுரிமை உள்ளது, மேலும் தகுதி இல்லாத எந்தவொரு " +"நுழைவும் `` 1`` தரத்திற்கு இயல்புநிலையாக இருக்கும்." + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" +"எவ்வாறாயினும், ஒரு சேவையகம் அவர்கள் கேட்டுக் கொண்ட உள்ளடக்க வகைகளில் ** ** ஐக் கோரப்பட்ட " +"முன்னுரிமையைப் பொருட்படுத்தாமல் தேர்ந்தெடுக்க இலவசம் என்பதை நினைவில் கொள்ள வேண்டும், மேலும் " +"அவர்கள் செய்த உள்ளடக்க வகையை கூட ** ** கேட்கவில்லை." + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" +"பநிஇ கோரிக்கையிலிருந்து அவர்கள் பெற்ற பதிலின் உள்ளடக்க வகையை தீர்மானிக்க " +"வாடிக்கையாளர்களுக்கு உதவ, இந்த விவரக்குறிப்புகள் எப்போதும் பதிலின் உள்ளடக்க வகையைக் " +"குறிக்கும் `` உள்ளடக்க-வகை`` தலைப்பு ஆகியவற்றை எப்போதும் சேர்க்க வேண்டும். இது தொழில்நுட்ப " +"ரீதியாக பின்னோக்கி பொருந்தாத மாற்றமாகும், இருப்பினும் நடைமுறையில் `பிஐபி இந்த தேவையை " +"அமல்படுத்துகிறது _" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" +"ஒரு வாடிக்கையாளர் எவ்வாறு செயல்பட முடியும் என்பதற்கான எடுத்துக்காட்டு போல் இருக்கும்:" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" +"ஒரு வாடிக்கையாளர் உஉகுமொ ஐ மட்டுமே ஆதரிக்க விரும்பினால் அல்லது சாதொபொகு ஐ மட்டுமே " +"ஆதரிக்க விரும்பினால், அவர்கள் விரும்பாத உள்ளடக்க வகைகளை `` ஏற்றுக்கொள்` தலைப்பிலிருந்து " +"அகற்றி, அவற்றைப் பெறுவதை பிழையாக மாற்றிவிடுவார்கள்." + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "மாற்று பேச்சுவார்த்தை வழிமுறைகள்" + +#: ../source/specifications/simple-repository-api.rst:859 +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 "" +"HTTP இன் உள்ளடக்க பேச்சுவார்த்தையைப் பயன்படுத்துவது ஒரு கிளையன்ட் மற்றும் சேவையகத்திற்கான " +"ஒருங்கிணைப்புக்கான நிலையான வழியாக கருதப்படுகிறது, வாடிக்கையாளர் புரிந்து கொள்ளக்கூடிய " +"ஒரு HTTP பதிலைப் பெறுகிறார் என்பதை உறுதிப்படுத்த, அந்த வழிமுறை போதுமானதாக இல்லாத " +"சூழ்நிலைகள் உள்ளன. அந்த நிகழ்வுகளுக்கு இந்த விவரக்குறிப்பில் மாற்று பேச்சுவார்த்தை " +"வழிமுறைகள் உள்ளன, அவை அதற்கு பதிலாக * விருப்பமாக * பயன்படுத்தப்படலாம்." + +#: ../source/specifications/simple-repository-api.rst:867 +msgid "URL Parameter" +msgstr "முகவரி அளவுரு" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" +"எளிய பநிஇ ஐ செயல்படுத்தும் சேவையகங்கள் முகவரி இன் குறிப்பிட்ட பதிப்பைக் கோர " +"வாடிக்கையாளர்களை அனுமதிக்க `` வடிவமைப்பு`` என்ற முகவரி அளவுருவை ஆதரிக்க தேர்வு " +"செய்யலாம்." + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" +"`` வடிவமைப்பு`` அளவுருவின் மதிப்பு சரியான உள்ளடக்க வகைகளில் ** ஒன்று ** ஆக இருக்க " +"வேண்டும். பல உள்ளடக்க வகைகள், காடு கார்டுகள், தர மதிப்புகள் போன்றவற்றை கடந்து செல்வது ... " +"** அல்ல ** ஆதரிக்கப்படவில்லை." + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" +"இந்த அளவுருவை ஆதரிப்பது விருப்பமானது, மேலும் வாடிக்கையாளர்கள் ** பநிஇ உடன் " +"தொடர்புகொள்வதற்கு ** இதை நம்பக்கூடாது. இந்த பேச்சுவார்த்தை பொறிமுறையானது உலாவிக்குள் " +"ஏபிஐக்கு எளிதாக மனித அடிப்படையிலான ஆய்வை அனுமதிப்பதற்காக அல்லது ஆவணங்கள் அல்லது " +"குறிப்புகளை ஒரு குறிப்பிட்ட பதிப்பு+வடிவமைப்போடு இணைக்க அனுமதிப்பதற்காக நோக்கமாக " +"உள்ளது." + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" +"இந்த அளவுருவை ஆதரிக்காத சேவையகங்கள் பிழையைக் கொண்டிருக்கும்போது அதைத் திருப்பித் தரத் " +"தேர்வுசெய்யலாம் அல்லது அவை எளிமையாக அதன் இருப்பை புறக்கணிக்கக்கூடும்." + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" +"ஒரு சேவையகம் இந்த அளவுருவை செயல்படுத்தும்போது, அது ** கிளையண்டின் `` ஏற்றுக்கொள்` " +"தலைப்பில் உள்ள எந்தவொரு மதிப்புகளையும் விட ** முன்னுரிமை பெற வேண்டும், மேலும் சேவையகம் " +"கோரப்பட்ட வடிவமைப்பை ஆதரிக்கவில்லை என்றால், அது `` ஏற்றுக்கொள்` தலைப்பு `` `ஏற்றுக்கொள்ளும் " +"எந்தவொரு பிழையும் தேர்வு செய்யத் தேர்வுசெய்யலாம், அல்லது நிலையான சேவையக பேச்சுவார்த்தை " +"பொதுவாகக் கிடைக்காது,` 406, திரும்புவதற்கான இயல்புநிலை வகை)." + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "இறுதிப்புள்ளி உள்ளமைவு" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" +"இந்த விருப்பம் தொழில்நுட்ப ரீதியாக ஒரு சிறப்பு விருப்பமல்ல, இது உள்ளடக்க " +"பேச்சுவார்த்தைகளைப் பயன்படுத்துவதன் இயல்பான விளைவு மற்றும் கிடைக்கக்கூடிய உள்ளடக்க வகைகளில் " +"எது அவற்றின் இயல்புநிலை என்பதைத் தேர்ந்தெடுக்க சேவையகங்களை அனுமதிக்கிறது." + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" +"ஒரு சேவையகம் விருப்பமில்லாமல் அல்லது சேவையகத்தால் இயக்கப்படும் உள்ளடக்க பேச்சுவார்த்தையை " +"செயல்படுத்த முடியாவிட்டால், அதற்கு பதிலாக பயனர்கள் தங்கள் வாடிக்கையாளரை அவர்கள் விரும்பும் " +"பதிப்பைத் தேர்ந்தெடுக்க வெளிப்படையாக கட்டமைக்க வேண்டும் என்றால், அது ஒரு உதவி உள்ளமைவு." + +#: ../source/specifications/simple-repository-api.rst:903 +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 "" +"இதை இயக்க, ஒரு சேவையகம் பல இறுதிப் புள்ளிகளை உருவாக்க வேண்டும் (உதாரணமாக, ``/எளிய/" +"v1+html/`` மற்றும்/அல்லது `/simple/v1+json/` `) அவர்கள் ஆதரிக்க விரும்பும் ஒவ்வொரு " +"பதிப்பிற்கும். அந்த இறுதிப்புள்ளியின் கீழ், உள்ளடக்க வகைகளின் ஒன்றை (அல்லது துணைக்குழு) " +"மட்டுமே ஆதரிக்கும் தங்கள் களஞ்சியத்தின் நகலை அவர்கள் வழங்க முடியும். `` ஏற்றுக்கொள்` " +"தலைப்பைப் பயன்படுத்தி ஒரு கிளையன்ட் கோரிக்கையைச் செய்யும்போது, சேவையகம் அதைப் " +"புறக்கணித்து, அந்த இறுதிப் புள்ளியுடன் ஒத்த உள்ளடக்க வகையை திருப்பித் தரலாம்." + +#: ../source/specifications/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" +"இந்த பிரிவு நெறிமுறையற்றது, மேலும் இந்த விவரக்குறிப்பை செயல்படுத்துவதற்கான சிறந்த " +"இயல்புநிலை செயல்படுத்தல் முடிவுகள் என்று ச்பெக் ஆசிரியர்கள் நம்புவதைக் குறிக்கிறது, ஆனால் " +"இந்த முடிவுகளுடன் பொருந்தக்கூடிய எந்தவொரு தேவையையும் இது குறிக்கிறது." + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" +"இந்த முடிவுகள் ஒரு ஏபிஐயின் புதிய பதிப்பிற்கு நகர்த்தக்கூடிய கோரிக்கைகளின் எண்ணிக்கையை " +"அதிகரிக்க தேர்வு செய்யப்பட்டுள்ளன, அதே நேரத்தில் மிகப் பெரிய அளவிலான பொருந்தக்கூடிய " +"தன்மையைப் பராமரிக்கின்றன. கூடுதலாக, அவர்கள் பநிஇ வழங்கும் காவலாளிகளைப் பயன்படுத்தி செய்ய " +"முயற்சித்தனர், இது வாடிக்கையாளர்களை தன்னால் முடிந்த சிறந்த தேர்வுகளைச் செய்ய " +"முயற்சிக்கிறது." + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "சேவையகங்கள் பரிந்துரைக்கப்படுகிறது:" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" +"இந்த விவரக்குறிப்பில் விவரிக்கப்பட்டுள்ள அனைத்து 3 உள்ளடக்க வகைகளையும் ஆதரிக்கவும், " +"சேவையகத்தால் இயக்கப்படும் உள்ளடக்க பேச்சுவார்த்தையைப் பயன்படுத்தி, அவை நியாயமான முறையில் " +"முடிந்தவரை, அல்லது குறைந்தபட்சம் உஉகுமொ பதில்களைப் பயன்படுத்தும் கீழான போக்குவரத்தை அவர்கள் " +"பெறும் வரை." + +#: ../source/specifications/simple-repository-api.rst:933 +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 "" +"ஒரு `` ஏற்றுக்கொள்` `தலைப்பை எதிர்கொள்ளும்போது, அது எவ்வாறு செயல்பட வேண்டும் என்று " +"தெரிந்த எந்த உள்ளடக்க வகைகளும் இல்லை, சேவையகம் ஒருபோதும்` `300 பல தேர்வு`` பதிலைத் " +"தரக்கூடாது, அதற்கு பதிலாக` `406 ஏற்றுக்கொள்ள முடியாதது`` பதிலைத் தரும்." + +#: ../source/specifications/simple-repository-api.rst:938 +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." +msgstr "" +"இருப்பினும், எண்ட்பாயிண்ட் உள்ளமைவைப் பயன்படுத்தத் தேர்வுசெய்தால், அந்த இறுதிப்புள்ளிக்கு " +"எதிர்பார்க்கப்படும் உள்ளடக்க வகையில் `` 200 சரி`` பதிலைத் தர வேண்டும்." + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" +"ஏற்றுக்கொள்ளக்கூடிய பதிப்பைத் தேர்ந்தெடுக்கும்போது, கிளையன்ட் ஆதரிக்கும் மிக உயர்ந்த பதிப்பை " +"சேவையகம் தேர்வு செய்ய வேண்டும், மிகவும் வெளிப்படையான/அம்சம் கொண்ட சீரியலைசேசன் " +"வடிவத்துடன், கிளையன்ட் கோரிக்கைகளின் தனித்துவத்தையும், அவர்கள் வெளிப்படுத்திய எந்தவொரு " +"தரமான முன்னுரிமை மதிப்புகளையும் கணக்கில் எடுத்துக்கொள்கிறது, மேலும் இது `` உரை/HTML`` " +"உள்ளடக்க வகையை கடைசி முயற்சியாக மட்டுமே பயன்படுத்த வேண்டும்." + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "வாடிக்கையாளர்கள் என்று பரிந்துரைக்கப்படுகிறது:" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" +"இந்த விவரக்குறிப்பில் விவரிக்கப்பட்டுள்ள அனைத்து 3 உள்ளடக்க வகைகளையும் ஆதரிக்கவும், " +"சேவையகத்தால் இயக்கப்படும் உள்ளடக்க பேச்சுவார்த்தையைப் பயன்படுத்தி, அவை நியாயமான முறையில் " +"முடிந்தவரை." + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" +"`` ஏற்றுக்கொள்` `தலைப்பைக் கட்டும் போது, நீங்கள் ஆதரிக்கும் அனைத்து உள்ளடக்க வகைகளையும் " +"சேர்க்கவும்." + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" +"இந்த பரிந்துரைக்கு ஒரு விதிவிலக்கு என்னவென்றால், நீங்கள் * `உரை/HTML`` உள்ளடக்க வகைக்கு " +"ஒரு` `; q = 0.01`` மதிப்பை நீங்கள் * சேர்க்க வேண்டும் என்று பரிந்துரைக்கப்படுகிறது, இது " +"நீங்கள் கோரும் ஒரே உள்ளடக்க வகையாக இல்லாவிட்டால்." + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" +"இயல்பான செயல்பாட்டின் போது `` சமீபத்திய`` மேவு பதிப்பைப் பயன்படுத்துவதை விட, அவர்கள் " +"தேடும் எந்த பதிப்புகளை வெளிப்படையாகத் தேர்ந்தெடுக்கவும்." + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" +"பதிலின் `` உள்ளடக்க-வகை`` ஐச் சரிபார்த்து, நீங்கள் எதிர்பார்த்த ஒன்றோடு பொருந்துகிறது " +"என்பதை உறுதிப்படுத்தவும்." + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "செப்டம்பர் 2015: உஉகுமொ வடிவமைப்பின் ஆரம்ப வடிவம், இல்: PEP: `503`" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "சூலை 2016: ஒரு புதுப்பிப்பில்-பைதான் மேனிலை தரவு தேவைப்படுகிறது: PEP: `503`" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "மே 2019: \"யாங்க்\" உதவி, இல்: பெப்: `592`" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" +"சூலை 2020: பநிஇ பதிப்பு மாநாடு மற்றும் மேனிலை தரவு, மற்றும் உஉகுமொ வடிவமைப்பை பநிஇ " +"V1 என அறிவித்தல், IN: PEP: `629`" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" +"மே 2021: ஒரு தொகுப்பிலிருந்து சுயாதீனமாக தொகுப்பு மெட்டாடேட்டாவை வழங்குதல், IN: PEP: " +"`658`" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" +"மே 2022: சாதொபொகு வடிவமைப்பின் ஆரம்ப வடிவம், வாடிக்கையாளர்களுக்கு இடையே தேர்வு " +"செய்வதற்கான ஒரு பொறிமுறையுடன், இரு வடிவங்களையும் பநிஇ V1 என அறிவித்தல், IN: PEP: " +"`691`" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" +"அக்டோபர் 2022: திட்ட பதிப்புகள் மற்றும் கோப்பு அளவு மற்றும் சாதொபொகு வடிவத்தில் பதிவேற்ற " +"நேரம், IN: PEP: `700`" + +#: ../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 "" +"சூன் 2023: ஒரு தொகுப்பிலிருந்து சுயாதீனமாக தொகுப்பு மெட்டாடேட்டாவை வழங்கும் புலத்தை " +"மறுபெயரிடுதல், IN: PEP: `714`" + +#: ../source/specifications/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" +"நவம்பர் 2024: உஉகுமொ மற்றும் சாதொபொகு வடிவங்களில் ஆதார மேனிலை தரவு, IN: PEP: `740`" + +#: ../source/specifications/simple-repository-api.rst:990 +#, fuzzy +#| msgid "" +#| "November 2024: provenance metadata in the HTML and JSON formats, " +#| "in :pep:`740`" +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" +"நவம்பர் 2024: உஉகுமொ மற்றும் சாதொபொகு வடிவங்களில் ஆதார மேனிலை தரவு, IN: PEP: `740`" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "மூல விநியோக வடிவம்" + +#: ../source/specifications/source-distribution-format.rst:8 +#, fuzzy +#| 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." +msgid "" +"The current standard 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 "" +"மூல விநியோக வடிவமைப்பின் தற்போதைய நிலையான வடிவம் A: FILE: `pyproject.toml` " +"கோப்பில் விநியோக காப்பகத்தில் அடையாளம் காணப்படுகிறது. அத்தகைய விநியோகத்தின் தளவமைப்பு " +"முதலில் குறிப்பிடப்பட்டுள்ளது: PEP: `517` மற்றும் முறையாக இங்கே ஆவணப்படுத்தப்பட்டுள்ளது." + +#: ../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 "" +"மரபு மூல விநியோக வடிவமைப்பும் உள்ளது, இது நிலையான நூலகத்தில் `` தொலைதூரங்கள்` " +"`தொகுதியின் நடத்தை மூலம் மறைமுகமாக வரையறுக்கப்படுகிறது, செயல்படுத்தும் போது: கட்டளை:` " +"setup.py sdist`. மேனிலை தரவு பதிப்பு 2.2 அல்லது அதற்குப் பிறகு ஒரு மரபு மூல " +"விநியோகத்தில் `` பி.கே.சி-இன்ஃபோ`` கோப்பைக் கொண்டிருந்தால், இந்த ஆவணம் இந்த வடிவமைப்பை " +"தரப்படுத்த முயற்சிக்கவில்லை, பின்னர் அது மேனிலை தரவு விவரக்குறிப்பில் வரையறுக்கப்பட்ட மூல " +"விநியோகங்களுக்கு பொருந்தக்கூடிய விதிகளைப் பின்பற்ற வேண்டும்." + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "மூல விநியோகங்கள் சுருக்கமாக * sdists * என்றும் அழைக்கப்படுகின்றன." + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "மூல மரங்கள்" + +#: ../source/specifications/source-distribution-format.rst:28 +#, fuzzy +#| 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." +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 used 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 "" +"A * மூல மரம் * என்பது கோப்புகள் மற்றும் கோப்பகங்களின் தொகுப்பாகும் - பதிப்பு கட்டுப்பாட்டு " +"அமைப்பு புதுப்பிப்பு போன்றவை - இதில் ஒரு: கோப்பு: `pyproject.toml` கோப்பு உள்ளது, " +"அவை கொண்ட கோப்புகள் மற்றும் கோப்பகங்களிலிருந்து மூல விநியோகத்தை உருவாக்க பயன்படுத்தலாம். ." + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "மூல விநியோக கோப்பு பெயர்" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" +"ஒரு SDIST இன் கோப்பு பெயர் தரப்படுத்தப்பட்டது: PEP: `625`. கோப்பு பெயர் `{name}-" +"{version} .tar.gz`` வடிவத்தில் இருக்க வேண்டும், அங்கு` `{name}` `பைனரி " +"விநியோகங்களுக்கு அதே விதிகளின்படி இயல்பாக்கப்படுகிறது (பார்க்க: Ref:` பைனரி-" +"டிச்ட்ரிபியூசன்-வடிவ), மற்றும் `{பதிப்பு-எச்." + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" +"கோப்பு பெயரின் பெயர் மற்றும் பதிப்பு கூறுகள் கோப்பில் உள்ள மெட்டாடேட்டாவில் சேமிக்கப்பட்ட " +"மதிப்புகளுடன் பொருந்த வேண்டும்." + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" +"மூல விநியோக கோப்பை உருவாக்கும் குறியீடு கோப்பிற்கு இந்த விவரக்குறிப்புடன் பொருந்தக்கூடிய " +"பெயரைக் கொடுக்க வேண்டும். இதில் `` Build_Sdist`` கொக்கி ஒரு: கால: `பின்தளத்தில் " +"உருவாக்கு <பின்தளத்தில் உருவாக்கு>`." + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" +"மூல விநியோக கோப்புகளை செயலாக்கும் குறியீடு மூல விநியோக கோப்புகளை `` .tar.gz`` " +"பின்னொட்டு மற்றும் கோப்பு பெயரில் துல்லியமாக * ஒன்று * ஐபன் மூலம் அங்கீகரிக்கலாம். இதைச் " +"செய்யும் குறியீடு பின்னர் சரிபார்ப்பு இல்லாமல் கோப்பு பெயரில் இருந்து விநியோக பெயர் மற்றும் " +"பதிப்பைப் பயன்படுத்தலாம்." + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "மூல விநியோக கோப்பு வடிவம்" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`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``) என்ற ஒற்றை உயர்மட்ட கோப்பகத்தைக் கொண்டுள்ளது. பெயர் மற்றும் பதிப்பு கோப்பில் " +"சேமிக்கப்பட்ட மெட்டாடேட்டாவுடன் பொருந்த வேண்டும். இந்த கோப்பகத்தில் ஒரு: கோப்பு: " +"`pyproject.toml` இல் வரையறுக்கப்பட்ட வடிவத்தில் இருக்க வேண்டும்: குறிப்பு: ref:` " +"pyproject-toml-spec`, மற்றும் a: கோப்பு: `pkg-info` கோப்பு:` கோர்-மெட்டாடாட்டா` " +"குறிப்பு. மேனிலை தரவு விவரக்குறிப்பின் குறைந்தபட்சம் பதிப்பு 2.2 க்கு மேனிலை தரவு " +"இணங்க வேண்டும்." + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" +"மேனிலை தரவு பதிப்பு 2.4 அல்லது அதற்கு மேற்பட்டதாக இருந்தால், மூல விநியோகத்தில் `` " +"உரிம-கோப்பு` `புலத்தால் குறிப்பிடப்பட்ட எந்த உரிமக் கோப்புகளும் இருக்க வேண்டும்: கோப்பு:` " +"பி.கே." + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" +"ஒரு SDIST இன் வேறு எந்த உள்ளடக்கமும் தேவையில்லை அல்லது வரையறுக்கப்படவில்லை. திட்டத்தை " +"உருவாக்க SDIST இல் தங்களுக்குத் தேவையான எந்த தகவலையும் உருவாக்க முடியும்." + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" +"நாடாகாப்பகபந்து நவீன POSIX.1-2001 PAX கரிக்கீல் வடிவமைப்பைப் பயன்படுத்த வேண்டும், இது " +"UTF-8 அடிப்படையிலான கோப்பு பெயர்களைக் குறிப்பிடுகிறது. குறிப்பாக, 'R: GZ' திறந்த " +"கொடியுடன் நிலையான நூலக டார்ஃபைல் தொகுதியைப் பயன்படுத்தி மூல விநியோக கோப்புகள் " +"படிக்கக்கூடியதாக இருக்க வேண்டும்." + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "மூல விநியோக காப்பக நற்பொருத்தங்கள்" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" +"தார் கோப்புகளை பிரித்தெடுப்பது ஆபத்தானது, மற்றும் முடிவுகள் இயங்குதள-குறிப்பிட்டவை " +"என்பதால், மூல விநியோகங்களின் காப்பக நற்பொருத்தங்கள் குறைவாகவே உள்ளன." + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "தரவு வடிப்பானுடன் திறக்க" + +#: ../source/specifications/source-distribution-format.rst:93 +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` (எ.கா." + +#: ../source/specifications/source-distribution-format.rst:97 +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`), பொதுவாக அந்த வடிப்பானைப் " +"பயன்படுத்தும் கருவிகள் (நேரடியாக மறைமுகமாக) பயனரை எச்சரிக்கலாம் மற்றும் இந்த குறிப்பை " +"புறக்கணிக்கலாம். பயன்பாட்டினுக்கு இடையிலான வணிகம் (எ.கா. காப்பகத்தை முழுமையாக நம்புதல்) " +"மற்றும் பாதுகாப்பு (எ.கா. திறக்க மறுப்பது) இந்த விசயத்தில் கருவி வரை விடப்படுகிறது." + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "தரவு வடிகட்டி இல்லாமல் திறக்க" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" +"`` தரவு`` வடிகட்டியை நேரடியாகப் பயன்படுத்தாத கருவிகள் (எ.கா. பின்னோக்கி " +"பொருந்தக்கூடிய தன்மைக்கு, கூடுதல் அம்சங்களை அனுமதிப்பது அல்லது பைத்தானைப் பயன்படுத்தாதது) " +"இந்த பகுதியைப் பின்பற்ற வேண்டும். (இந்த எழுத்தின் போது, `` தரவு`` வடிகட்டியும் இந்த " +"பகுதியைப் பின்பற்றுகிறது, ஆனால் அது எதிர்காலத்தில் ஒத்திசைவிலிருந்து வெளியேறக்கூடும்.)" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" +"பின்வரும் கோப்புகள் * SDIST * காப்பகத்தில் செல்லாது. அத்தகைய உள்ளீட்டை எதிர்கொண்டவுடன், " +"கருவிகள் பயனருக்கு அறிவிக்க வேண்டும், உள்ளீட்டைத் திறக்கக்கூடாது, தோல்வியுடன் " +"நிறுத்தப்படலாம்:" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "இலக்கு கோப்பகத்திற்கு வெளியே வைக்கப்படும் கோப்புகள்." + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" +"இலக்கு கோப்பகத்திற்கு வெளியே சுட்டிக்காட்டும் இணைப்புகள் (குறியீட்டு அல்லது கடினமான)." + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "சாதன கோப்புகள் (குழாய்கள் உட்பட)." + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" +"பின்வருவனையும் தவறானது. கருவிகள் மேலே கருதப்படலாம், ஆனால் அவ்வாறு செய்ய தேவையில்லை:" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "கோப்பு பெயர் அல்லது இணைப்பு இலக்கில் `` ..` கூறு கொண்ட கோப்புகள்." + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "காப்பகத்தின் பகுதியாக இல்லாத ஒரு கோப்பை சுட்டிக்காட்டும் இணைப்புகள்." + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" +"காப்பகத்திலிருந்து உள்ளடக்கத்தைப் பயன்படுத்தி, கருவிகள் வழக்கமான கோப்புகளாக இணைப்புகளை " +"(குறியீட்டு அல்லது கடினமாக்கலாம்) திறக்கலாம்." + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "* Sdist * காப்பகங்களை பிரித்தெடுக்கும் போது:" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" +"கோப்பு பெயர்களில் முன்னணி ச்லாச்கள் கைவிடப்பட வேண்டும். (இது இப்போதெல்லாம் `` tar`` " +"திறக்கப்படுவதற்கான நிலையான நடத்தை.)" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "ஒவ்வொரு `` பயன்முறை`` (யூனிக்ச் அனுமதி) பிட்டிற்கும், கருவிகளும் இருக்க வேண்டும்:" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "புதிய கோப்பு/கோப்பகத்திற்கு (முறையே) தளத்தின் இயல்புநிலையைப் பயன்படுத்தவும்," + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "காப்பகத்தின் படி பிட் அமைக்கவும், அல்லது" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"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/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "உயர் `` பயன்முறை` `பிட்கள் (Setuid, setgid, ஒட்டும்) அழிக்கப்பட வேண்டும்." + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "பயனரை * இயங்கக்கூடிய * பிட் பாதுகாக்க பரிந்துரைக்கப்படுகிறது." + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "மேலும் குறிப்புகள்" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" +"`` டார்ஃபைல்`` ஆவணத்தில் மேலும் சரிபார்ப்புக்கான * குறிப்புகள் அவற்றின் கருவிக்கு எவ்வாறு " +"பொருந்தும் என்பதைக் கருத்தில் கொள்ள கருவி ஆசிரியர்கள் ஊக்குவிக்கப்படுகிறார்கள்." + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" +"நவம்பர் 2020: இந்த விவரக்குறிப்பின் அசல் பதிப்பு மூலம் அங்கீகரிக்கப்பட்டது: PEP: `643`." + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "சூலை 2021: ஒரு மூல மரம் என்றால் என்ன என்பதை வரையறுத்தது." + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "செப்டம்பர் 2022: மூல விநியோகத்தின் கோப்பு பெயர் தரப்படுத்தப்பட்டது: PEP: `625`." + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "ஆகச்ட் 2023: மூல விநியோக காப்பக நற்பொருத்தங்கள் தரப்படுத்தப்பட்டன: PEP: `721`." + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" +"டிசம்பர் 2024: மூல விநியோகத்தில் உரிமக் கோப்புகளைச் சேர்ப்பது தரப்படுத்தப்பட்டது: PEP: " +"`639`." + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "பதிப்பு விவரக்குறிப்புகள்" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" +"இந்த விவரக்குறிப்பு பைதான் மென்பொருள் விநியோகங்களின் பதிப்புகளை அடையாளம் காண்பதற்கான " +"திட்டத்தை விவரிக்கிறது, மேலும் குறிப்பிட்ட பதிப்புகளில் சார்புகளை அறிவிக்கிறது." + +#: ../source/specifications/version-specifiers.rst:15 +msgid "Definitions" +msgstr "வரையறைகள்" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +msgstr "" +"\"கட்டாயம்\", \"செய்யக்கூடாது\", \"தேவை\", \"வேண்டும்\", \"வேண்டும்\", \",\", \",\", " +"\",\", \"பரிந்துரைக்கப்படக்கூடாது\", \"மே\" மற்றும் \"விருப்பமானது\" ஆகியவை " +"விவரிக்கப்பட்டுள்ளபடி விளக்கப்பட வேண்டும்: RFC: `2119`." + +#: ../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." +msgstr "" +"\"பில்ட் கருவிகள்\" என்பது மேம்பாட்டு அமைப்புகளில் இயங்குவதை நோக்கமாகக் கொண்ட தானியங்கி " +"கருவிகள், மூல மற்றும் பைனரி விநியோக காப்பகங்களை உருவாக்குகிறது. பைனரி காப்பகங்களை " +"முன்பே கட்டியெழுப்புவதை விட SDIST களாக விநியோகிக்கப்பட்ட மென்பொருளை உருவாக்குவதற்கு " +"ஒருங்கிணைப்பு கருவிகளால் உருவாக்க கருவிகள் பயன்படுத்தப்படலாம்." + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" +"\"இன்டெக்ச் சேவையகங்கள்\" என்பது செயலில் விநியோக பதிவுகள் ஆகும், அவை பதிப்பு மற்றும் " +"சார்பு மெட்டாடேட்டாவை வெளியிடுகின்றன மற்றும் அனுமதிக்கப்பட்ட மெட்டாடேட்டாவில் இடக் " +"கட்டுப்பாடுகளை வெளியிடுகின்றன." + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" +"\"வெளியீட்டு கருவிகள்\" என்பது மேம்பாட்டு அமைப்புகளில் இயங்குவதற்கும், மூல மற்றும் பைனரி " +"விநியோக காப்பகங்களை குறியீட்டு சேவையகங்களுக்கு பதிவேற்றுவதற்கும் நோக்கம் கொண்ட தானியங்கி " +"கருவிகள்." + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" +"\"நிறுவல் கருவிகள்\" என்பது ஒருங்கிணைப்பு கருவிகள் குறிப்பாக வரிசைப்படுத்தல் இலக்குகள், " +"நுகர்வு மூல மற்றும் பைனரி விநியோக காப்பகங்களை ஒரு குறியீட்டு சேவையகம் அல்லது பிற " +"நியமிக்கப்பட்ட இடத்திலிருந்து இயக்கவும், அவற்றை இலக்கு அமைப்புக்கு அனுப்பவும் நோக்கம் " +"கொண்டவை." + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" +"\"தானியங்கி கருவிகள்\" என்பது உருவாக்கும் கருவிகள், குறியீட்டு சேவையகங்கள், வெளியீட்டு " +"கருவிகள், ஒருங்கிணைப்பு கருவிகள் மற்றும் விநியோக பதிப்பு மற்றும் சார்பு மெட்டாடேட்டாவை " +"உருவாக்கும் அல்லது நுகரும் வேறு எந்த மென்பொருளையும் உள்ளடக்கியது." + +#: ../source/specifications/version-specifiers.rst:43 +msgid "Version scheme" +msgstr "பதிப்பு திட்டம்" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" +"அனைத்து வரையறுக்கப்பட்ட பதிப்பு ஒப்பீட்டு செயல்பாடுகளையும் ஆதரிக்கும் பொது பதிப்பு " +"அடையாளங்காட்டியால் விநியோகங்கள் அடையாளம் காணப்படுகின்றன" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" +"ஒரு குறிப்பிட்ட விநியோக காப்பகத்தால் வழங்கப்பட்ட விநியோக பதிப்பை விவரிக்கவும், " +"மென்பொருளை உருவாக்க அல்லது இயக்குவதற்குத் தேவையான சார்புகளின் பதிப்பில் தடைகளை வைக்கவும் " +"பதிப்பு திட்டம் பயன்படுத்தப்படுகிறது." + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "பொது பதிப்பு அடையாளங்காட்டிகள்" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "நியமன பொது பதிப்பு அடையாளங்காட்டிகள் பின்வரும் திட்டத்திற்கு இணங்க வேண்டும் ::" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" +"பொது பதிப்பு அடையாளங்காட்டிகளில் முன்னணி அல்லது பின்தங்கிய இடைவெளியைக் " +"கொண்டிருக்கக்கூடாது." + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" +"கொடுக்கப்பட்ட விநியோகத்திற்குள் பொது பதிப்பு அடையாளங்காட்டிகள் தனித்துவமாக இருக்க வேண்டும்." + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" +"நிறுவல் கருவிகள் இந்த திட்டத்திற்கு இணங்காத எந்தவொரு பொது பதிப்புகளையும் புறக்கணிக்க " +"வேண்டும், ஆனால் கீழே குறிப்பிடப்பட்டுள்ள இயல்பாக்கங்களையும் சேர்க்க வேண்டும். இணக்கமற்ற அல்லது " +"தெளிவற்ற பதிப்புகள் கண்டறியப்படும்போது நிறுவல் கருவிகள் பயனரை எச்சரிக்கலாம்." + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" +"மேலும் காண்க: குறிப்பு: `பதிப்பு-விவரிப்பாளர்கள்-ரெசெக்ச்` இது நியமன வடிவத்துடன் " +"கடுமையான இணக்கத்தை சரிபார்க்க வழக்கமான வெளிப்பாட்டை வழங்குகிறது, அத்துடன் அடுத்தடுத்த " +"இயல்பாக்கம் தேவைப்படும் உள்ளீடுகளை ஏற்றுக்கொள்வது மிகவும் அனுமதிக்கப்பட்ட வழக்கமான " +"வெளிப்பாடு." + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "பொது பதிப்பு அடையாளங்காட்டிகள் ஐந்து பிரிவுகளாக பிரிக்கப்படுகின்றன:" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "சகாப்தம்: `` `" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "வெளியீட்டு பிரிவு: `` n (.n)*``" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "முன் வெளியீட்டு பிரிவு: `{a | b | rc} n``" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "வெளியீட்டுக்குப் பிந்தைய பிரிவு: `` .போச்ட்ன்``" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "மேம்பாட்டு வெளியீட்டு பிரிவு: `` .டெவ்ன்``" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" +"எந்தவொரு வெளியீட்டும் பின்வரும் பிரிவுகளில் வரையறுக்கப்பட்டுள்ளபடி \"இறுதி வெளியீடு\", " +"\"முன் வெளியீடு\", \"வெளியீட்டுக்கு பிந்தைய\" அல்லது \"மேம்பாட்டு வெளியீடு\" ஆகும்." + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" +"அனைத்து எண் கூறுகளும் ASCII இலக்கங்களின் வரிசைகளாக குறிப்பிடப்படும் எதிர்மறை அல்லாத " +"முழு எண்களாக இருக்க வேண்டும்." + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" +"அனைத்து எண் கூறுகளும் அவற்றின் எண் மதிப்புக்கு ஏற்ப விளக்கப்பட்டு ஆர்டர் செய்யப்பட வேண்டும், " +"உரை சரங்களாக அல்ல." + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" +"அனைத்து எண் கூறுகளும் பூச்சியமாக இருக்கலாம். வெளியீட்டுப் பிரிவுக்கு கீழே " +"விவரிக்கப்பட்டுள்ளதைத் தவிர, பூச்சியத்தின் ஒரு எண் கூறுக்கு பதிப்பு வரிசைப்படுத்தலில் " +"எப்போதும் மிகக் குறைந்த மதிப்பாக இருப்பதைத் தவிர்த்து சிறப்பு முக்கியத்துவம் இல்லை." + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" +"தற்போதுள்ள பொது மற்றும் தனியார் பைதான் திட்டங்களில் பரந்த அளவிலான பதிப்பு நடைமுறைகளுக்கு " +"ஏற்றவாறு இந்த திட்டத்தால் பதிப்பு அடையாளங்காட்டிகளைப் படிக்க சில கடினமாக உள்ளது." + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" +"அதன்படி, விவரக்குறிப்பால் தொழில்நுட்ப ரீதியாக அனுமதிக்கப்பட்ட சில பதிப்பு நடைமுறைகள் " +"புதிய திட்டங்களுக்கு கடுமையாக ஊக்கமளிக்கின்றன. இது எங்கே, தொடர்புடைய விவரங்கள் பின்வரும் " +"பிரிவுகளில் குறிப்பிடப்பட்டுள்ளன." + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "உள்ளக பதிப்பு அடையாளங்காட்டிகள் பின்வரும் திட்டத்திற்கு இணங்க வேண்டும் ::" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" +"அவை ஒரு சாதாரண பொது பதிப்பு அடையாளங்காட்டியைக் கொண்டிருக்கின்றன (முந்தைய பிரிவில் " +"வரையறுக்கப்பட்டுள்ளபடி), தன்னிச்சையான \"உள்ளக பதிப்பு சிட்டை\" உடன், பொது பதிப்பு " +"அடையாளங்காட்டியிலிருந்து ஒரு பிளச் மூலம் பிரிக்கப்பட்டுள்ளன. உள்ளக பதிப்பு லேபிள்களுக்கு " +"குறிப்பிட்ட சொற்பொருள்கள் ஒதுக்கப்படவில்லை, ஆனால் சில தொடரியல் கட்டுப்பாடுகள் " +"விதிக்கப்படுகின்றன." + +#: ../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:132 +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." +msgstr "" +"உள்ளக பதிப்பு லேபிளைச் சேர்ப்பது, கீழ்நிலை ஒருங்கிணைப்பாளர்களால் மாற்றப்பட்ட " +"மறுகட்டமைப்புகளிலிருந்து மேலோடை வெளியீடுகளை வேறுபடுத்துவதை சாத்தியமாக்குகிறது. உள்ளக " +"பதிப்பு அடையாளங்காட்டியின் பயன்பாடு ஒரு வெளியீட்டைப் பாதிக்காது, ஆனால், மூல " +"விநியோகத்திற்குப் பயன்படுத்தப்படும்போது, அதனுடன் தொடர்புடைய மேலோடை வெளியீட்டின் சரியான " +"குறியீட்டைக் கொண்டிருக்கவில்லை என்பதைக் குறிக்கிறது." + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" +"உள்ளக பதிப்பு அடையாளங்காட்டிகளை கோப்பு பெயர்கள் மற்றும் முகவரி களின் ஒரு பகுதியாக " +"உடனடியாக இணைக்க முடியும் என்பதை உறுதிப்படுத்தவும், மற்றும் எக்சாடெசிமல் ஆச் " +"பிரதிநிதித்துவங்களில் முரண்பாடுகளை வடிவமைப்பதைத் தவிர்க்கவும், உள்ளக பதிப்பு லேபிள்கள் " +"பின்வரும் அனுமதிக்கப்பட்ட எழுத்துக்களின் தொகுப்பிற்கு மட்டுப்படுத்தப்பட வேண்டும்:" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "ASCII கடிதங்கள் (`` [a-za-z] ``)" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "ASCII இலக்கங்கள் (`` [0-9] ``)" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "காலங்கள் (`` .``)" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" +"உள்ளக பதிப்பு லேபிள்கள் ASCII கடிதம் அல்லது இலக்கத்துடன் தொடங்கி முடிவடைய வேண்டும்." + +#: ../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 "" +"உள்ளக பதிப்புகளின் ஒப்பீடு மற்றும் வரிசைப்படுத்தல் உள்ளக பதிப்பின் ஒவ்வொரு பகுதியையும் " +"(`` .``) தனித்தனியாகக் கருதுகிறது. ஒரு பிரிவு முழுவதுமாக ASCII இலக்கங்களைக் " +"கொண்டிருந்தால், அந்த பிரிவு ஒப்பீட்டு நோக்கங்களுக்காக ஒரு முழு எண்ணாக கருதப்பட வேண்டும், " +"மேலும் ஒரு பிரிவில் ஏதேனும் ASCII எழுத்துக்கள் இருந்தால், அந்த பிரிவு அகராதிக் முறையில் " +"வழக்கு உணர்வற்ற தன்மையுடன் ஒப்பிடப்படுகிறது. ஒரு எண் மற்றும் அகராதி பிரிவை ஒப்பிடும் " +"போது, எண் பிரிவு எப்போதும் லெக்சிகோகிராஃபிக் பிரிவை விட அதிகமாக ஒப்பிடுகிறது. " +"கூடுதலாக, ஏராளமான பிரிவுகளைக் கொண்ட உள்ளக பதிப்பு எப்போதும் உள்ளக பதிப்பை விட " +"குறைவான பிரிவுகளுடன் ஒப்பிடப்படும், குறுகிய உள்ளக பதிப்பின் பிரிவுகள் நீண்ட உள்ளக " +"பதிப்பின் பிரிவுகளின் தொடக்கத்துடன் சரியாக பொருந்தும் வரை." + +#: ../source/specifications/version-specifiers.rst:160 +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." +msgstr "" +"ஒரு \"மேலோடை திட்டம்\" என்பது அதன் சொந்த பொது பதிப்புகளை வரையறுக்கும் ஒரு திட்டமாகும். " +"ஒரு \"கீழ்நிலை திட்டம்\" என்பது ஒரு மேலோடை திட்டத்தை கண்காணித்து மறுபகிர்வு செய்யும் " +"ஒன்றாகும், இது மேலோடை திட்டத்தின் பிற்கால பதிப்புகளிலிருந்து பாதுகாப்பு மற்றும் பிழை " +"திருத்தங்களை பின்னுக்குத் தள்ளும்." + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" +"உள்ளக பதிப்பு அடையாளங்காட்டியைப் பயன்படுத்தும் மூல விநியோகங்கள் `` பைதான்.இண்டெக்ரேட்டர்` " +"`நீட்டிப்பு மெட்டாடேட்டாவை வழங்க வேண்டும் (வரையறுக்கப்பட்டுள்ளபடி: PEP:` 459`)." + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "இறுதி வெளியீடுகள்" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" +"ஒரு வெளியீட்டு பிரிவு மற்றும் விருப்பமாக ஒரு சகாப்த அடையாளங்காட்டியைக் கொண்ட ஒரு " +"பதிப்பு அடையாளங்காட்டி \"இறுதி வெளியீடு\" என்று அழைக்கப்படுகிறது." + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" +"வெளியீட்டு பிரிவு ஒன்று அல்லது அதற்கு மேற்பட்ட எதிர்மறை அல்லாத முழு எண் மதிப்புகளைக் " +"கொண்டுள்ளது, இது புள்ளிகளால் பிரிக்கப்படுகிறது ::" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" +"ஒரு திட்டத்திற்குள் இறுதி வெளியீடுகள் தொடர்ந்து அதிகரித்து வரும் பாணியில் எண்ணப்பட " +"வேண்டும், இல்லையெனில் தானியங்கி கருவிகள் அவற்றை சரியாக மேம்படுத்த முடியாது." + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" +"இந்த திட்டத்தின் கீழ் முதல் கூடுதல் கூறுகள் அனுமதிக்கப்பட்டாலும், மிகவும் பொதுவான வகைகள் " +"இரண்டு கூறுகளை (\"மேசர்.மினோர்\") அல்லது மூன்று கூறுகளை (\"மேசர்.மினோர்.மிக்ரோ\") " +"பயன்படுத்த வேண்டும்." + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "உதாரணமாக ::" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" +"வெளியீட்டுத் தொடர் என்பது பொதுவான முன்னொட்டுடன் தொடங்கும் இறுதி வெளியீட்டு எண்களின் " +"தொகுப்பாகும். எடுத்துக்காட்டாக, `` 3.3.1``, `` 3.3.5`` மற்றும் `` 3.3.9.45`` " +"அனைத்தும் `` 3.3`` வெளியீட்டுத் தொடரின் ஒரு பகுதியாகும்." + +#: ../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." +msgstr "" +"`` X.y`` மற்றும் `` x.y.0`` ஆகியவை தனித்துவமான வெளியீட்டு எண்களாகக் கருதப்படுவதில்லை, " +"ஏனெனில் வெளியீட்டு பிரிவு ஒப்பீட்டு விதிகள் மறைமுகமாக இரண்டு கூறு படிவத்தை `` x.y.0`` " +"என விரிவாக்குகின்றன." + +#: ../source/specifications/version-specifiers.rst:229 +#, fuzzy +#| msgid "" +#| "Date based release segments are also permitted. An example of a date " +#| "based release scheme using the year and month of the release::" +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:243 +msgid "Pre-releases" +msgstr "முன் வெளியீடுகள்" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" +"திட்டத்தின் மேம்பாட்டு சுழற்சியின் ஒரு பகுதியாகப் பயன்படுத்தப்பட்டால், இந்த முன் வெளியீடுகள் " +"பதிப்பு அடையாளங்காட்டியில் ஒரு முன் வெளியீட்டுப் பகுதியைச் சேர்ப்பதன் மூலம் " +"குறிக்கப்படுகின்றன ::" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" +"வெளியீட்டு பிரிவு மற்றும் வெளியீட்டுக்கு முந்தைய பிரிவு ஆகியவற்றைக் கொண்ட ஒரு பதிப்பு " +"அடையாளங்காட்டி \"வெளியீட்டுக்கு முந்தைய\" என்று அழைக்கப்படுகிறது." + +#: ../source/specifications/version-specifiers.rst:259 +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 "" +"வெளியீட்டுக்கு முந்தைய பிரிவு, வெளியீட்டுக்கு முந்தைய கட்டத்திற்கான அகரவரிசை " +"அடையாளங்காட்டியைக் கொண்டுள்ளது, மேலும் எதிர்மறை அல்லாத முழு எண் மதிப்புடன். கொடுக்கப்பட்ட " +"வெளியீட்டிற்கான முன் வெளியீடுகள் முதலில் கட்டம் (ஆல்பா, பீட்டா, வெளியீட்டு வேட்பாளர்) மற்றும் " +"பின்னர் அந்த கட்டத்திற்குள் எண் கூறு மூலம் ஆர்டர் செய்யப்படுகின்றன." + +#: ../source/specifications/version-specifiers.rst:264 +msgid "" +"Installation tools MAY accept both ``c`` and ``rc`` releases for a common " +"release segment in order to handle some existing legacy distributions." +msgstr "" +"தற்போதுள்ள சில மரபு விநியோகங்களைக் கையாள்வதற்காக பொதுவான வெளியீட்டு பிரிவுக்கான `` " +"சி`` மற்றும் `` rc`` வெளியீடுகளை நிறுவல் கருவிகள் ஏற்றுக்கொள்ளலாம்." + +#: ../source/specifications/version-specifiers.rst:267 +msgid "" +"Installation tools SHOULD interpret ``c`` versions as being equivalent to " +"``rc`` versions (that is, ``c1`` indicates the same version as ``rc1``)." +msgstr "" +"நிறுவல் கருவிகள் `` சி`` பதிப்புகள் `` rc`` பதிப்புகளுக்கு சமமானவை என்று விளக்க " +"வேண்டும் (அதாவது, `` சி 1`` அதே பதிப்பைக் குறிக்கிறது `` rc1``)." + +#: ../source/specifications/version-specifiers.rst:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" +"ஒரு பொதுவான வெளியீட்டு பிரிவுக்கு `` rc`` மற்றும் `C`` இரண்டையும் உருவாக்க கருவிகள், " +"வெளியீட்டு கருவிகள் மற்றும் குறியீட்டு சேவையகங்களை உருவாக்க அனுமதிக்க வேண்டும்." + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "பிந்தைய வெளியீடுகள்" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" +"சில திட்டங்கள் விநியோகிக்கப்பட்ட மென்பொருளை பாதிக்காத இறுதி வெளியீட்டில் சிறிய பிழைகளை " +"நிவர்த்தி செய்ய பிந்தைய வெளியீடுகளைப் பயன்படுத்துகின்றன (எடுத்துக்காட்டாக, வெளியீட்டுக் " +"குறிப்புகளில் பிழையை சரிசெய்தல்)." + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" +"ஒரு திட்டத்தின் மேம்பாட்டு சுழற்சியின் ஒரு பகுதியாகப் பயன்படுத்தப்பட்டால், இந்த பிந்தைய " +"வெளியீடுகள் பதிப்பு அடையாளங்காட்டியில் வெளியீட்டுக்குப் பிந்தைய பிரிவைச் சேர்ப்பதன் மூலம் " +"குறிக்கப்படுகின்றன ::" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" +"மேம்பாட்டு வெளியீட்டு பிரிவு இல்லாமல் வெளியீட்டுக்குப் பிந்தைய பிரிவை உள்ளடக்கிய பதிப்பு " +"அடையாளங்காட்டி \"வெளியீட்டுக்குப் பிந்தையது\" என்று அழைக்கப்படுகிறது." + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" +"வெளியீட்டுக்குப் பிந்தைய பிரிவு `` .போச்ட்`` என்ற சரம் கொண்டது, அதைத் தொடர்ந்து எதிர்மறை " +"அல்லாத முழு எண் மதிப்பு. பிந்தைய உறவுகள் அவற்றின் எண் கூறுகளால் கட்டளையிடப்படுகின்றன, " +"உடனடியாக தொடர்புடைய வெளியீட்டைத் தொடர்ந்து, அடுத்தடுத்த வெளியீட்டிற்கு முன்னதாக." + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "முன் வெளியீடுகளுக்கு பிந்தைய வெளியீடுகளும் அனுமதிக்கப்படுகின்றன ::" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" +"முன் வெளியீடுகளின் பிந்தைய உறவுகளை உருவாக்குவது வலுவாக ஊக்கமளிக்கிறது, ஏனெனில் இது " +"பதிப்பு அடையாளங்காட்டியை மனித வாசகர்களுக்கு அலசுவது கடினம். பொதுவாக, எண் கூறுகளை " +"அதிகரிப்பதன் மூலம் புதிய முன் வெளியீட்டை உருவாக்குவது கணிசமாக தெளிவாக உள்ளது." + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "வளர்ச்சி வெளியீடுகள்" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" +"சில திட்டங்கள் வழக்கமான மேம்பாட்டு வெளியீடுகளை உருவாக்குகின்றன, மேலும் கணினி பேக்கேசர்கள் " +"(குறிப்பாக லினக்ச் விநியோகங்களுக்கு) ஆரம்ப வெளியீடுகளை மூலக் கட்டுப்பாட்டிலிருந்து " +"நேரடியாக உருவாக்க விரும்பலாம், அவை பிற்கால திட்ட வெளியீடுகளுடன் முரண்படாது." + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" +"மேம்பாட்டு வெளியீட்டு பிரிவை உள்ளடக்கிய பதிப்பு அடையாளங்காட்டி \"மேம்பாட்டு வெளியீடு\" " +"என்று அழைக்கப்படுகிறது." + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" +"மேம்பாட்டு வெளியீட்டு பிரிவு `` .dev`` என்ற சரத்தைக் கொண்டுள்ளது, அதைத் தொடர்ந்து " +"எதிர்மறை அல்லாத முழு எண் மதிப்பு. மேம்பாட்டு வெளியீடுகள் அவற்றின் எண் கூறுகளால் ஆர்டர் " +"செய்யப்படுகின்றன, அதனுடன் தொடர்புடைய வெளியீட்டிற்கு முன்பே (மற்றும் ஒரே வெளியீட்டு " +"பிரிவுடன் எந்தவொரு முன் வெளியீட்டிற்கும் முன்பு), மற்றும் முந்தைய வெளியீட்டைப் பின்பற்றி " +"(எந்தவொரு பிந்தைய வெளியீடுகளும் உட்பட)." + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" +"முன் வெளியீடுகள் மற்றும் பிந்தைய வெளியீடுகளுக்கு வளர்ச்சி வெளியீடுகளும் " +"அனுமதிக்கப்படுகின்றன ::" + +#: ../source/specifications/version-specifiers.rst:346 +#, fuzzy +#| msgid "" +#| "Developmental releases are also permitted for pre-releases and post-" +#| "releases::" +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" +"முன் வெளியீடுகள் மற்றும் பிந்தைய வெளியீடுகளுக்கு வளர்ச்சி வெளியீடுகளும் " +"அனுமதிக்கப்படுகின்றன ::" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" +"தொடர்ச்சியான ஒருங்கிணைப்பு நோக்கங்களுக்காக அவை பயனுள்ளதாக இருக்கும் என்றாலும், பொது " +"நோக்கத்திற்கான பொது குறியீட்டு சேவையகங்களுக்கு முன் வெளியீடுகளின் மேம்பாட்டு வெளியீடுகளை " +"வெளியிடுவது வலுவாக ஊக்கமளிக்கிறது, ஏனெனில் இது பதிப்பு அடையாளங்காட்டியை மனித " +"வாசகர்களுக்கு அலசுவது கடினம். அத்தகைய வெளியீட்டை வெளியிட வேண்டியிருந்தால், எண் கூறுகளை " +"அதிகரிப்பதன் மூலம் புதிய முன் வெளியீட்டை உருவாக்குவது கணிசமாக தெளிவாக உள்ளது." + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" +"பிந்தைய வெளியீடுகளின் மேம்பாட்டு வெளியீடுகளும் கடுமையாக ஊக்கமளிக்கின்றன, ஆனால் அவை " +"குறியீடு மாற்றங்களை உள்ளடக்கிய முழு பராமரிப்பு வெளியீடுகளுக்கு வெளியீட்டுக்குப் பிந்தைய " +"குறியீட்டைப் பயன்படுத்தும் திட்டங்களுக்கு அவை பொருத்தமானதாக இருக்கலாம்." + +#: ../source/specifications/version-specifiers.rst:364 +msgid "Version epochs" +msgstr "பதிப்பு சகாப்தங்கள்" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" +"பதிப்பு அடையாளங்காட்டியில் சேர்க்கப்பட்டால், சகாப்தம் மற்ற எல்லா கூறுகளுக்கும் முன்பாக " +"தோன்றும், வெளியீட்டு பிரிவில் இருந்து ஆச்சரியக் குறி ::" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" +"வெளிப்படையான சகாப்தம் எதுவும் கொடுக்கப்படவில்லை என்றால், மறைமுகமான சகாப்தம் `` 0`` ஆகும்." + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" +"பெரும்பாலான பதிப்பு அடையாளங்காட்டிகள் ஒரு சகாப்தத்தை சேர்க்காது, ஏனெனில் ஒரு திட்டம் * " +"மாற்றினால் மட்டுமே வெளிப்படையான சகாப்தம் தேவைப்படுகிறது * இது பதிப்பு எண்ணிக்கையை " +"கையாளும் விதத்தில் சாதாரண பதிப்பு வரிசைப்படுத்தும் விதிகள் தவறான பதிலைக் கொடுக்கும். " +"எடுத்துக்காட்டாக, ஒரு திட்டம் `` 2014.04`` போன்ற தேதி அடிப்படையிலான பதிப்புகளைப் " +"பயன்படுத்துகிறது மற்றும் `` 1.0`` போன்ற சொற்பொருள் பதிப்புகளுக்கு மாற விரும்பினால், " +"புதிய வெளியீடுகள் சாதாரண வரிசையாக்கத் திட்டத்தைப் பயன்படுத்தும் போது தேதி அடிப்படையிலான " +"வெளியீடுகளை விட * பழையவை * என அடையாளம் காணப்படும் ::" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" +"இருப்பினும், ஒரு வெளிப்படையான சகாப்தத்தைக் குறிப்பிடுவதன் மூலம், வரிசை வரிசையை சரியான " +"முறையில் மாற்ற முடியும், ஏனெனில் முந்தைய சகாப்தத்தின் அனைத்து பதிப்புகளும் முந்தைய " +"சகாப்தத்தின் பதிப்புகளுக்குப் பிறகு வரிசைப்படுத்தப்படுகின்றன ::" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +msgid "Normalization" +msgstr "இயல்பாக்கம்" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" +"தற்போதுள்ள பதிப்புகளுடன் சிறந்த பொருந்தக்கூடிய தன்மையைப் பராமரிக்க, பல \"மாற்று\" " +"தொடரியல் உள்ளன, அவை பதிப்புகளை பாகுபடுத்தும்போது கணக்கில் எடுத்துக்கொள்ளப்பட வேண்டும். " +"ஒரு பதிப்பை பாகுபடுத்தும்போது இந்த தொடரியல் கருத்தில் கொள்ளப்பட வேண்டும், இருப்பினும் அவை " +"மேலே வரையறுக்கப்பட்ட நிலையான தொடரியல் க்கு \"இயல்பாக்கப்பட வேண்டும்\"." + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "வழக்கு உணர்திறன்" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" +"அனைத்து ASCII கடிதங்களும் ஒரு பதிப்பிற்குள் உணர்வற்ற முறையில் விளக்கப்பட வேண்டும் மற்றும் " +"சாதாரண வடிவம் சிறிய எழுத்துக்கள். இது `` 1.1rc1`` போன்ற பதிப்புகளை அனுமதிக்கிறது, " +"இது `1.1rc1`` க்கு இயல்பாக்கப்படும்." + +#: ../source/specifications/version-specifiers.rst:433 +msgid "Integer Normalization" +msgstr "முழு எண் இயல்பாக்கம்" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" +"அனைத்து முழு எண்ணும் `` இன்ட் () `` வழியாக விளக்கப்பட்டு வெளியீட்டின் சரம் வடிவத்தை " +"இயல்பாக்குகிறது. இதன் பொருள் `` 00`` இன் முழு எண் பதிப்பு `` 0`` க்கு இயல்பாக்கும், அதே " +"நேரத்தில் `09000``` `9000`` க்கு இயல்பாக்கும். `` 1.0+FOO0100`` போன்ற உள்ளக பதிப்பின் " +"எண்ணெழுத்து பிரிவின் உள்ளே நுழைவதற்கு இது உண்மையல்ல, இது ஏற்கனவே அதன் இயல்பாக்கப்பட்ட " +"வடிவத்தில் உள்ளது." + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "முன் வெளியீட்டு பிரிப்பான்கள்" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" +"முன் வெளியீடுகள் வெளியீட்டுப் பிரிவுக்கும் வெளியீட்டுக்கு முந்தைய பிரிவுக்கும் இடையில் ஒரு " +"`` .` .`. இதற்கான சாதாரண வடிவம் பிரிப்பான் இல்லாமல் உள்ளது. இது `` 1.1. இது ஒரு " +"பிரிப்பான் முன் வெளியீட்டு அடையாளத்திற்கும் எண்களுக்கும் இடையில் பயன்படுத்த அனுமதிக்க " +"வேண்டும். இது `` 1.0a.1`` போன்ற பதிப்புகளை அனுமதிக்கிறது, இது `` 1.0a1`` க்கு " +"இயல்பாக்கப்படும்." + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "முன் வெளியீட்டு எழுத்துப்பிழை" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" +"முன்-வெளியீடுகள் `` ஆல்பா``, `` பீட்டா``, `சி``,` `முன்``, மற்றும்` `பி``,` `rc``,` " +"`rc`, மற்றும்` `` `` `` `` `` `` `` `` `` `` `` `` `` `` இது `` 1.1alpha1``, " +"`` 1.1beta2``, அல்லது `` 1.1c3`` போன்ற பதிப்புகளை `` 1.1a1``, `` 1.1b2``, மற்றும் " +"`1rc3`` போன்ற பதிப்புகளை அனுமதிக்கிறது. ஒவ்வொரு சந்தர்ப்பத்திலும் கூடுதல் எழுத்துப்பிழை " +"அவற்றின் சாதாரண வடிவங்களுக்கு சமமானதாக கருதப்பட வேண்டும்." + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "மறைமுகத்திற்கு முந்தைய வெளியீடு எண்" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" +"முன் வெளியீடுகள் எண்களைத் தவிர்ப்பதற்கு அனுமதிக்கின்றன, இந்த விசயத்தில் அது `` 0`` என்று " +"மறைமுகமாக கருதப்படுகிறது. இதற்கான சாதாரண வடிவம் `` 0`` வெளிப்படையாக சேர்க்க " +"வேண்டும். இது `` 1.2a`` போன்ற பதிப்புகளை அனுமதிக்கிறது, இது `` 1.2A0`` க்கு " +"இயல்பாக்கப்படுகிறது." + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "வெளியீட்டு பிரிப்பான்கள் இடுகை" + +#: ../source/specifications/version-specifiers.rst:475 +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 "" +"போச்ட் வெளியீடுகள் ஒரு `` .``, `` --``, அல்லது `` _`` பிரிப்பான் மற்றும் பிரிப்பான் " +"அனைத்தையும் ஒன்றாகத் தவிர்ப்பதை அனுமதிக்கின்றன. இதன் இயல்பான வடிவம் `` .`` பிரிப்பான். " +"இது `` 1.2-post2`` அல்லது `1.2 போச்ட் 2`` போன்ற பதிப்புகளை` `1.2.post2`` க்கு " +"இயல்பாக்குகிறது. முன் வெளியீட்டு பிரிப்பானைப் போலவே இது இடுகை வெளியீட்டு " +"அடையாளத்திற்கும் எண்களுக்கும் இடையில் விருப்பமான பிரிப்பான் அனுமதிக்கிறது. இது `` " +"1.2.post-2`` போன்ற பதிப்புகளை அனுமதிக்கிறது, இது `` 1.2.post2`` க்கு இயல்பாக்கும்." + +#: ../source/specifications/version-specifiers.rst:484 +msgid "Post release spelling" +msgstr "வெளியீட்டு எழுத்துப்பிழை இடுகை" + +#: ../source/specifications/version-specifiers.rst:486 +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 "" +"பிந்தைய உறவுகள் `` rev`` மற்றும் `` r`` ஆகியவற்றின் கூடுதல் எழுத்துப்பிழைகளை " +"அனுமதிக்கின்றன. இது `` 1.0-R4`` போன்ற பதிப்புகளை `` 1.0.post4`` க்கு " +"இயல்பாக்குகிறது. முன் வெளியீடுகளைப் போலவே கூடுதல் எழுத்துப்பிழைகள் அவற்றின் சாதாரண " +"வடிவங்களுக்கு சமமானதாக கருதப்பட வேண்டும்." + +#: ../source/specifications/version-specifiers.rst:493 +msgid "Implicit post release number" +msgstr "மறைமுகமான இடுகை வெளியீட்டு எண்" + +#: ../source/specifications/version-specifiers.rst:495 +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 "" +"போச்ட் வெளியீடுகள் எண்களைத் தவிர்ப்பதற்கு அனுமதிக்கின்றன, இந்த விசயத்தில் அது `` 0`` என்று " +"மறைமுகமாக கருதப்படுகிறது. இதற்கான சாதாரண வடிவம் `` 0`` வெளிப்படையாக சேர்க்க " +"வேண்டும். `` 1.2.post0`` க்கு இயல்பாக்கப்பட்ட `` 1.2.post`` போன்ற பதிப்புகளை இது " +"அனுமதிக்கிறது." + +#: ../source/specifications/version-specifiers.rst:501 +msgid "Implicit post releases" +msgstr "மறைமுகமான இடுகை வெளியீடுகள்" + +#: ../source/specifications/version-specifiers.rst:503 +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 "" +"பிந்தைய வெளியீடுகள் `` போச்ட்`` அடையாளங்காட்டியைத் தவிர்ப்பதற்கு அனுமதிக்கின்றன. இந்த " +"வடிவத்தைப் பயன்படுத்தும் போது பிரிப்பான் `` --`` ஆக இருக்க வேண்டும், வேறு எந்த வடிவமும் " +"அனுமதிக்கப்படவில்லை. இது `` 1.0-1`` போன்ற பதிப்புகளை `` 1.0.post1`` க்கு இயல்பாக்க " +"அனுமதிக்கிறது. இந்த குறிப்பிட்ட இயல்பாக்கம் மறைமுகமான இடுகை வெளியீட்டு எண் விதியுடன் " +"இணைந்து பயன்படுத்தப்படக்கூடாது. வேறு வார்த்தைகளில் கூறுவதானால், `` 1.0 -`` என்பது * " +"சரியான பதிப்பாக இல்லை, மேலும் இது * `1.0.post0`` க்கு * இயல்பாக்கப்படாது." + +#: ../source/specifications/version-specifiers.rst:512 +msgid "Development release separators" +msgstr "வளர்ச்சி வெளியீட்டு பிரிப்பான்கள்" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" +"வளர்ச்சி வெளியீடுகள் ஒரு `` .``, `` --``, அல்லது ஒரு `` _`` பிரிப்பான் மற்றும் " +"பிரிப்பான் அனைத்தையும் ஒன்றாகத் தவிர்ப்பதை அனுமதிக்கின்றன. இதன் இயல்பான வடிவம் `` .`` " +"பிரிப்பான். இது `` 1.2-DEV2`` அல்லது `1.2dev2`` போன்ற பதிப்புகளை` `1.2.dev2`` க்கு " +"இயல்பாக்குகிறது." + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "மறைமுக வளர்ச்சி வெளியீட்டு எண்" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" +"வளர்ச்சி வெளியீடுகள் எண்களைத் தவிர்ப்பதற்கு அனுமதிக்கின்றன, இந்த விசயத்தில் அது `` 0`` " +"என்று மறைமுகமாக கருதப்படுகிறது. இதற்கான சாதாரண வடிவம் `` 0`` வெளிப்படையாக சேர்க்க " +"வேண்டும். `` 1.2.dev0`` க்கு இயல்பாக்கப்பட்ட `` 1.2.dev`` போன்ற பதிப்புகளை இது " +"அனுமதிக்கிறது." + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "உள்ளக பதிப்பு பிரிவுகள்" + +#: ../source/specifications/version-specifiers.rst:532 +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 "" +"ஒரு உள்ளக பதிப்போடு, பிரிவுகளின் பிரிப்பாளராக `` .`` பயன்படுத்துவதோடு கூடுதலாக, `` " +"-`` மற்றும் `_`` ஆகியவற்றைப் பயன்படுத்துவதும் ஏற்றுக்கொள்ளத்தக்கது. சாதாரண வடிவம் `` .`` " +"எழுத்தைப் பயன்படுத்துகிறது. இது `` 1.0+உபுண்டு -1`` போன்ற பதிப்புகளை `` 1.0+உபுண்டு " +"1`` க்கு இயல்பாக்க அனுமதிக்கிறது." + +#: ../source/specifications/version-specifiers.rst:539 +msgid "Preceding v character" +msgstr "V எழுத்து முந்தையது" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" +"`` V1.0`` பதிப்புகளின் பொதுவான பதிப்பு குறியீட்டை ஆதரிப்பதற்காக, ஒரு நேரடி `v`` " +"பாத்திரத்தால் முன்னதாக இருக்கலாம். இந்த பாத்திரம் அனைத்து நோக்கங்களுக்காகவும் புறக்கணிக்கப்பட " +"வேண்டும் மற்றும் பதிப்பின் அனைத்து இயல்பாக்கப்பட்ட வடிவங்களிலிருந்தும் தவிர்க்கப்பட வேண்டும். " +"`` வி`` உடன் மற்றும் இல்லாமல் அதே பதிப்பு சமமானதாகக் கருதப்படுகிறது." + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "வழிநடத்தும் மற்றும் பின்தங்கிய இடைவெளி" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" +"ஒரு பதிப்பின் இயல்பாக்கப்பட்ட அனைத்து வடிவங்களிலிருந்தும் அமைதியாக புறக்கணிக்கப்பட்டு " +"அகற்றப்பட வேண்டும். இதில் `` \"\" `` `,` `\\ t``,` `\\ n``,` `\\ r``,` \\ f``, " +"மற்றும் `\\ v`` ஆகியவை அடங்கும். `` 1.0 \\ n`` போன்ற பதிப்பு போன்ற தற்செயலான " +"இடைவெளியை விவேகத்துடன் கையாள இது அனுமதிக்கிறது, இது `` 1.0`` ஐ இயல்பாக்குகிறது." + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "இணக்கமான பதிப்பு திட்டங்களின் எடுத்துக்காட்டுகள்" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" +"நிலையான பதிப்பு திட்டம் பொது மற்றும் தனியார் பைதான் திட்டங்களில் பரந்த அளவிலான அடையாள " +"நடைமுறைகளை உள்ளடக்கியதாக வடிவமைக்கப்பட்டுள்ளது. நடைமுறையில், திட்டத்தால் வழங்கப்படும் " +"முழு நெகிழ்வுத்தன்மையைப் பயன்படுத்த முயற்சிக்கும் ஒரு திட்டம் மனித பயனர்களுக்கு " +"பதிப்புகளின் ஒப்பீட்டு வரிசையைக் கண்டுபிடிப்பதில் சிரமப்பட்ட ஒரு சூழ்நிலையை உருவாக்கும், " +"மேலே உள்ள விதிகள் அனைத்து இணக்கமான கருவிகளும் தொடர்ந்து கட்டளையிடும் என்பதை " +"உறுதிசெய்தாலும்." + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" +"பின்வரும் எடுத்துக்காட்டுகள் வெவ்வேறு அணுகுமுறைகளின் ஒரு சிறிய தேர்வு திட்டங்கள் அவற்றின் " +"வெளியீடுகளை அடையாளம் காண தேர்வு செய்யலாம், அதே நேரத்தில் \"அண்மைக் கால வெளியீடு\" " +"மற்றும் \"அண்மைக் கால நிலையான வெளியீடு\" ஆகியவற்றை மனித பயனர்கள் மற்றும் தானியங்கி " +"கருவிகளால் எளிதில் தீர்மானிக்க முடியும் என்பதை உறுதிசெய்கிறது." + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "எளிய \"மேசர்.மினோர்\" பதிப்பு ::" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "எளிய \"மேசர்.மினோர்.மிக்ரோ\" பதிப்பு ::" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "ஆல்பா, பீட்டா மற்றும் வேட்பாளர் முன் வெளியீடுகளுடன் \"மேசர்.மினோர்\" பதிப்பு ::" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" +"மேம்பாட்டு வெளியீடுகளுடன் \"மேசர்.மினோர்\" பதிப்பு, வேட்பாளர்கள் மற்றும் சிறிய " +"திருத்தங்களுக்கு பிந்தைய வெளியீடுகளை வெளியிடுங்கள் ::" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" +"தேதி அடிப்படையிலான வெளியீடுகள், ஒவ்வொரு ஆண்டும் அதிகரிக்கும் சீரியலைப் பயன்படுத்தி, " +"பூச்சியத்தைத் தவிர்ப்பது ::" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "அனுமதிக்கப்பட்ட பின்னொட்டுகளின் சுருக்கம் மற்றும் உறவினர் வரிசைப்படுத்தல்" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" +"இந்த பிரிவு முதன்மையாக ஒரு பதிப்பு திட்டத்தை தீர்மானிக்கும் பைதான் விநியோகங்களின் " +"டெவலப்பர்களைக் காட்டிலும், விநியோக மெட்டாடேட்டாவை தானாக செயலாக்கும் கருவிகளின் " +"ஆசிரியர்களுக்காக வடிவமைக்கப்பட்டுள்ளது." + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" +"பதிப்பு அடையாளங்காட்டிகளின் சகாப்த பிரிவு கொடுக்கப்பட்ட சகாப்தத்தின் எண் மதிப்புக்கு ஏற்ப " +"வரிசைப்படுத்தப்பட வேண்டும். எபோச் பிரிவு எதுவும் இல்லை என்றால், மறைமுகமான எண் மதிப்பு `` " +"0`` ஆகும்." + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" +"பதிப்பு அடையாளங்காட்டிகளின் வெளியீட்டுப் பிரிவு இயல்பாக்கப்பட்ட வெளியீட்டு பிரிவு " +"பின்வருமாறு பாகுபடுத்தப்படும்போது பைதனின் டூப்பிள் வரிசையாக்கத்தின் அதே வரிசையில் " +"வரிசைப்படுத்தப்பட வேண்டும் ::" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" +"ஒப்பீட்டில் ஈடுபட்டுள்ள அனைத்து வெளியீட்டு பிரிவுகளும் தேவைக்கேற்ப பூச்சியங்களுடன் குறுகிய " +"பிரிவுகளைத் திணிப்பதன் மூலம் நிலையான நீளமாக மாற்றப்பட வேண்டும்." + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" +"ஒரு எண் வெளியீட்டிற்குள் (`` 1.0``, `` 2.7.3``), பின்வரும் பின்னொட்டுகள் " +"அனுமதிக்கப்படுகின்றன, மேலும் காட்டப்பட்டுள்ளபடி ஆர்டர் செய்யப்பட வேண்டும் ::" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" +"`` சி`` சொற்பொருளாக `` rc`` க்கு சமமானதாகக் கருதப்படுகிறது, மேலும் அது `` rc`` " +"போல வரிசைப்படுத்தப்பட வேண்டும் என்பதை நினைவில் கொள்க. ஒரு `சி`` இரண்டிற்கும் ஒரே " +"மாதிரியான வெளியீட்டுப் பிரிவில் தெளிவற்ற அதே பிரிவில் ஒரே மாதிரியான` `n`` ஐக் கொண்ட " +"வழக்கை கருவிகள் நிராகரிக்கலாம் மற்றும் விவரக்குறிப்புக்கு இணங்க வேண்டும்." + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" +"ஆல்பா (`` 1.0a1``), பீட்டா (`` 1.0b1``), அல்லது வேட்பாளரை (`1.0rc1``,` `1.0c1``) " +"வெளியிடும், பின்வரும் பின்னொட்டுகள் அனுமதிக்கப்படுகின்றன, மேலும் காட்டப்பட்டுள்ளபடி ஆர்டர் " +"செய்யப்பட வேண்டும் ::" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" +"ஒரு பிந்தைய வெளியீட்டிற்குள் (`` 1.0.post1``), பின்வரும் பின்னொட்டுகள் " +"அனுமதிக்கப்படுகின்றன, மேலும் அவை காட்டப்பட்டுள்ளபடி ஆர்டர் செய்யப்பட வேண்டும் ::" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" +"ஒரு எண் பதிப்பை (எ.கா. `` 1.0.dev456``, `` 1.0.post1``) உடனடியாகப் " +"பயன்படுத்தும்போது கூட, `` devn`` மற்றும் `` போச்ட்ன்`` எப்போதும் ஒரு புள்ளிக்கு முன்னதாக " +"இருக்க வேண்டும் என்பதை நினைவில் கொள்க." + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" +"ஒரு முன் வெளியீட்டிற்குள், பகிரப்பட்ட முன்னொட்டுடன் வெளியீடு அல்லது மேம்பாட்டு வெளியீட்டு " +"பிரிவுக்குள், வரிசைப்படுத்துதல் எண் கூறுகளின் மதிப்பால் இருக்க வேண்டும்." + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "பின்வரும் எடுத்துக்காட்டு சாத்தியமான பல சேர்க்கைகளை உள்ளடக்கியது ::" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "பதிப்பு வெவ்வேறு மேனிலை தரவு பதிப்புகளில் வரிசைப்படுத்துகிறது" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" +"மேனிலை தரவு V1.0 (: PEP: `241`) மற்றும் மேனிலை தரவு V1.1 (: PEP:` 314`) ஒரு " +"நிலையான பதிப்பு அடையாளம் அல்லது வரிசைப்படுத்தும் திட்டத்தை குறிப்பிடவில்லை. இருப்பினும் " +"மேனிலை தரவு V1.2 (: PEP: `345`) வரையறுக்கப்பட்ட ஒரு திட்டத்தை குறிப்பிடுகிறது: " +"PEP:` 386`." + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" +"எளிய நிறுவி ஏபிஐயின் தன்மை காரணமாக, ஒரு குறிப்பிட்ட வழங்கல் எந்த மேனிலை தரவு " +"பதிப்பைப் பயன்படுத்துகிறது என்பதை ஒரு நிறுவி அறிந்து கொள்ள முடியாது. கூடுதலாக, " +"நிறுவிகள் ஒரு திட்டத்தின் அனைத்து பதிப்புகளை நிறுவ வேண்டும் என்பதை தீர்மானிக்க அனைத்தையும் " +"உள்ளடக்கிய ஒரு நியாயமான முன்னுரிமை பட்டியலை உருவாக்கும் திறன் தேவைப்பட்டது. இந்த " +"தேவைகள் ஒரு திட்டத்தின் அனைத்து பதிப்புகளுக்கும் பயன்படுத்தப்பட வேண்டிய ஒரு பாகுபடுத்தும் " +"பொறிமுறையில் ஒரு தரப்படுத்தல் தேவைப்படுகிறது." + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" +"மேற்கூறியவற்றின் காரணமாக, இந்த விவரக்குறிப்பு மேனிலை தரவு மற்றும் சூப்பர்செட்களின் " +"அனைத்து பதிப்புகளுக்கும் பயன்படுத்தப்பட வேண்டும்: PEP: `386` மேனிலை தரவு V1.2 க்கு " +"கூட. இந்த விவரக்குறிப்பில் உள்ள விதிகளால் பாகுபடுத்த முடியாத எந்த பதிப்புகளையும் " +"கருவிகள் புறக்கணிக்க வேண்டும், ஆனால் இந்த விவரக்குறிப்புக்கு இணங்காத பதிப்புகள் எதுவும் " +"கிடைக்கவில்லை என்றால், வரையறுக்கப்பட்ட பதிப்பு பாகுபடுத்தல் மற்றும் வரிசைப்படுத்தும் " +"திட்டங்களை செயல்படுத்தலாம்." + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" +"விநியோக பயனர்கள் தாங்கள் கட்டுப்படுத்தும் எந்தவொரு தனியார் தொகுப்பு குறியீடுகளிலிருந்தும் " +"இணங்காத பதிப்புகளை வெளிப்படையாக அகற்ற விரும்பலாம்." + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "பிற பதிப்பு திட்டங்களுடன் பொருந்தக்கூடிய தன்மை" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" +"இந்த விவரக்குறிப்பில் வரையறுக்கப்பட்ட பொது பதிப்பு திட்டத்திற்கு இணங்க மொழிபெயர்ப்பு " +"தேவைப்படும் பதிப்பு திட்டத்தைப் பயன்படுத்த சில திட்டங்கள் தேர்வு செய்யலாம். இதுபோன்ற " +"சந்தர்ப்பங்களில், திட்ட குறிப்பிட்ட பதிப்பை மெட்டாடேட்டாவில் சேமிக்க முடியும், அதே நேரத்தில் " +"மொழிபெயர்க்கப்பட்ட பொது பதிப்பு பதிப்பு புலத்தில் வெளியிடப்படுகிறது." + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" +"இது தானியங்கு விநியோக கருவிகளை வெளியிடப்பட்ட வெளியீடுகளின் தொடர்ச்சியாக சரியான " +"வரிசைப்படுத்தலை வழங்க அனுமதிக்கிறது, அதே நேரத்தில் உருவாக்குபவர்கள் தங்கள் திட்டங்களுக்கு " +"அவர்கள் விரும்பும் உள் பதிப்பு திட்டத்தைப் பயன்படுத்த அனுமதிக்கிறது." + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" +"`சொற்பொருள் பதிப்பு `_ என்பது ஒரு பிரபலமான பதிப்பு அடையாளத் திட்டமாகும், இது " +"வெளியீட்டு எண்ணின் வெவ்வேறு கூறுகளின் முக்கியத்துவத்தைப் பற்றிய இந்த விவரக்குறிப்பை விட " +"பரிந்துரைக்கப்படுகிறது. ஒரு திட்டம் சொற்பொருள் பதிப்பின் விவரங்களுக்கு கட்டுப்படக்கூடாது " +"என்று தேர்வுசெய்தாலும், மற்ற விநியோகங்களைப் பொறுத்து எழும் பல சிக்கல்களை இது " +"உள்ளடக்கியுள்ளதால், மற்றவர்கள் நம்பியிருக்கும் விநியோகத்தை வெளியிடும் போது இந்த திட்டம் " +"புரிந்து கொள்ளத்தக்கது." + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" +"சொற்பொருள் பதிப்பின் (இந்த விவரக்குறிப்பில் \"மேசர்.மினோர்\" என விவரிக்கப்பட்டுள்ளது " +"(2.0.0 விவரக்குறிப்பில் 1-8 உட்பிரிவுகள்) இந்த விவரக்குறிப்பில் வரையறுக்கப்பட்ட பதிப்பு " +"திட்டத்துடன் முழுமையாக ஒத்துப்போகும், மேலும் இந்த அம்சங்களை பின்பற்றுவது " +"ஊக்குவிக்கப்படுகிறது." + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" +"ஒரு ஐபன் (முன் -வெளியீடுகள் - பிரிவு 10) அல்லது ஒரு பிளச் அடையாளம் (கட்டடங்கள் - " +"பிரிவு 11) கொண்ட சொற்பொருள் பதிப்புகள் * இந்த விவரக்குறிப்புடன் பொருந்தாது மற்றும் பொது " +"பதிப்பு துறையில் அனுமதிக்கப்படாது." + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" +"இதுபோன்ற சொற்பொருள் பதிப்பு அடிப்படையிலான மூல லேபிள்களை இணக்கமான பொது பதிப்புகளுக்கு " +"மொழிபெயர்ப்பதற்கான ஒரு வழிமுறை, பொருத்தமான பதிப்பு வரிசையைக் குறிப்பிட `` .devn`` " +"பின்னொட்டைப் பயன்படுத்துவது." + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "உள்ளக பதிப்பு லேபிள்களிலும் குறிப்பிட்ட உருவாக்க தகவல்கள் சேர்க்கப்படலாம்." + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "டி.வி.சி.எச் அடிப்படையிலான பதிப்பு லேபிள்கள்" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" +"பதிப்பு அடையாளங்காட்டிக்கு அடையாளம் காணும் ஆசைச் சேர்க்க பல உருவாக்க கருவிகள் அறிவிலி " +"மற்றும் மெர்குரியல் போன்ற விநியோகிக்கப்பட்ட பதிப்பு கட்டுப்பாட்டு அமைப்புகளுடன் " +"ஒருங்கிணைக்கின்றன. ஆச்களை நம்பத்தகுந்த வகையில் ஆர்டர் செய்ய முடியாது, இதுபோன்ற பதிப்புகள் " +"பொது பதிப்பு துறையில் அனுமதிக்கப்படாது." + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "ஆச் தகவல்களை அடையாளம் காண்பது உள்ளக பதிப்பு லேபிள்களிலும் சேர்க்கப்படலாம்." + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "ஓல்சன் தரவுத்தள பதிப்பு" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" +"`` Pytz`` திட்டம் அதன் பதிப்புத் திட்டத்தை தொடர்புடைய ஓல்சன் டைம்சோன் தரவுத்தள பதிப்பு " +"திட்டத்திலிருந்து பெறுகிறது: அந்த ஆண்டுக்குள் தரவுத்தளத்தின் பதிப்பைக் குறிக்கும் சிறிய " +"எழுத்து ஆண்டு." + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" +"இதை ஒரு இணக்கமான பொது பதிப்பு அடையாளங்காட்டிக்கு `` <ஆண்டு> என மொழிபெயர்க்கலாம்." + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" +"பிற மொழிபெயர்க்கப்பட்ட பதிப்பு அடையாளங்காட்டிகளைப் போலவே, தொடர்புடைய ஓல்சன் தரவுத்தள " +"பதிப்பையும் திட்ட மெட்டாடேட்டாவில் பதிவு செய்யலாம்." + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" +"ஒரு பதிப்பு விவரக்குறிப்பு தொடர்ச்சியான பதிப்பு உட்பிரிவுகளைக் கொண்டுள்ளது, இது " +"காற்புள்ளிகளால் பிரிக்கப்பட்டுள்ளது. உதாரணமாக ::" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "ஒப்பீட்டு ஆபரேட்டர் பதிப்பு விதிமுறையை தீர்மானிக்கிறது:" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "`` ~ = ``: `இணக்கமான வெளியீடு`_ பிரிவு" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "`` == ``: `பதிப்பு பொருந்தும்`_ பிரிவு" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "``! = ``: `பதிப்பு விலக்கு`_ பிரிவு" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "`` <= ``, ``> = ``: `உள்ளடக்கிய உத்தரவிடப்பட்ட ஒப்பீடு`_ பிரிவு" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "`` <``, ``> ``: `பிரத்யேக உத்தரவிடப்பட்ட ஒப்பீடு`_ பிரிவு" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "`` === ``: `தன்னிச்சையான சமத்துவம்`_ பிரிவு." + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" +"கமா (\",\") ஒரு தர்க்கரீதியான ** மற்றும் ** ஆபரேட்டருக்கு சமம்: ஒரு வேட்பாளர் பதிப்பு " +"கொடுக்கப்பட்ட அனைத்து பதிப்பு உட்பிரிவுகளையும் பொருத்த வேண்டும்." + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" +"ஒரு நிபந்தனை ஆபரேட்டருக்கும் பின்வரும் பதிப்பு அடையாளங்காட்டிக்கும் இடையிலான இடைவெளி " +"விருப்பமானது, காற்புள்ளிகளைச் சுற்றியுள்ள இடைவெளி." + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" +"கீழே குறிப்பாக குறிப்பிடப்பட்ட இடத்தைத் தவிர, உள்ளக பதிப்பு அடையாளங்காட்டிகள் பதிப்பு " +"குறிப்பான்களில் அனுமதிக்கப்படக்கூடாது, மேலும் வேட்பாளர் பதிப்புகள் கொடுக்கப்பட்ட பதிப்பு " +"விவரக்குறிப்புடன் பொருந்துமா என்பதைச் சரிபார்க்கும்போது உள்ளக பதிப்பு லேபிள்கள் முற்றிலும் " +"புறக்கணிக்கப்பட வேண்டும்." + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "இணக்கமான வெளியீடு" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" +"இணக்கமான வெளியீட்டு பிரிவு இணக்கமான வெளியீட்டு ஆபரேட்டர் `` ~ = `` மற்றும் பதிப்பு " +"அடையாளங்காட்டியைக் கொண்டுள்ளது. குறிப்பிட்ட பதிப்போடு இணக்கமாக இருக்கும் என்று " +"எதிர்பார்க்கப்படும் எந்த வேட்பாளர் பதிப்பையும் இது பொருந்துகிறது." + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" +"குறிப்பிட்ட பதிப்பு அடையாளங்காட்டி `பதிப்பு திட்டம்`_ இல் விவரிக்கப்பட்டுள்ள நிலையான " +"வடிவத்தில் இருக்க வேண்டும். இந்த பதிப்பு விவரக்குறிப்பில் உள்ளக பதிப்பு அடையாளங்காட்டிகள் " +"அனுமதிக்கப்படவில்லை." + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" +"கொடுக்கப்பட்ட வெளியீட்டு அடையாளங்காட்டிக்கு `` v.n`` க்கு, இணக்கமான வெளியீட்டு விதிமுறை " +"ஒப்பீட்டு உட்பிரிவுகளின் சோடியுக்கு சமமானதாகும் ::" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" +"இந்த ஆபரேட்டர் `` ~ = 1`` போன்ற ஒற்றை பிரிவு பதிப்பு எண்ணுடன் பயன்படுத்தப்படக்கூடாது." + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "எடுத்துக்காட்டாக, பதிப்பு உட்பிரிவுகளின் பின்வரும் குழுக்கள் சமமானவை ::" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" +"ஒரு முன் வெளியீடு, வெளியீடு அல்லது மேம்பாட்டு வெளியீடு ஒரு இணக்கமான வெளியீட்டு பிரிவில் " +"`` v.n.suffix`` என பெயரிடப்பட்டால், தேவையான முன்னொட்டு பொருத்தத்தை தீர்மானிக்கும்போது " +"பின்னொட்டு புறக்கணிக்கப்படுகிறது ::" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" +"வெளியீட்டு பிரிவு ஒப்பீடுகளுக்கான திணிப்பு விதிகள் என்பது இணக்கமான வெளியீட்டு பிரிவில் " +"முன்னோக்கி பொருந்தக்கூடிய அளவைக் கருதுவதன் மூலம் கூடுதல் பூச்சியங்களை பதிப்பில் சேர்ப்பதன் " +"மூலம் கட்டுப்படுத்த முடியும் ::" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "பதிப்பு பொருந்தும்" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" +"ஒரு பதிப்பு பொருந்தும் பிரிவில் பதிப்பு பொருந்தும் ஆபரேட்டர் `` == `` மற்றும் பதிப்பு " +"அடையாளங்காட்டி ஆகியவை அடங்கும்." + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" +"இயல்பாக, பதிப்பு பொருந்தும் ஆபரேட்டர் கடுமையான சமத்துவ ஒப்பீட்டை அடிப்படையாகக் கொண்டது: " +"குறிப்பிட்ட பதிப்பு கோரப்பட்ட பதிப்பைப் போலவே இருக்க வேண்டும். வெளியீட்டுப் பிரிவுகள் ஒரே " +"நீளத்துடன் ஒப்பிடப்படுவதை உறுதிசெய்ய வெளியீட்டு பிரிவின் சுழிய திணிப்பு * மட்டுமே " +"செய்யப்படுகிறது." + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" +"கண்டிப்பான பதிப்பு பொருத்தம் பொருத்தமானது இல்லையா என்பது பதிப்பு விவரக்குறிப்புக்கான " +"குறிப்பிட்ட பயன்பாட்டு வழக்கைப் பொறுத்தது. தானியங்கு கருவிகள் குறைந்தபட்சம் எச்சரிக்கைகளை " +"வழங்க வேண்டும், மேலும் கடுமையான பதிப்பு போட்டிகள் தகாத முறையில் பயன்படுத்தப்படும்போது " +"அவற்றை முழுமையாக நிராகரிக்கலாம்." + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" +"பதிப்பு பொருந்தும் பிரிவில் பதிப்பு அடையாளங்காட்டிக்கு `` `` `` என்ற பின்தங்கியதைச் " +"சேர்ப்பதன் மூலம், கடுமையான ஒப்பீட்டுக்கு பதிலாக முன்னொட்டு பொருத்தம் கோரப்படலாம். பதிப்பு " +"அடையாளங்காட்டி பிரிவுடன் பொருந்துகிறதா இல்லையா என்பதை தீர்மானிக்கும்போது கூடுதல் " +"பின்தங்கிய பிரிவுகள் புறக்கணிக்கப்படும் என்பதே இதன் பொருள். குறிப்பிட்ட பதிப்பில் ஒரு " +"வெளியீட்டு பிரிவு மட்டுமே இருந்தால், வெளியீட்டு பிரிவில் உள்ள பின்வரும் கூறுகள் (அல்லது " +"அதன் பற்றாக்குறை) புறக்கணிக்கப்படுகின்றன." + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" +"எடுத்துக்காட்டாக, பதிப்பு `` 1.1.post1`` கொடுக்கப்பட்டால், பின்வரும் உட்பிரிவுகள் " +"பொருந்தாது அல்லது காட்டப்பட்டுள்ளபடி இல்லை ::" + +#: ../source/specifications/version-specifiers.rst:920 +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 "" +"முன்னொட்டு பொருத்தத்தின் நோக்கங்களுக்காக, வெளியீட்டுக்கு முந்தைய பிரிவு `` .`` க்கு " +"முந்தைய ஒரு மறைமுகத்தைக் கொண்டிருப்பதாகக் கருதப்படுகிறது, எனவே பதிப்பு `` 1.1a1```" + +#: ../source/specifications/version-specifiers.rst:928 +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::" +msgstr "" +"ஒரு சரியான போட்டி ஒரு முன்னொட்டு போட்டியாகவும் கருதப்படுகிறது (இந்த விளக்கம் பதிப்பு " +"அடையாளங்காட்டிகளின் வெளியீட்டு பிரிவுக்கான வழக்கமான சுழிய திணிப்பு விதிகளால் " +"குறிக்கப்படுகிறது). பதிப்பு `` 1.1`` கொடுக்கப்பட்டால், பின்வரும் உட்பிரிவுகள் பொருந்தாது " +"அல்லது காட்டப்பட்டுள்ளபடி இல்லை ::" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" +"`` 1.0.dev1.*`` அல்லது `` 1.0+foo1.*`` போன்ற வளர்ச்சி அல்லது உள்ளக வெளியீட்டைக் கொண்ட " +"முன்னொட்டு பொருத்தத்தைக் கொண்டிருப்பது தவறானது.*``. இருந்தால், வளர்ச்சி வெளியீட்டு பிரிவு " +"எப்போதும் பொது பதிப்பில் இறுதிப் பகுதியாகும், மேலும் உள்ளக பதிப்பு ஒப்பீட்டு " +"நோக்கங்களுக்காக புறக்கணிக்கப்படுகிறது, எனவே முன்னொட்டு போட்டியில் பயன்படுத்துவது எந்த " +"அர்த்தமும் இல்லை." + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" +"வெளியிடப்பட்ட விநியோகங்களுக்கான சார்புகளை வரையறுக்கும் போது `` == `` (குறைந்தபட்சம் " +"வைல்டு அட்டை பின்னொட்டு இல்லாமல்) பயன்பாடு பாதுகாப்புத் திருத்தங்களை வரிசைப்படுத்துவதை " +"பெரிதும் சிக்கலாக்குவதால் கடுமையாக ஊக்கமளிக்கிறது. பகிரப்பட்ட விநியோகக் குறியீட்டைப் " +"பயன்படுத்தும் போது மீண்டும் மீண்டும் செய்யக்கூடிய * பயன்பாடுகளின் வரிசைப்படுத்தல்களுக்கான " +"சார்புகளை வரையறுக்கும் போது கடுமையான பதிப்பு ஒப்பீட்டு ஆபரேட்டர் முதன்மையாக " +"பயன்பாட்டிற்காக கருதப்படுகிறது." + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +msgid "Version exclusion" +msgstr "பதிப்பு விலக்கு" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" +"பதிப்பு விலக்கு பிரிவில் பதிப்பு விலக்கு ஆபரேட்டர் ``! = `` மற்றும் பதிப்பு " +"அடையாளங்காட்டி ஆகியவை அடங்கும்." + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "உள்ளடக்கிய உத்தரவிட்ட ஒப்பீடு" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "உள்ளடக்கிய உத்தரவிடப்பட்ட ஒப்பீட்டு ஆபரேட்டர்கள் `` <= `` மற்றும் ``> = ``." + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "இந்த பதிப்பு விவரக்குறிப்பில் உள்ளக பதிப்பு அடையாளங்காட்டிகள் அனுமதிக்கப்படவில்லை." + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "பிரத்தியேக உத்தரவிடப்பட்ட ஒப்பீடு" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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 "" +"பிரத்யேக உத்தரவிடப்பட்ட ஒப்பீடு ``> v`` ** ** கொடுக்கப்பட்ட பதிப்பின் பிந்தைய வெளியீட்டை " +"அனுமதிக்கக்கூடாது `` v`` ஒரு இடுகை வெளியீடு. ``> V.postn`` ஐப் பயன்படுத்துவதன் மூலம் " +"கூடுதல் இடுகை வெளியீடுகள் உட்பட ஒரு குறிப்பிட்ட இடுகை வெளியீட்டை விட வெளியீடுகள் பின்னர் " +"இருக்க வேண்டும் என்று நீங்கள் கட்டளையிடலாம். எடுத்துக்காட்டாக, ``> 1.7`` `` 1.7.1`` ஆனால் " +"`` 1.7.0.post1`` மற்றும் `> 1.7.post2`` ஐ அனுமதிக்கும்` `1.7.1``` மற்றும்` " +"`1.7.0.post3`` அல்ல, ஆனால்` `1.7.0``." + +#: ../source/specifications/version-specifiers.rst:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" +"பிரத்யேக ஆர்டர் செய்யப்பட்ட ஒப்பீடு ``> v`` ** குறிப்பிட்ட பதிப்பின் உள்ளக பதிப்போடு " +"பொருந்தக்கூடாது." + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" +"மூல காப்பகம் மற்றும் சக்கர குறிப்புகளுக்கு, `` <ஆச்-அல்காரிதம்> = <எதிர்பார்க்கப்படும்-ஆச்> " +"`` முகவரி துண்டின் ஒரு பகுதியாக நுழைவு ஆகியவற்றைச் சேர்ப்பதன் மூலம் எதிர்பார்க்கப்படும் " +"ஆச் மதிப்பு குறிப்பிடப்படலாம்." + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" +"பதிப்பு கட்டுப்பாட்டு குறிப்புகளுக்கு, பதிப்பு கட்டுப்பாட்டு அமைப்பு மற்றும் பாதுகாப்பான " +"போக்குவரத்து இரண்டையும் அடையாளம் காண `` வி.சி.எச்+நெறிமுறை`` திட்டம் பயன்படுத்தப்பட " +"வேண்டும், மேலும் ஆச் அடிப்படையிலான கமிட் அடையாளங்காட்டிகளுடன் ஒரு பதிப்பு கட்டுப்பாட்டு " +"அமைப்பு பயன்படுத்தப்பட வேண்டும். ஆச் அடிப்படையிலான கமிட் அடையாளங்காட்டிகளை வழங்காத " +"பதிப்பு கட்டுப்பாட்டு அமைப்புகளுக்கான ஆச்களைக் காணவில்லை என்ற எச்சரிக்கைகளை தானியங்கு " +"கருவிகள் தவிர்க்கலாம்." + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" +"முகவரி இல் நேரடியாக கமிட் அல்லது டேக் குறிப்புகள் உட்பட ஆதரிக்காத பதிப்பு கட்டுப்பாட்டு " +"அமைப்புகளைக் கையாள, அந்த செய்தி `` `<கமிட்-ஆச்>` அல்லது ``@<குறிச்சொல்>#<கமிட்-ஆச்> `` " +"குறியீட்டைப் பயன்படுத்தி முகவரி இன் முடிவில் சேர்க்கப்படலாம்." + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" +"இது PIP ஆல் ஆதரிக்கப்படும் தற்போதுள்ள பகஅ குறிப்பு குறியீட்டைப் போலவே இல்லை. முதலாவதாக, " +"விநியோக பெயர் முகவரி இன் ஒரு பகுதியாக உட்பொதிக்கப்பட்டதை விட முன்னால் " +"நகர்த்தப்படுகிறது. இரண்டாவதாக, ஒரு குறிச்சொல்லின் அடிப்படையில் மீட்டெடுக்கும்போது கூட, " +"கமிட் ஆச் சேர்க்கப்பட்டுள்ளது, மேலே உள்ள தேவையை நிறைவு செய்வதற்காக *ஒவ்வொரு *இணைப்பும் " +"விசயங்களை உருவாக்க கடினமாக இருக்க ஒரு ஆச் இருக்க வேண்டும் (ஒரு குறிப்பிட்ட " +"குறிச்சொல்லுடன் தீங்கிழைக்கும் ரெப்போவை உருவாக்குவது எளிதானது, ஒரு குறிப்பிட்ட *ஆச் *உடன் " +"ஒன்றை உருவாக்குகிறது, குறைவாக)." + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "தொலைநிலை முகவரி எடுத்துக்காட்டுகள் ::" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "கோப்பு முகவரி கள்" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" +"கோப்பு முகவரி கள் `` கோப்பு: // <ஓச்ட்>/ `` வடிவத்தை எடுக்கின்றன. `` <ஓச்ட்> `` " +"தவிர்க்கப்பட்டால், அது `` உள்ளக ஓச்ட்`` என்று கருதப்படுகிறது, மேலும் `` <ஓச்ட்> `` " +"தவிர்க்கப்பட்டாலும் கூட மூன்றாவது சாய்வு இன்னும் இருக்க வேண்டும். `` `` `அணுக " +"வேண்டிய கோப்பு முறைமையின் கோப்பு பாதை என்ன என்பதை வரையறுக்கிறது." + +#: ../source/specifications/version-specifiers.rst:1184 +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 "" +"பல்வேறு \\*நிக்ச் இயக்க முறைமைகளில், `` <ஓச்ட்> `` க்கான ஒரே அனுமதிக்கப்பட்ட மதிப்புகள், " +"அதைத் தவிர்க்க வேண்டும், `` உள்ளக ஓச்ட்`` அல்லது தற்போதைய இயந்திரம் நம்பும் மற்றொரு fqdn " +"அதன் சொந்த ஓச்டுடன் பொருந்துகிறது. வேறு வார்த்தைகளில் கூறுவதானால், `` கோப்பு: // `` " +"திட்டத்தை உள்ளக கணினியில் பாதைகளை அணுக மட்டுமே பயன்படுத்த முடியும்." + +#: ../source/specifications/version-specifiers.rst:1189 +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 "" +"சாளரங்களில் கோப்பு வடிவத்தில் `` `` (எ.கா. `` `` கோப்பு: /// சி:/பாத்/டு/ஏ/" +"கோப்பு``) இன் ஒரு பகுதியாக பொருந்தினால் இயக்கி கடிதத்தை சேர்க்க வேண்டும். சாளரங்களில் " +"\\*நிக்ச் போலல்லாமல் `` <ஓச்ட்> `` பிணையம் பங்கில் வசிக்கும் கோப்பைக் குறிப்பிட அளவுரு " +"பயன்படுத்தப்படலாம். வேறு வார்த்தைகளில் கூறுவதானால், `` \\\\ இயந்திர \\ தொகுதி \\ " +"கோப்பு`` ஒரு `` கோப்பு: // `` முகவரி க்கு மொழிபெயர்க்க, இது `` கோப்பு: // இயந்திரம்/" +"தொகுதி/கோப்பு`` என முடிவடையும். சாளரங்களில் `` கோப்பு: // `` urls பற்றிய கூடுதல் " +"தகவலுக்கு `msdtn `_ project):" +msgstr "" +"பதிப்பு அடையாளங்காட்டியின் கூறுகளைப் பிரித்தெடுக்க, பின்வரும் வழக்கமான வெளிப்பாட்டைப் " +"பயன்படுத்தவும் (`பேக்கேசிங் _ _ திட்டம்):" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "ஆகச்ட் 2014: இந்த விவரக்குறிப்பு அங்கீகரிக்கப்பட்டது: PEP: `440`." + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "பைதான் மெய்நிகர் சூழல்கள்" + +#: ../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 "" +"பைதான் 3.3 மற்றும் பின்னர் பதிப்புகளுக்கு,: PEP: `405`\" பைதான் மெய்நிகர் சூழல்கள் \"என்ற " +"கருத்துக்கு மொழிபெயர்ப்பாளர் நிலை ஆதரவை அறிமுகப்படுத்தியது. ஒவ்வொரு மெய்நிகர் சூழலும் " +"அதன் சொந்த பைதான் பைனரி (பல்வேறு பைதான் பதிப்புகளுடன் சூழல்களை உருவாக்க அனுமதிக்கிறது) " +"மற்றும் அதன் தள கோப்பகங்களில் நிறுவப்பட்ட பைதான் தொகுப்புகளின் சொந்த சுயாதீனமான தொகுப்பைக் " +"கொண்டிருக்கலாம், ஆனால் நிலையான நூலகத்தை அடிப்படை நிறுவப்பட்ட பைத்தானுடன் பகிர்ந்து " +"கொள்கிறது. இந்த புதுப்பிப்புக்கு முன்னர் மெய்நிகர் சூழல்களின் கருத்து இருந்தபோதிலும், " +"அவற்றை அறிவிக்க அல்லது கண்டுபிடிப்பதற்கு முன்னர் தரப்படுத்தப்பட்ட வழிமுறை எதுவும் இல்லை." + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "மெய்நிகர் சூழல்களின் இயக்க நேர கண்டறிதல்" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +msgstr "" +"இயக்க நேரத்தில், மெய்நிகர் சூழல்களை நற்பண்பால் அடையாளம் காணலாம்: PY: தரவு: `sys.prefix` " +"(இயங்கும் மொழிபெயர்ப்பாளரின் கோப்பு முறைமை இருப்பிடம்) வேறுபட்ட மதிப்பைக் கொண்டுள்ளது: " +"py: தரவு:` sys.base_prefix` (நிலையான நூலக இயக்குநர்களின் இயல்புநிலை கோப்பு முறைமை " +"இருப்பிடம்)." + +#: ../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)." +msgstr "" +":ref:`venv-explanation` in the பைதான் தரநிலை library ஆவணப்படுத்துதல் க்கு " +"the :py:mod:`venv` தொகுதி மறையம் this along with the concept of " +"\"activating\" a virtual சூழல் in an interactive operating மண்டலம் ஓடு (this " +"activation படி is விரும்பினால் and hence the changes it makes can't be " +"reliably used பெறுநர் detect whether a பைதான் திட்டம் is running in a virtual " +"சூழல் or not)." + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "நிறுவல் சூழல்களை பைதான் மெய்நிகர் சூழல்களாக அறிவித்தல்" + +#: ../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." +msgstr "" +"இதில் விவரிக்கப்பட்டுள்ளபடி: PEP: `405`, ஒரு பைதான் மெய்நிகர் சூழலில் அதன் எளிமையான " +"வடிவத்தில் ஒரு` `தள-பேக்கேச்கள்` கோப்பகம் மற்றும் ஒரு` `pyvenv.cfg` கோப்புடன் ஒரு` " +"`pyvenv.cfg` கோப்புடன் ஒரு` `` pyvenv.cfg` கோப்புடன் ஒரு `` pyvenv.cfg` கோப்புடன் " +"ஒரு நகல் அல்லது சிம்லிங்க் ஆகியவற்றைத் தவிர வேறொன்றையும் கொண்டிருக்கவில்லை." + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" +"தரத்தின் தேவைகளைப் நிறைவு செய்ய வடிவமைக்கப்பட்டிருந்தாலும்: PY: MOD: `VEV` தொகுதி, " +"இந்த பிளவு நிறுவல் மற்றும்` `pyvenv.cfg`` கோப்பு அணுகுமுறை ஆகியவை * எந்த * பைதான் " +"நிறுவல் வழங்குநரால் பயன்படுத்தப்படலாம், அவை பைதான்-குறிப்பிட்ட கருவிகளை ஏற்கனவே ஒரு " +"மெய்நிகர் சூழலில் இயங்குகின்றன, மேலும் எந்தவொரு சூழலும் தேவையில்லை அல்லது தேவையில்லை." + +#: ../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 "" +"`` Pyvenv.cfg`` கோப்பு இல்லாத நிலையில் கூட, எந்தவொரு அணுகுமுறையும் (எ.கா. : py: " +"mod: `sysconfig`, கண்டறியப்பட்டு பைதான் மெய்நிகர் சூழலாக நடந்து கொள்ளும்." + +#: ../source/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "மே 2012: இந்த விவரக்குறிப்பு மூலம் அங்கீகரிக்கப்பட்டது: PEP: `405`." + +#: ../source/specifications/well-known-project-urls.rst:5 +msgid "Well-known Project URLs in Metadata" +msgstr "மெட்டாடேட்டாவில் நன்கு அறியப்பட்ட திட்ட முகவரி கள்" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" +"இந்த ஆவணம் முதன்மையாக மேனிலை தரவு *நுகர்வோர் *க்கு ஆர்வமாக உள்ளது, அவர் பைதான் " +"சுற்றுச்சூழல் அமைப்பு முழுவதும் திட்ட முகவரி களை வழங்குவதற்கு இயல்பாக்குதல் விதிகளையும் " +"நன்கு அறியப்பட்ட பட்டியலையும் பயன்படுத்த வேண்டும்." + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" +"மேனிலை தரவு * தயாரிப்பாளர்கள் * (உருவாக்க கருவிகள் மற்றும் தனிப்பட்ட தொகுப்பு " +"பராமரிப்பாளர்கள் போன்றவை) ஒட்டுமொத்த `` திட்ட-உர்எல்`` நீளக் கட்டுப்பாடுகளுக்குள் அவர்கள் " +"விரும்பும் எந்த லேபிள்களையும் தொடர்ந்து பயன்படுத்தலாம். இருப்பினும், முடிந்தால், பயனர்கள் " +"நன்கு அறியப்பட்ட லேபிள்களுக்கு இயல்பாக்கும் அர்த்தமுள்ள லேபிள்களை எடுக்க * " +"ஊக்குவிக்கப்படுகிறார்கள் *." + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" +"காண்க: குறிப்பு: `உங்கள் pyproject.toml-URL கள் <எழுதுதல்-pyproject-toml-urls>` " +"உங்கள் தொகுப்பின் மெட்டாடேட்டாவில் திட்ட முகவரி லேபிள்களைத் தேர்ந்தெடுப்பதற்கான பயனர் சார்ந்த " +"வழிகாட்டுதலுக்காக." + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "இந்த விவரக்குறிப்பு முதலில் வரையறுக்கப்பட்டது: PEP: `753`." + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" +". `` முகப்பு-பக்கம்``, `` பதிவிறக்கம்-உர்எல்`` அல்லது பிற பொதுவான திட்ட முகவரி கள்." + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" +"இது குறியீடுகளை (பைதான் தொகுப்பு அட்டவணை போன்றவை) மற்றும் பிற கீழ்நிலை மேனிலை தரவு " +"நுகர்வோர் திட்ட முகவரி களை சீரான முறையில் வழங்க அனுமதிக்கிறது." + +#: ../source/specifications/well-known-project-urls.rst:42 +msgid "Label normalization" +msgstr "சிட்டை இயல்பாக்கம்" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "சிட்டை இயல்பாக்கம் மேனிலை தரவு *நுகர்வோர் *, மேனிலை தரவு உற்பத்தியாளர்கள் அல்ல." + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" +"ஒரு `` திட்ட-உர்எல்`` சிட்டை \"நன்கு அறியப்பட்டதா\" என்பதை தீர்மானிக்க, மேனிலை தரவு " +"நுகர்வோர் லேபிளை ஒப்பிடுவதற்கு முன்பு இயல்பாக்க வேண்டும்: குறிப்பு: `நன்கு அறியப்பட்ட " +"லேபிள்களின் பட்டியல் <நன்கு அறியப்பட்ட-லேபிள்கள்>`." + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" +"`` Project-URL`` லேபிள்களுக்கான இயல்பாக்க செயல்முறை பின்வரும் பைதான் செயல்பாட்டால் " +"வரையறுக்கப்படுகிறது:" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" +"எளிய மொழியில்: அனைத்து ASCII நிறுத்தற்குறி மற்றும் இடைவெளிகளையும் நீக்குவதன் மூலம் ஒரு " +"சிட்டை * இயல்பாக்கப்பட்டது *, பின்னர் முடிவை சிறிய எழுத்துக்கு மாற்றுகிறது." + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" +"பின்வரும் அட்டவணை லேபிள்களின் எடுத்துக்காட்டுகளை (மூல) மற்றும் இயல்பாக்கத்திற்குப் பிறகு " +"காட்டுகிறது:" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "மூல" + +#: ../source/specifications/well-known-project-urls.rst:75 +msgid "Normalized" +msgstr "இயல்பாக்கப்பட்டது" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "`` முகப்புப்பக்கம்``" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "`` முகப்புப்பக்கம்``" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "`` முகப்பு-பக்கம்``" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "`` முகப்பு பக்கம்``" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "`` மாற்றம்_லாக்``" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "`` சேஞ்ச்லாக்``" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "`` புதியது என்ன? ``" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "`` வாட்ச்நியூ``" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "`` கிடினப்``" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "நன்கு அறியப்பட்ட லேபிள்கள்" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" +"நன்கு அறியப்பட்ட லேபிள்களின் பட்டியல் ஒரு வாழ்க்கைத் தரமாகும், இது இந்த ஆவணத்தின் ஒரு " +"பகுதியாக பராமரிக்கப்படுகிறது." + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" +"`` Project-URL`` மெட்டாடேட்டாவின் விளக்கக்காட்சியை நிபுணத்துவம் பெறுவதற்கான " +"நோக்கத்திற்காக நன்கு அறியப்பட்ட லேபிள்களை பின்வரும் அட்டவணை பட்டியலிடுகிறது:" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "சிட்டை (மனிதனால் படிக்கக்கூடிய சமமான)" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "மாற்றுப்பெயர்கள்" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "`` முகப்புப்பக்கத்தை` (முகப்புப்பக்கம்)" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "திட்டத்தின் முகப்பு பக்கம்" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "*(எதுவுமில்லை)*" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "`` மூல`` (மூலக் குறியீடு)" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "திட்டத்தின் புரவலன் செய்யப்பட்ட மூலக் குறியீடு அல்லது களஞ்சியம்" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "`` களஞ்சியம்``, `` சோர்ச் கோட்``, `` கிதுப்``" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "`` பதிவிறக்கம்`` (பதிவிறக்கம்)" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "தற்போதைய விநியோகத்திற்கான பதிவிறக்க முகவரி, `` பதிவிறக்கம்-url`` க்கு சமம்" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "`` சேஞ்ச்லாக்`` (சேஞ்ச்லாக்)" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "திட்டத்தின் விரிவான சேஞ்ச்லாக்" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "`` மாற்றங்கள்``, `` வாட்ச்நியூ``, `` வரலாறு``" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "`` வெளியீட்டு குறிப்புகள்)" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "திட்டத்தின் நிர்வகிக்கப்பட்ட வெளியீட்டுக் குறிப்புகள்" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "`` ஆவணங்கள்`` (ஆவணங்கள்)" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "திட்டத்தின் நிகழ்நிலை ஆவணங்கள்" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "`` டாக்ச்``" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "`` சிக்கல்கள்`` (டிராக்கர் வெளியீடு)" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "திட்டத்தின் பிழை டிராக்கர்" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" +"`` பிழைகள்``, `` வெளியீடு``, `` டிராக்கர்``, `` issuetracker``, `` bugtracker``" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "`` நிதி`` (நிதி)" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "பொருள் செய்தி" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "`` ச்பான்சர்``, `` நன்கொடை``, `` நன்கொடை``" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" +"தொகுப்பு மேனிலை தரவு நுகர்வோர் தங்கள் \"பெற்றோர்\" நன்கு அறியப்பட்ட லேபிளைப் போலவே " +"மாற்றியமைக்கப்பட்ட லேபிள்களை வழங்க தேர்வு செய்யலாம் அல்லது அவற்றை மேலும் நிபுணத்துவம் " +"பெறலாம்." + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "எடுத்துக்காட்டு நடத்தை" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" +"`` Pyproject.toml`` இலிருந்து கோர் மெட்டாடேட்டாவிலிருந்து சாத்தியமான குறியீட்டு " +"விளக்கக்காட்சிக்கு திட்ட முகவரி மெட்டாடேட்டாவின் ஓட்டத்தை பின்வருவது காட்டுகிறது:" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "நிலையான உள்ளமைவில் எடுத்துக்காட்டு திட்ட முகவரி கள்" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "கோர் மேனிலை தரவு பிரதிநிதித்துவம்" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "சாத்தியமான வழங்குதல்" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" +"பயனரால் வழங்கப்பட்ட வடிவத்தில் கோர் மேனிலை தரவு தோன்றும் என்பதைக் கவனியுங்கள் (மெட்டாடேட்டா " +"* தயாரிப்பாளர்கள் * இயல்பாக்கம் செய்யாததால்), ஆனால் மேனிலை தரவு * நுகர்வோர் * " +"இயல்பாக்கப்பட்ட வடிவத்தின் அடிப்படையில் பொருத்தமான மனித-படிக்கக்கூடிய சமமானவற்றை " +"இயல்பாக்குகிறது மற்றும் அடையாளம் காட்டுகிறது:" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" +"`` முகப்பு பக்கம்`` `` முகப்புப்பக்கத்தை`` ஆகிறது, இது `` முகப்புப்பக்கத்தை`` என " +"வழங்கப்படுகிறது" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "`` ஆவணங்கள்`` `` ஆவணங்கள்` ஏற்படுகிறது, இது `` ஆவணங்கள்`` என வழங்கப்படுகிறது" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" +"`` களஞ்சியம்`` `` களஞ்சியத்தை` `ஆகிறது, இது` `மூலக் குறியீடு`` என வழங்கப்படுகிறது" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" +"`` கிதுப்`` `` கிட்அப்`` ஆகிறது, இது `` மூலக் குறியீடு (கிதுப்) `` (`` மூலக் " +"குறியீடு`` இன் நிபுணத்துவமாக) என வழங்கப்படுகிறது)" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "ஆதரவைப் பெறுவது எப்படி" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" +"ஒரு குறிப்பிட்ட திட்டத்துடன் தொடர்புடைய ஆதரவுக்கு, டாக்: `திட்டங்கள் ` " +"பக்கம் ஆகியவற்றில் உள்ள இணைப்புகளைப் பார்க்கவும்." + +#: ../source/support.rst:8 +msgid "" +"For something more general, or when you're just not sure, please `open an " +"issue `_ on the `packaging-problems `_ repository on GitHub." +msgstr "" +"இன்னும் பொதுவான ஒன்றுக்கு, அல்லது உங்களுக்குத் தெரியாதபோது, தயவுசெய்து ஒரு சிக்கலைத் " +"திறக்கவும் `_ instead." +msgstr "" +"இந்த டுடோரியல் பேக்கேசிங் தொடர்பானது அல்ல, ஏனெனில் இது அளவிடப்படவில்லை. அதற்கு பதிலாக " +"`ச்பின்க்ச் டுடோரியல் _ _ ஐப் " +"பார்க்கவும்." + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" +"** பயிற்சிகள் ** பேக்கேசிங் கருத்துக்களை நன்கு அறிந்து கொள்ள உதவும் படிப்படியான " +"வழிகாட்டிகள். குறிப்பிட்ட பேக்கேசிங் தலைப்புகள் பற்றிய விரிவான தகவலுக்கு, காண்க: DOC: `/" +"வழிகாட்டிகள்/குறியீட்டு`." + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "தொகுப்புகளை நிறுவுதல்" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" +"இந்த பிரிவு பைத்தானை எவ்வாறு நிறுவுவது என்பதற்கான அடிப்படைகளை உள்ளடக்கியது: கால: " +"`தொகுப்புகள் <விநியோக தொகுப்பு>`." + +#: ../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 "" +"இந்த சூழலில் \"தொகுப்பு\" என்ற சொல் நிறுவப்பட வேண்டிய மென்பொருளை விவரிக்க " +"பயன்படுத்தப்படுகிறது என்பதை கவனத்தில் கொள்ள வேண்டும் (அதாவது A க்கு ஒத்ததாக: கால: " +"`விநியோக <விநியோக தொகுப்பு>`). இது உங்கள் பைதான் மூலக் குறியீட்டில் இறக்குமதி செய்யும் " +"(அதாவது தொகுதிகளின் கொள்கலன்) நீங்கள் இறக்குமதி செய்யும்: `தொகுப்பு <இறக்குமதி தொகுப்பு> " +"வகைகளைக் குறிக்கவில்லை. ஒரு: கால: `விநியோகம் <விநியோக தொகுப்பு>` \"தொகுப்பு\" என்ற " +"வார்த்தையைப் பயன்படுத்துவது பைதான் சமூகத்தில் பொதுவானது. \"வழங்கல்\" என்ற வார்த்தையைப் " +"பயன்படுத்துவது பெரும்பாலும் விரும்பப்படுவதில்லை, ஏனென்றால் இது லினக்ச் விநியோகத்துடன் " +"அல்லது பைத்தான் போன்ற மற்றொரு பெரிய மென்பொருள் விநியோகத்துடன் எளிதாக குழப்பமடையக்கூடும்." + +#: ../source/tutorials/installing-packages.rst:24 +msgid "Requirements for Installing Packages" +msgstr "தொகுப்புகளை நிறுவுவதற்கான தேவைகள்" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" +"இந்த பிரிவு பிற பைதான் தொகுப்புகளை நிறுவுவதற்கு முன் பின்பற்ற வேண்டிய படிகளை " +"விவரிக்கிறது." + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" +"`` பைதான் 3.6.3`` போன்ற சில வெளியீட்டை நீங்கள் பெற வேண்டும். உங்களிடம் பைதான் " +"இல்லையென்றால், தயவுசெய்து `python.org`_ இலிருந்து அண்மைக் கால 3.x பதிப்பை நிறுவவும் " +"அல்லது: குறிப்பு:` பைத்தானை நிறுவுதல் <பைதான்-வழிகாட்டியாக: நிறுவல்> `பைத்தானுக்கு " +"இட்சிகரின் வழிகாட்டியின் பிரிவு." + +#: ../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:62 +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." +msgstr "" +"ஏனென்றால், இந்த கட்டளையும் இந்த டுடோரியலில் பரிந்துரைக்கப்பட்ட பிற கட்டளைகளும் ஒரு *செல் " +"*இல் இயக்கப்பட வேண்டும் (ஒரு *முனையம் *அல்லது *கன்சோல் *என்றும் அழைக்கப்படுகிறது). உங்கள் " +"இயக்க முறைமையின் செல்லைப் பயன்படுத்துவதற்கும் பைத்தானுடன் தொடர்புகொள்வதற்கும் ஒரு " +"அறிமுகத்திற்கு தொடக்கக்காரர்களுக்கான பைதானைப் பார்க்கவும்." + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" +"தற்போது இயங்கும் நோட்புக்குடன் பொருந்தக்கூடிய பைதான் நிறுவலில் கட்டளைகள் இயங்குவதை உறுதி " +"செய்வதற்காக `` பைதான்`` ஐ விட `{sys.executable}` `எழுத பரிந்துரைக்கப்படுகிறது." + +#: ../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 "" +"பெரும்பாலான லினக்ச் விநியோகங்கள் பைதான் 3 இடம்பெயர்வுகளைக் கையாளும் விதம் காரணமாக, " +"முதலில் ஒரு மெய்நிகர் சூழலை உருவாக்காமல் கணினி பைத்தானைப் பயன்படுத்தும் லினக்ச் பயனர்கள் " +"இந்த டுடோரியலில் `` பைதான்`` கட்டளையை `` பைதான் 3`` மற்றும் `` பைதான் -எம் பிப்` கட்டளை " +"`` பைட்டான் 3. இந்த டுடோரியலில் உள்ள எந்தவொரு கட்டளைகளையும் `` sudo`` உடன் இயக்க " +"வேண்டாம்: உங்களுக்கு இசைவு பிழை ஏற்பட்டால், மெய்நிகர் சூழல்களை உருவாக்குவது குறித்த " +"பகுதிக்கு திரும்பி வந்து, ஒன்றை அமைத்து, பின்னர் எழுதப்பட்ட டுடோரியலுடன் தொடரவும்." + +#: ../source/tutorials/installing-packages.rst:95 +msgid "Ensure you can run pip from the command line" +msgstr "கட்டளை வரியிலிருந்து நீங்கள் PIP ஐ இயக்க முடியும் என்பதை உறுதிப்படுத்தவும்" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" +"கூடுதலாக, உங்களிடம் இருப்பதை உறுதி செய்ய வேண்டும்: குறிப்பு: `பிப்` கிடைக்கிறது. " +"இயங்குவதன் மூலம் இதை நீங்கள் சரிபார்க்கலாம்:" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" +"நீங்கள் மூலத்திலிருந்து பைத்தானை நிறுவியிருந்தால், `python.org`_ இலிருந்து ஒரு " +"நிறுவியுடன் அல்லது` ஓம் ப்ரூ`_ வழியாக உங்களிடம் ஏற்கனவே பிப் இருக்க வேண்டும். நீங்கள் " +"லினக்சில் இருந்தால், உங்கள் OS தொகுப்பு மேலாளரைப் பயன்படுத்தி நிறுவப்பட்டிருந்தால், நீங்கள் " +"PIP ஐ தனித்தனியாக நிறுவ வேண்டியிருக்கும், பார்க்க: DOC: `/வழிகாட்டிகள்/நிறுவுதல்-" +"பயன்படுத்தும்-லினக்ச்-கருவிகளை நிறுவுதல்." + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" +"`` பிப்`` ஏற்கனவே நிறுவப்படவில்லை என்றால், முதலில் அதை நிலையான நூலகத்திலிருந்து " +"தொடக்கவார் செய்ய முயற்சிக்கவும்:" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "பாதுகாப்பாக பதிவிறக்குங்கள்" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" +"`` பைதான் get-pip.py`` ஐ இயக்கவும். [2] _ இது PIP ஐ நிறுவும் அல்லது மேம்படுத்தும். " +"கூடுதலாக, இது நிறுவப்படும்: Ref: `setuptools` மற்றும்: ref:` சக்கரம்` அவை ஏற்கனவே " +"நிறுவப்படவில்லை என்றால்." + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" +"உங்கள் இயக்க முறைமை அல்லது மற்றொரு தொகுப்பு மேலாளரால் நிர்வகிக்கப்படும் பைதான் நிறுவலைப் " +"பயன்படுத்துகிறீர்கள் என்றால் எச்சரிக்கையாக இருங்கள். get-pip.py அந்த கருவிகளுடன் " +"ஒருங்கிணைக்காது, மேலும் உங்கள் கணினியை சீரற்ற நிலையில் விட்டுவிடக்கூடும். உள்நாட்டில் " +"நிறுவப்பட்ட மென்பொருளுக்காக வடிவமைக்கப்பட்ட ``/usr/local`` இல் நிறுவ `` பைதான் get-" +"pip.py-/USR/`` ஆகியவற்றைப் பயன்படுத்தலாம்." + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "பிப், செட்டுப்டூல்கள் மற்றும் சக்கரம் புதுப்பித்த நிலையில் இருப்பதை உறுதிசெய்க" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" +"முன்பே கட்டப்பட்ட பைனரி காப்பகங்களிலிருந்து நிறுவுவதற்கு `` பிப்`` மட்டும் போதுமானது " +"என்றாலும், `` செடிப்டூல்ச்`` மற்றும் `` வீல்`` திட்டங்களின் புதுப்பித்த நகல்கள் மூல " +"காப்பகங்களிலிருந்து நிறுவ முடியும் என்பதை உறுதிப்படுத்த பயனுள்ளதாக இருக்கும்:" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "விருப்பமாக, மெய்நிகர் சூழலை உருவாக்கவும்" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"See :ref:`section below ` for " +"details, but here's the basic :doc:`venv ` [3]_ command " +"to use on a typical Linux system:" +msgstr "" +"காண்க: குறிப்பு: `கீழே உள்ள பிரிவு <மெய்நிகர் சூழல்களை உருவாக்குதல் மற்றும் " +"பயன்படுத்துதல்>` விவரங்களுக்கு, ஆனால் இங்கே அடிப்படை: ஆவணம்: `வெவி <பைதான்: நூலகம்/" +"வென்வ்>` [3] _ ஒரு பொதுவான லினக்ச் கணினியில் பயன்படுத்த கட்டளை:" + +#: ../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:199 +msgid "Creating Virtual Environments" +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 "" +"பைதான் \"மெய்நிகர் சூழல்கள்\" பைதானை அனுமதிக்கின்றன: கால: `தொகுப்புகள் <விநியோக " +"தொகுப்பு>` உலகளவில் நிறுவப்படுவதை விட, ஒரு குறிப்பிட்ட பயன்பாட்டிற்கான " +"தனிமைப்படுத்தப்பட்ட இடத்தில் நிறுவப்பட வேண்டும். உலகளாவிய கட்டளை வரி கருவிகளை " +"பாதுகாப்பாக நிறுவ நீங்கள் விரும்பினால், காண்க: DOC: `/வழிகாட்டிகள்/நிறுவுதல்-தனித்த-" +"கட்டளை-கோட்டுகளை நிறுவுதல்." + +#: ../source/tutorials/installing-packages.rst:207 +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." +msgstr "" +"லிப்ஃபூவின் பதிப்பு 1 தேவைப்படும் பயன்பாடு உங்களிடம் இருப்பதாக கற்பனை செய்து பாருங்கள், " +"ஆனால் மற்றொரு பயன்பாட்டிற்கு பதிப்பு தேவைப்படுகிறது. இந்த இரண்டு பயன்பாடுகளையும் நீங்கள் " +"எவ்வாறு பயன்படுத்தலாம்? எல்லாவற்றையும் /usr/lib/python3.6/site-pagages (அல்லது உங்கள் " +"தளத்தின் நிலையான இருப்பிடம் எதுவாக இருந்தாலும்) நிறுவினால், மேம்படுத்தப்படாத ஒரு " +"பயன்பாட்டை நீங்கள் தற்செயலாக மேம்படுத்தும் சூழ்நிலையில் முடிவடைவது எளிது." + +#: ../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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "தற்போது, பைதான் மெய்நிகர் சூழல்களை உருவாக்க இரண்டு பொதுவான கருவிகள் உள்ளன:" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" +":doc:`venv ` is available by இயல்புநிலை in பைதான் 3.3 and " +"later, and installs :ref:`pip` into உருவாக்கப்பட்டது virtual environments in " +"பைதான் 3.4 and later (Python versions prior பெறுநர் 3.12 also " +"installed :ref:`setuptools`)." + +#: ../source/tutorials/installing-packages.rst:229 +#, fuzzy +#| 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)." +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" +":ref:`virtualenv` needs பெறுநர் be installed separately, but supports பைதான் " +"2.7+ and பைதான் 3.3+, and :ref:`pip`, :ref:`setuptools` and :ref:`wheel` அரே " +"எப்போதும் installed into உருவாக்கப்பட்டது virtual environments by இயல்புநிலை " +"(regardless of பைதான் version)." + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "அடிப்படை பயன்பாடு அவ்வாறு உள்ளது:" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "பயன்படுத்துதல்: DOC: `vev `:" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "பயன்படுத்துதல்: ref: `Virtualenv`:" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" +"மேலும் தகவலுக்கு, டி.ஓ.சி: `வெவி <பைதான்: நூலகம்/வென்வ்>` டாக்ச் அல்லது தி: டாக்: " +"`மெய்நிகர் ஈவ் <மெய்நிகர் ஈன்வ்: குறியீட்டு>` டாக்ச் ஆகியவற்றைக் காண்க." + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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 "" +"பல மெய்நிகர் சூழல்களை நேரடியாக நிர்வகிப்பது சிரமமாக மாறும், எனவே: ref: `சார்பு " +"மேலாண்மை பயிற்சி <நிர்வாக-சார்புநிலைகள்>` ஒரு உயர் மட்ட கருவியை " +"அறிமுகப்படுத்துகிறது,: re: `பைபென்வ்`, நீங்கள் பணிபுரியும் ஒவ்வொரு திட்டத்திற்கும் " +"பயன்பாட்டிற்கும் ஒரு தனி மெய்நிகர் சூழலை தானாக நிர்வகிக்கிறது." + +#: ../source/tutorials/installing-packages.rst:293 +msgid "Use pip for Installing" +msgstr "நிறுவ PIP ஐப் பயன்படுத்தவும்" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" +": ref: `பிப்` என்பது பரிந்துரைக்கப்பட்ட நிறுவி. கீழே, மிகவும் பொதுவான பயன்பாட்டு " +"காட்சிகளை நாங்கள் உள்ளடக்குவோம். மேலும் விவரங்களுக்கு, டிஓசி: `பிஐபி டாக்ச் <பிப்: " +"இன்டெக்ச்>`, இதில் முழுமையானது: டாக்: `குறிப்பு வழிகாட்டி <பிஐபி: சிஎல்ஐ/குறியீட்டு>` " +"ஐப் பார்க்கவும்." + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "PYPI இலிருந்து நிறுவுகிறது" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" +"இதன் மிகவும் பொதுவான பயன்பாடு: ref: `பிப்` என்பது நிறுவல்: கால:` பைதான் தொகுப்பு " +"குறியீட்டு <பைதான் தொகுப்பு குறியீட்டு (பைபி)> `ஒரு: காலத்தைப் பயன்படுத்துதல்:` தேவை " +"விவரக்குறிப்பு <தேவை விவரக்குறிப்பு> `. பொதுவாக, ஒரு தேவை விவரக்குறிப்பு ஒரு திட்டப் " +"பெயரை உள்ளடக்கியது, அதைத் தொடர்ந்து ஒரு விருப்ப: சொல்: `பதிப்பு விவரக்குறிப்பு <பதிப்பு " +"விவரக்குறிப்பு>`. ஆதரிக்கப்பட்ட குறிப்பான்களின் முழு விளக்கத்தையும்: ref: `பதிப்பு " +"விவரக்குறிப்பு விவரக்குறிப்பு <பதிப்பு-விவரக்குறிப்புகள்>` இல் காணலாம். சில " +"எடுத்துக்காட்டுகள் கீழே." + +#: ../source/tutorials/installing-packages.rst:311 +msgid "To install the latest version of \"SomeProject\":" +msgstr "\"Forproject\" இன் அண்மைக் கால பதிப்பை நிறுவ:" + +#: ../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 "" +"ஒரு பதிப்பை விட அதிகமாகவோ அல்லது சமமாகவோ நிறுவவும், மற்றொன்றை விட குறைவாகவும் " +"நிறுவுதல்:" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" +"ஒரு பதிப்பை நிறுவ: குறிப்பு: `இணக்கமான <பதிப்பு-விவரிப்பாளர்கள்-இணக்கமான-வெளியீடு>` " +"ஒரு குறிப்பிட்ட பதிப்போடு: [4] _" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" +"இந்த வழக்கில், \"== 1.4.*\" பதிப்பையும் நிறுவ வேண்டும் என்பதே இதன் பொருள் \"> = " +"1.4.2\"." + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "மூல வழங்கல் Vs சக்கரங்கள்" + +#: ../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: `-no-entar ` விருப்பம்." + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" +":term:`Wheels ` அரே a pre-built :term:`distribution ` வடிவம் that provides faster நிறுவல் compared பெறுநர் :term:`Source " +"Distributions (sdist) `, especially when a திட்டம் " +"contains compiled extensions." + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" +"If: ref: `பிப்` நிறுவ ஒரு சக்கரத்தைக் கண்டுபிடிக்கவில்லை, இது எதிர்காலத்தில் மூல " +"விநியோகத்தை மீண்டும் கட்டியெழுப்புவதற்குப் பதிலாக, உள்நாட்டில் ஒரு சக்கரத்தை உருவாக்கி " +"எதிர்கால நிறுவல்களுக்கு தற்காலிகமாக சேமிக்கும்." + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" +"ஏற்கனவே நிறுவப்பட்ட `` someproject`` ஐ பைபியிலிருந்து சமீபத்தியதாக மேம்படுத்தவும்." + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "பயனர் தளத்திற்கு நிறுவுதல்" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" +"நிறுவ: கால: `தொகுப்புகள் <விநியோக தொகுப்பு>` தற்போதைய பயனருக்கு தனிமைப்படுத்தப்பட்ட, " +"`` --user`` கொடியைப் பயன்படுத்தவும்:" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" +"மேலும் தகவலுக்கு, `பயனர் நிறுவல்கள் ` _ பிரிவு பிப் டாக்சிலிருந்து." + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +msgstr "" +"மெய்நிகர் சூழலுக்குள் இருக்கும்போது `` --user`` கொடி எந்த விளைவையும் ஏற்படுத்தாது " +"என்பதை நினைவில் கொள்க-அனைத்து நிறுவல் கட்டளைகளும் மெய்நிகர் சூழலை பாதிக்கும்." + +#: ../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`:" +msgstr "" +"எந்தவொரு கட்டளை-வரி ச்கிரிப்டுகள் அல்லது கன்சோல் நுழைவு புள்ளிகளை `` சில திட்ட` " +"`வரையறுத்தால்,` `--user`` அவை` பயனர் தளத்தின் `_ இன் பைனரி கோப்பகத்திற்குள் " +"நிறுவப்படும், இது ஏற்கனவே உங்கள் செல்லில் இருக்கலாம் அல்லது இல்லாமல் இருக்கலாம்: envvar: " +"`பாதை`. ." + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" +"லினக்ச் மற்றும் மேகோசில் நீங்கள் `` பைதான் -எம் தளத்தை -யூசர் -பேச்`` ஐ இயக்கி, `` பின்`` ஐ " +"இறுதிவரை சேர்ப்பதன் மூலம் பயனர் அடிப்படை பைனரி கோப்பகத்தைக் காணலாம். எடுத்துக்காட்டாக, " +"இது பொதுவாக `` ~/.local`` ஐ அச்சிடும் (`` `` `உங்கள் வீட்டு கோப்பகத்திற்கான முழுமையான " +"பாதைக்கு விரிவாக்கப்படும்) எனவே உங்கள்` `பாதை`` இல்` `~/.local/bin`` ஐ சேர்க்க " +"வேண்டும். `மாற்றியமைப்பதன் மூலம் உங்கள்` `பாதையை` நிரந்தரமாக அமைக்கலாம்." + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" +"சாளரங்களில் நீங்கள் `` py -m தளத்தை-பயனர்-தளத்தை `` `` தள-தொகுப்புகள்`` `` ச்கிரிப்ட்கள்`` " +"உடன் மாற்றுவதன் மூலம் பயனர் அடிப்படை பைனரி கோப்பகத்தைக் காணலாம். க்கு example, this " +"could return ``C:\\Users\\Username\\AppData\\Roaming\\Python36\\site-" +"packages`` so you would need பெறுநர் கணம் your ``PATH`` பெறுநர் include ``C:" +"\\Users\\Username\\AppData\\Roaming\\Python36\\Scripts``. உங்கள் பயனரை " +"`கட்டுப்பாட்டு குழு`_ இல் நிரந்தரமாக அமைக்கலாம். நடைமுறைக்கு வருவதற்கான `` பாதை` " +"`மாற்றங்களுக்கு நீங்கள் வெளியேற வேண்டியிருக்கலாம்." + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" +"A இல் குறிப்பிடப்பட்டுள்ள தேவைகளின் பட்டியலை நிறுவவும்: ref: `தேவைகள் கோப்பு `." + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "பகஅ இலிருந்து நிறுவுகிறது" + +#: ../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 `." +msgstr "" +"பகஅ இலிருந்து ஒரு திட்டத்தை \"திருத்தக்கூடிய\" பயன்முறையில் நிறுவவும். தொடரியல் முழு " +"முறிவுக்கு, பைப்பின் பகுதியைப் பார்க்கவும்: குறிப்பு: `வி.சி.எச் உதவி <பிஐபி: " +"வி.சி.எச் ஆதரவு>`." + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "பிற குறியீடுகளிலிருந்து நிறுவுகிறது" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "மாற்று குறியீட்டிலிருந்து நிறுவவும்" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" +"நிறுவலின் போது கூடுதல் குறியீட்டைத் தேடுங்கள், கூடுதலாக: கால: `பைபி <பைதான் தொகுப்பு " +"அட்டவணை (பைபி)>`" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "உள்ளக எச்.ஆர்.சி மரத்திலிருந்து நிறுவுகிறது" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" +"உள்ளக எச்.ஆர்.சியிலிருந்து நிறுவுதல்: டிஓசி: `மேம்பாட்டு முறை <செட்டப்டூல்ச்: பயனர் " +"வழிகாட்டி/மேம்பாட்டு பயன்முறை>`, ஐ.எச்.எச். திட்டம் நிறுவப்பட்டதாகத் தோன்றும் வகையில், " +"ஆனால் இன்னும் எச்.ஆர்.சி மரத்திலிருந்து திருத்தக்கூடியது." + +#: ../source/tutorials/installing-packages.rst:558 +msgid "You can also install normally from src" +msgstr "நீங்கள் பொதுவாக SRC இலிருந்து நிறுவலாம்" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" +"காப்பகங்களைக் கொண்ட உள்ளக கோப்பகத்திலிருந்து நிறுவவும் (மற்றும் சரிபார்க்க வேண்டாம்: சொல்: " +"`பைபி <பைதான் தொகுப்பு குறியீட்டு (பைபி)>`)" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "பிற மூலங்களிலிருந்து நிறுவுகிறது" + +#: ../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 "" +"பிற தரவு மூலங்களிலிருந்து நிறுவ (எடுத்துக்காட்டாக அமேசான் எச் 3 சேமிப்பிடம்) நீங்கள் ஒரு " +"உதவி பயன்பாட்டை உருவாக்கலாம், இது ஒரு வடிவத்தில் இணக்கமான வடிவத்தில் வழங்கலாம்: ref: " +"`எளிய களஞ்சிய பநிஇ <எளிய-ரோபோசிட்டரி-ஏபிஐ>`:, மற்றும் ``-எக்ச்ட்ரா-இன்டெக்ச்-உர்எல்``` " +"கொடியை அந்த குறியீட்டைப் பயன்படுத்துவதற்கு நேரடியாகப் பயன்படுத்தவும்." + +#: ../source/tutorials/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "முன்நிபந்தனைகளை நிறுவுதல்" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" +"நிலையான பதிப்புகளுக்கு கூடுதலாக, முன் வெளியீடு மற்றும் மேம்பாட்டு பதிப்புகளைக் " +"கண்டறியவும். இயல்பாக, பிஐபி நிலையான பதிப்புகளை மட்டுமே காண்கிறது." + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "\"கூடுதல்\" நிறுவுதல்" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" +"கூடுதல் ஒரு தொகுப்பின் விருப்பமான \"மாறுபாடுகள்\" ஆகும், இதில் கூடுதல் சார்புநிலைகள் " +"இருக்கலாம், இதன் மூலம் தொகுப்பிலிருந்து கூடுதல் செயல்பாட்டை செயல்படுத்துகின்றன. ஒன்றை " +"வெளியிடுவது உங்களுக்குத் தெரிந்த ஒரு தொகுப்புக்கு கூடுதல் நிறுவ விரும்பினால், நீங்கள் " +"அதை PIP நிறுவல் கட்டளையில் சேர்க்கலாம்:" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" +"இந்த சூழலில் \"பாதுகாப்பானது\" என்பது நவீன உலாவி அல்லது ஒரு கருவியைப் " +"பயன்படுத்துவதாகும்: கட்டளை: `சுருட்டை` இது HTTPS முகவரி களில் இருந்து பதிவிறக்கும் " +"போது SSL சான்றிதழ்களை சரிபார்க்கிறது." + +#: ../source/tutorials/installing-packages.rst:675 +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`." +msgstr "" +"பைதான் 3.4 உடன் தொடங்கி, `` வெர்வ்`` (ஒரு எச்.டி.எல்.ஐ.பி மாற்று: ref: `மெய்நிகர்என்வ்`) " +"மெய்நிகர் ஈட்டிங் சூழல்களை முன் நிறுவப்பட்ட` `பிஐபி`` உடன் உருவாக்கும், இதனால் இது சமமான " +"மாற்றாக அமைகிறது: குறிப்பு:` மெய்நிகர் ஈன்வ்`." + +#: ../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" +msgstr "" +"இணக்கமான வெளியீட்டு விவரக்குறிப்பு ஏற்றுக்கொள்ளப்பட்டது: PEP: `440` மற்றும் உதவி " +"வெளியிடப்பட்டது: Ref:` setuptools` v8.0 மற்றும்: Ref: `Pip` v6.0" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "விண்ணப்ப சார்புகளை நிர்வகித்தல்" + +#: ../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." +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." +msgstr "" +"எவ்வாறாயினும், இந்த கட்டளைகளை ஊடாடும் வகையில் இயக்குவது உங்கள் சொந்த திட்டங்களுக்கு கூட " +"கடினமாகிவிடும், மேலும் பல பங்களிப்பாளர்களைக் கொண்ட திட்டங்களுக்கு தானாகவே மேம்பாட்டு " +"சூழல்களை அமைக்க முயற்சிக்கும்போது விசயங்கள் இன்னும் கடினமாகிவிடும்." + +#: ../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: `பைபென்வ்` ஒரு " +"விண்ணப்பத்திற்கான சார்புகளை நிர்வகிக்க. தேவையான கருவிகளை எவ்வாறு நிறுவுவது மற்றும் " +"பயன்படுத்துவது மற்றும் சிறந்த நடைமுறைகளில் வலுவான பரிந்துரைகளை வழங்குவது என்பதை இது " +"காண்பிக்கும்." + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" +"பைத்தான் பல வேறுபட்ட நோக்கங்களுக்காகப் பயன்படுத்தப்படுகிறது என்பதை நினைவில் கொள்ளுங்கள், " +"மேலும் உங்கள் மென்பொருளை எவ்வாறு வெளியிட முடிவு செய்கிறீர்கள் என்பதன் அடிப்படையில் உங்கள் " +"சார்புகளை எவ்வாறு நிர்வகிக்க விரும்புகிறீர்கள் என்பதை துல்லியமாக மாற்றலாம். இங்கு " +"வழங்கப்பட்ட வழிகாட்டுதல் பிணையம் சேவைகளின் (வலை பயன்பாடுகள் உட்பட) வளர்ச்சி மற்றும் " +"வரிசைப்படுத்தலுக்கு நேரடியாக பொருந்தும், ஆனால் எந்தவொரு திட்டத்திற்கும் வளர்ச்சி மற்றும் " +"சோதனை சூழல்களை நிர்வகிப்பதற்கும் இது மிகவும் பொருத்தமானது." + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "மாற்றுகளுக்கு, பயன்பாட்டு சார்பு மேலாண்மைக்கான பிற கருவிகளைப் பார்க்கவும் `_." + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "பைபென்வ் நிறுவுதல்" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" +": குறிப்பு: `பைபென்வ்` பைதான் திட்டங்களுக்கான சார்பு மேலாளர். Node.js 'npm`_ அல்லது " +"ரூபியின் `பண்ட்லர்`_ உடன் உங்களுக்கு தெரிந்திருந்தால், அது அந்தக் கருவிகளுக்கு ஆவிக்கு " +"ஒத்ததாகும். அதே நேரத்தில்: ref: `பிப்` மட்டும் பெரும்பாலும் தனிப்பட்ட பயன்பாட்டிற்கு " +"போதுமானது, கூட்டு திட்டங்களுக்கு பைபென்வி பரிந்துரைக்கப்படுகிறது, ஏனெனில் இது பொதுவான " +"பயன்பாட்டு நிகழ்வுகளுக்கு சார்பு நிர்வாகத்தை எளிதாக்கும் உயர் மட்ட கருவியாகும்." + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "பைபென்வை நிறுவ `` பிப்`` ஐப் பயன்படுத்தவும்:" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" +"எந்தவொரு கணினி அளவிலான தொகுப்புகளையும் உடைப்பதைத் தடுக்க இது `பயனர் நிறுவல்`_ " +"செய்கிறது. நிறுவலுக்குப் பிறகு உங்கள் செல்லில் `` பைபென்வ்`` கிடைக்கவில்லை என்றால், நீங்கள்: " +"py: தரவு: `பயனர் அடிப்படை <பைதான்: site.user_base>` இன் பைனரி அடைவு உங்கள் `` " +"பாதை`` சேர்க்க வேண்டும். காண்க: குறிப்பு: `பயனர் தளத்திற்கு நிறுவுதல்` மேலும் தகவலுக்கு." + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "உங்கள் திட்டத்திற்கான தொகுப்புகளை நிறுவுதல்" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +msgstr "" +"PIPENV ஒரு திட்டத்தின் அடிப்படையில் சார்புகளை நிர்வகிக்கிறது. தொகுப்புகளை நிறுவ, உங்கள் " +"திட்டத்தின் கோப்பகத்தில் மாற்றவும் (அல்லது இந்த டுடோரியலுக்கான வெற்று அடைவு) மற்றும் " +"இயக்கவும்:" + +#: ../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):" +msgstr "" +"பைபென்வி `கோரிக்கைகள்`_ நூலகத்தை நிறுவி, உங்கள் திட்டத்தின் கோப்பகத்தில் உங்களுக்காக ஒரு` " +"`பிப்ஃபைல்`` உருவாக்கும். தி: ரெஃப்: `பிப்ஃபைல்` உங்கள் திட்டத்தை நீங்கள் மீண்டும் நிறுவ " +"வேண்டியிருந்தால், உங்கள் திட்டத்தை மற்றவர்களுடன் பகிர்ந்து கொள்ளும்போது அவற்றை மீண்டும் நிறுவ " +"வேண்டும் என்பதைக் கண்காணிக்க பயன்படுத்தப்படுகிறது. இதைப் போன்ற வெளியீட்டை நீங்கள் பெற வேண்டும் " +"(காட்டப்பட்டுள்ள சரியான பாதைகள் மாறுபடும் என்றாலும்):" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "நிறுவப்பட்ட தொகுப்புகளைப் பயன்படுத்துதல்" + +#: ../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 "" +"இப்போது கோரிக்கைகள் நிறுவப்பட்டுள்ளன, நீங்கள் ஒரு எளிய: கோப்பு: `main.py` கோப்பைப் " +"பயன்படுத்தலாம்:" + +#: ../source/tutorials/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "`` பைபென்வ் ரன்`` ஐப் பயன்படுத்தி இந்த ச்கிரிப்டை இயக்கலாம்:" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "இதைப் போன்ற வெளியீட்டை நீங்கள் பெற வேண்டும்:" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" +"`` பைபென்வ் ரன்`` ஐப் பயன்படுத்துவது உங்கள் நிறுவப்பட்ட தொகுப்புகள் உங்கள் ச்கிரிப்ட்டில் " +"கிடைப்பதை உறுதி செய்கிறது. `` பைபென்வ் செல்`` உடன் உங்கள் நிறுவப்பட்ட தொகுப்புகளுக்கு " +"அனைத்து கட்டளைகளும் அணுகுவதை உறுதி செய்யும் ஒரு புதிய செல்லை உருவாக்கவும் முடியும்." + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "அடுத்த படிகள்" + +#: ../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/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 "" +"உங்கள் சொந்த பைதான் தொகுப்புகளை உருவாக்கி விநியோகிப்பதில் நீங்கள் ஆர்வமாக இருந்தால், இதைக் " +"காண்க: குறிப்பு: `தொகுப்புகளை பேக்கேசிங் மற்றும் விநியோகித்தல் பற்றிய பயிற்சி " +"<விநியோகிக்கும் பேக்கேச்கள்>`." + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" +"உங்கள் பயன்பாட்டில் பைதான் மூல தொகுப்புகளின் வரையறைகளை உள்ளடக்கியிருக்கும் போது, அவை " +"(மற்றும் அவற்றின் சார்புகளை) `` பைபென்வ்`` சூழலில் `` பைபென்வ் நிறுவல் -இ <உறவினர்-பாதை-" +"க்கு-மூல-நேரடி> `` (எ.கா." + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "பயன்பாட்டு சார்பு நிர்வாகத்திற்கான பிற கருவிகள்" + +#: ../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/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 "" +"`அட்ச் ` _ திட்ட மேலாண்மை பணிப்பாய்வுகளில் இன்னும் " +"அதிகமான படிகளைப் பற்றிய கருத்துக்களுக்காக, பதிப்புகளை அதிகரித்தல் மற்றும் திட்ட " +"வார்ப்புருக்களிலிருந்து புதிய எலும்புக்கூடு திட்டங்களை உருவாக்குவது போன்றவை." + +#: ../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 "" +"`மைக்ரோபிபென்வ் ` _ `` தேவைகள். " +"Txt``, பைபன்வி மற்றும் பா பூட்டு கோப்புகளை ஆதரிக்கும் அல்லது அவற்றை பிப்-குழாய்களுக்கு " +"இணக்கமான வெளியீட்டிற்கு மாற்றும் பி.ஐ.பி. கொள்கலன் செய்யப்பட்ட பைதான் பயன்பாடுகளுக்காக " +"வடிவமைக்கப்பட்டுள்ளது, ஆனால் அவற்றுடன் மட்டுப்படுத்தப்படவில்லை." + +#: ../source/tutorials/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" +"`Pdm ` _ போன்ற தரங்களை நம்பியிருக்கும் நவீன " +"பைதான் தொகுப்பு நிர்வாகத்திற்கு: PEP: `517` மற்றும்: PEP:` 621`." + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" +"`கவிதை ` __ __ __ PIPENV உடன் " +"ஒப்பிடக்கூடிய ஒரு கருவிக்கு, நிர்வகிக்கப்படும் திட்டம் ஒரு செல்லுபடியாகும் `` " +"pyproject.tomll`` `கோப்புடன் விநியோகிக்கக்கூடிய பைதான் தொகுப்பாக கட்டமைக்கப்பட்ட " +"பயன்பாட்டு நிகழ்வுகளில் நேரடியாக கவனம் செலுத்துகிறது. இதற்கு நேர்மாறாக, பிபென்வ் " +"வெளிப்படையாக வேலை செய்யப்படும் பயன்பாடு விநியோக விநியோகத்தை `` பிப்`` நிறுவக்கூடிய " +"பைதான் தொகுப்பாக ஆதரிக்கும் என்ற அனுமானத்தை செய்வதைத் தவிர்க்கிறது." + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "பேக்கேசிங் பைதான் திட்டங்கள்" + +#: ../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 "" +"இந்த பயிற்சி ஒரு எளிய பைதான் திட்டத்தை எவ்வாறு தொகுத்தல் மூலம் உங்களை அழைத்துச் " +"செல்கிறது. தொகுப்பை உருவாக்க தேவையான கோப்புகள் மற்றும் கட்டமைப்பை எவ்வாறு சேர்ப்பது, " +"தொகுப்பை எவ்வாறு உருவாக்குவது, அதை பைதான் தொகுப்பு குறியீட்டில் (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 "" +"இந்த டுடோரியலில் கட்டளைகளை இயக்குவதில் உங்களுக்கு சிக்கல் இருந்தால், தயவுசெய்து " +"கட்டளையையும் அதன் வெளியீட்டையும் நகலெடுக்கவும், பின்னர் கிட்அப்பில் `பேக்கேசிங்-வெளியீடுகள்`_ " +"களஞ்சியத்தில்` ஒரு சிக்கலைத் திறக்கவும். உங்களுக்கு உதவ நாங்கள் எங்களால் முடிந்த அனைத்தையும் " +"செய்வோம்!" + +#: ../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:" +msgstr "" +"சில கட்டளைகளுக்கு புதிய பதிப்பு தேவைப்படுகிறது: குறிப்பு: `பிப்`, எனவே நீங்கள் அண்மைக் " +"கால பதிப்பை நிறுவியுள்ளதா என்பதை உறுதிப்படுத்துவதன் மூலம் தொடங்கவும்:" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "ஒரு எளிய திட்டம்" + +#: ../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 "" +"இந்த டுடோரியல் `` எடுத்துக்காட்டு_பேக்கேச்_யோர்_சர்ன்ம்_எர்`` என்ற எளிய திட்டத்தைப் " +"பயன்படுத்துகிறது. உங்கள் பயனர்பெயர் `` me`` என்றால், தொகுப்பு `` " +"example_package_me``; இந்த டுடோரியலைத் தொடர்ந்து மற்றவர்களால் பதிவேற்றப்பட்ட " +"தொகுப்புகளுடன் முரண்படாத ஒரு தனித்துவமான தொகுப்பு பெயர் உங்களிடம் இருப்பதை இது உறுதி " +"செய்கிறது. உங்கள் சொந்த திட்டத்தை பேக்கேசிங் செய்வதற்கு முன், இந்த திட்டத்தைப் பயன்படுத்த இந்த " +"டுடோரியலைப் பின்பற்ற பரிந்துரைக்கிறோம்." + +#: ../source/tutorials/packaging-projects.rst:44 +msgid "Create the following file structure locally:" +msgstr "உள்நாட்டில் பின்வரும் கோப்பு கட்டமைப்பை உருவாக்கவும்:" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" +"கோப்பை உருவாக்குதல்: கோப்பு: `__init __. பை` பரிந்துரைக்கப்படுகிறது, ஏனெனில் ஒரு: " +"கோப்பு:` __init __. [#பெயர்வெளி-தொகுப்புகள்] _" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" +": கோப்பு: உங்கள் தொகுப்பின் வழக்கு (செயல்பாடுகள், வகுப்புகள், மாறிலிகள் போன்றவை) " +"கொண்டிருக்கக்கூடிய தொகுப்புக்குள் உள்ள ஒரு தொகுதிக்கு `எடுத்துக்காட்டு. அந்த கோப்பைத் " +"திறந்து பின்வரும் உள்ளடக்கத்தை உள்ளிடவும்:" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" +"பைதான்: கால: `தொகுதிகள் <தொகுதி>` மற்றும்: கால: `இறக்குமதி தொகுப்புகள் <இறக்குமதி " +"தொகுப்பு> உடன் உங்களுக்கு அறிமுகமில்லாதவராக இருந்தால், தொகுப்புகள் மற்றும் தொகுதிகள்`_ " +"க்கான` பைதான் ஆவணங்களைப் படிக்க சில நிமிடங்கள் எடுத்துக் கொள்ளுங்கள்." + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "தொகுப்பு கோப்புகளை உருவாக்குதல்" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" +"விநியோகத்திற்காக திட்டத்தைத் தயாரிக்கப் பயன்படுத்தப்படும் கோப்புகளை இப்போது சேர்ப்பீர்கள். " +"நீங்கள் முடித்ததும், திட்ட அமைப்பு இப்படி இருக்கும்:" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "சோதனை கோப்பகத்தை உருவாக்குதல்" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" +": கோப்பு: `சோதனைகள்/` சோதனை கோப்புகளுக்கான ஒதுக்கிடமாகும். இப்போதைக்கு காலியாக " +"விடவும்." + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "ஒரு கட்டமைப்பைத் தேர்ந்தெடுப்பது" + +#: ../source/tutorials/packaging-projects.rst:113 +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 "" +"போன்ற கருவிகள்: குறிப்பு: `பிப்` மற்றும்: குறிப்பு:` பில்ட்` உண்மையில் உங்கள் மூலங்களை ஒரு " +"ஆக மாற்ற வேண்டாம்: கால: `விநியோக தொகுப்பு <விநியோக தொகுப்பு>` (ஒரு சக்கரம் போன்றது); " +"அந்த வேலை ஒரு: கால: `பின்தளத்தில் உருவாக்கு <பின்தளத்தில் உருவாக்கு>`. மேனிலை தரவு " +"(திட்டத்தைப் பற்றிய தகவல்கள், எடுத்துக்காட்டாக, PYPI இல் காட்டப்படும் பெயர் மற்றும் " +"குறிச்சொற்கள்) மற்றும் உள்ளீட்டு கோப்புகள் உள்ளிட்ட அதன் உள்ளமைவை உங்கள் திட்டம் எவ்வாறு " +"குறிப்பிடும் என்பதை பில்ட் பின்தளத்தில் தீர்மானிக்கிறது. கட்டியெழுப்பும் பின்தளத்தில் அவை " +"கட்டடத்தை ஆதரிக்கின்றனவா?" + +#: ../source/tutorials/packaging-projects.rst:122 +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 "" +"நீங்கள் பல பின்தளத்தில் இருந்து தேர்வு செய்யலாம்; இந்த டுடோரியல் பயன்பாடுகள்: ref: `அட்ச்லிங் " +"<அட்ச்>` இயல்பாகவே, ஆனால் அது ஒரே மாதிரியாக செயல்படும்: ref: `setuptools`,: Ref:` " +"Flit `,: Ref:` pdm `, மற்றும்` `[திட்டம்]` `மெட்டாடாட்டா:` " +"மெட்டாடாட்டா: `மெட்டாடா கட்டமைப்பு." + +#: ../source/tutorials/packaging-projects.rst:129 +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:134 +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." +msgstr "" +"தி: கோப்பு: `pyproject.toml` சொல்கிறது: சொல்:` பில்ட் ஃபிரான்டெண்ட் <பில்ட் " +"ஃபிரான்டெண்ட்> `போன்ற கருவிகள்: ref:` பிப்` மற்றும்: ref: `பில்ட்` உங்கள் திட்டத்திற்கு எந்த " +"பின்தளத்தில் பயன்படுத்த வேண்டும். பொதுவான கட்டமைப்பிற்கான சில எடுத்துக்காட்டுகள் கீழே உள்ளன, " +"ஆனால் மேலும் விவரங்களுக்கு உங்கள் பின்தளத்தில் சொந்த ஆவணங்களை சரிபார்க்கவும்." + +#: ../source/tutorials/packaging-projects.rst:141 +#, fuzzy +#| 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." +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" +"`` தேவை` `விசையானது உங்கள் தொகுப்பை உருவாக்க தேவையான தொகுப்புகளின் பட்டியல். தி: " +"கால: `ஃபிரான்டென்ட் <பில்ட் ஃபிரான்டென்ட்>` உங்கள் தொகுப்பை உருவாக்கும்போது அவற்றை தானாக " +"நிறுவ வேண்டும். முன்பக்கங்கள் வழக்கமாக தனிமைப்படுத்தப்பட்ட சூழல்களில் கட்டடங்களை " +"இயக்குகின்றன, எனவே இங்குள்ள சார்புகளைத் தவிர்ப்பது கட்டட நேர பிழைகளை ஏற்படுத்தக்கூடும். " +"இது எப்போதும் உங்கள் பின்தளத்தில் தொகுப்பைக் கொண்டிருக்க வேண்டும், மேலும் பிற உருவாக்க நேர " +"சார்புகள் இருக்கலாம்." + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" +"உருவாக்க கருவியின் கூடுதல் உள்ளமைவு `` pyproject.toml`` இன் `` கருவி` பிரிவில் " +"அல்லது உருவாக்க கருவியால் வரையறுக்கப்பட்ட சிறப்பு கோப்பில் இருக்கும். எடுத்துக்காட்டாக, `` " +"செடிப்டூல்ச்`` ஐ உங்கள் உருவாக்க பின்தளத்தில் பயன்படுத்தும் போது, கூடுதல் உள்ளமைவு ஒரு `` " +"setup.py`` அல்லது `` setup.cfg`` கோப்பில் சேர்க்கப்படலாம், மேலும் `` " +"setuptools.build_meta` ஐக் குறிப்பிடுவது உங்கள் கட்டமைப்பில் கருவிகளை தானாகவே " +"பயன்படுத்தவும் பயன்படுத்தவும் அனுமதிக்கிறது." + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "மெட்டாடேட்டாவை உள்ளமைத்தல்" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" +"திறந்த: கோப்பு: `pyproject.toml` மற்றும் பின்வரும் உள்ளடக்கத்தை உள்ளிடவும். உங்கள் " +"பயனர்பெயரைச் சேர்க்க `` பெயர்`` ஐ மாற்றவும்; இந்த டுடோரியலைத் தொடர்ந்து மற்றவர்களால் " +"பதிவேற்றப்பட்ட தொகுப்புகளுடன் முரண்படாத ஒரு தனித்துவமான தொகுப்பு பெயர் உங்களிடம் " +"இருப்பதை இது உறுதி செய்கிறது." + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" +"`` பெயர்`` என்பது உங்கள் தொகுப்பின் * விநியோக பெயர் *. கடிதங்கள், எண்கள், `` .``, `` " +"_``, மற்றும் `` -`` ஆகியவற்றைக் கொண்டிருக்கும் வரை இது எந்த பெயராகவும் இருக்கலாம். இது " +"ஏற்கனவே பைபி மீது எடுக்கப்படக்கூடாது. ** இந்த டுடோரியலுக்காக இதை உங்கள் பயனர்பெயருடன் " +"புதுப்பிக்க மறக்காதீர்கள், ஏனெனில் இது ஏற்கனவே இருக்கும் அதே பெயருடன் ஒரு தொகுப்பை " +"பதிவேற்ற முயற்சிக்காது என்பதை இது உறுதி செய்கிறது." + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" +"தொகுப்பின் ஆசிரியரை அடையாளம் காண `` ஆசிரியர்கள்`` பயன்படுத்தப்படுகிறது; ஒவ்வொரு " +"எழுத்தாளருக்கும் ஒரு பெயர் மற்றும் மின்னஞ்சலைக் குறிப்பிடுகிறீர்கள். அதே வடிவத்தில் `` " +"பராமரிப்பாளர்கள்` ஐ பட்டியலிடலாம்." + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "`` விளக்கம்`` என்பது தொகுப்பின் குறுகிய, ஒரு வாக்கிய சுருக்கமாகும்." + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" +"`` ரீட்மே`` என்பது தொகுப்பின் விரிவான விளக்கத்தைக் கொண்ட கோப்பிற்கான பாதை. இது PYPI இல் " +"உள்ள தொகுப்பு விவரம் பக்கத்தில் காட்டப்பட்டுள்ளது. இந்த வழக்கில், விளக்கம் ஏற்றப்பட்டது: " +"கோப்பு: `ReadMe.md` (இது ஒரு பொதுவான முறை). இதில் விவரிக்கப்பட்டுள்ள ஒரு மேம்பட்ட " +"அட்டவணை வடிவமும் உள்ளது: erf: `pyproject.toml வழிகாட்டி <எழுதுதல்-பைபிரெக்ட்-டாம்>`." + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" +"`` தேவை-பைதான் `your உங்கள் திட்டத்தால் ஆதரிக்கப்படும் பைதனின் பதிப்புகளைத் தருகிறது. " +"இது போன்ற ஒரு நிறுவி: ref: `பிப்` பொருந்தக்கூடிய பைதான் பதிப்பைக் கொண்ட ஒன்றைக் " +"கண்டுபிடிக்கும் வரை பழைய பதிப்புகளின் மூலம் திரும்பிப் பார்க்கும்." + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on and which operating systems your package " +"will work on. For a complete list of classifiers, see https://pypi.org/" +"classifiers/." +msgstr "" +"`` வகைப்படுத்திகள்`` குறியீட்டைக் கொடுக்கும்: குறிப்பு: `பிப்` உங்கள் தொகுப்பைப் பற்றி சில " +"கூடுதல் மேனிலை தரவு. இந்த வழக்கில், தொகுப்பு பைதான் 3 உடன் மட்டுமே இணக்கமானது மற்றும் " +"OS- சுயாதீனமானது. பைதனின் எந்த பதிப்பு (கள்) உங்கள் தொகுப்பு செயல்படுகிறது, எந்த இயக்க " +"முறைமைகள் உங்கள் தொகுப்பு செயல்படும் என்பதை நீங்கள் எப்போதும் சேர்க்க வேண்டும். " +"வகைப்படுத்திகளின் முழுமையான பட்டியலுக்கு, https://pypi.org/classifiers/ ஐப் " +"பார்க்கவும்." + +#: ../source/tutorials/packaging-projects.rst:222 +#, fuzzy +#| msgid "" +#| "This is a valid :term:`SPDX license expression ` " +#| "consisting of one or more :term:`license identifiers `. The full license list is available at the `SPDX license " +#| "list page `_. The supported list version is 3.17 or any " +#| "later compatible one." +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" +"இது செல்லுபடியாகும்: சொல்: `SPDX உரிம வெளிப்பாடு <உரிம வெளிப்பாடு>` ஒன்று அல்லது " +"அதற்கு மேற்பட்டவற்றைக் கொண்டது: கால: `உரிம அடையாளங்காட்டிகள் <உரிம அடையாளங்காட்டி>`. " +"முழு உரிம பட்டியல் `SPDX உரிம பட்டியல் பக்கத்தில் ` _ இல் " +"கிடைக்கிறது. ஆதரிக்கப்பட்ட பட்டியல் பதிப்பு 3.17 அல்லது பின்னர் இணக்கமான ஒன்றாகும்." + +#: ../source/tutorials/packaging-projects.rst:224 +#, fuzzy +#| msgid "" +#| "Now run this command from the same directory where :file:`pyproject.toml` " +#| "is located:" +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" +"இப்போது இந்த கட்டளையை அதே கோப்பகத்திலிருந்து இயக்கவும்: கோப்பு: `pyproject.toml` " +"அமைந்துள்ளது:" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" +"`` urls`` PYPI இல் காண்பிக்க கூடுதல் கூடுதல் இணைப்புகளை பட்டியலிட அனுமதிக்கிறது. " +"பொதுவாக இது மூல, ஆவணங்கள், வெளியீட்டு டிராக்கர்கள் போன்றவற்றுக்கு இருக்கலாம்." + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" +"`` [திட்டம்] `` அட்டவணையில் வரையறுக்கக்கூடிய இந்த மற்றும் பிற துறைகள் பற்றிய " +"விவரங்களுக்கு `pyproject.toml வழிகாட்டி <எழுதுதல்-பைபிரோசெக்ட்-டோம்>` ஐக் காண்க. " +"கண்டுபிடிப்புத்தன்மையை மேம்படுத்துவதற்கான பிற பொதுவான புலங்கள் `` முக்கிய வார்த்தைகள்` " +"மற்றும் உங்கள் தொகுப்பை நிறுவ தேவையான `` சார்புகள்`." + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "README.MD ஐ உருவாக்குதல்" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" +"திறந்த: கோப்பு: `ReadMe.md` மற்றும் பின்வரும் உள்ளடக்கத்தை உள்ளிடவும். நீங்கள் விரும்பினால் " +"இதைத் தனிப்பயனாக்கலாம்." + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "உரிமத்தை உருவாக்குதல்" + +#: ../source/tutorials/packaging-projects.rst:253 +#, fuzzy +#| 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:" +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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 "" +"பைதான் தொகுப்பு குறியீட்டில் பதிவேற்றப்பட்ட ஒவ்வொரு தொகுப்புக்கும் உரிமம் சேர்க்க வேண்டியது " +"தேவை. உங்கள் தொகுப்பைப் பயன்படுத்தக்கூடிய விதிமுறைகளை உங்கள் தொகுப்பை நிறுவும் " +"பயனர்களிடம் இது சொல்கிறது. உரிமத்தை எடுக்க உதவ, https://choosealicense.com/ ஐப் " +"பார்க்கவும். நீங்கள் உரிமத்தைத் தேர்ந்தெடுத்ததும், திறந்து: கோப்பு: `உரிமம்` மற்றும் உரிம " +"உரையை உள்ளிடவும். எடுத்துக்காட்டாக, நீங்கள் எம்ஐடி உரிமத்தைத் தேர்ந்தெடுத்திருந்தால்:" + +#: ../source/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" +"பெரும்பாலானவை பின்தளத்தில் தானாகவே தொகுப்புகளில் உரிமக் கோப்புகளை உள்ளடக்குகின்றன. " +"மேலும் விவரங்களுக்கு உங்கள் பின்தளத்தில் ஆவணங்களைப் பார்க்கவும். உரிமம் பெறுவதற்கான பாதையை " +"`` உரிமம்-கோப்புகள்` `விசையில் சேர்த்தால்: கோப்பு:` pyproject.toml`, மற்றும் உங்கள் " +"உருவாக்க பின்தளத்தில் ஆதரவளிக்கிறது: PEP: `639`, கோப்பு தானாகவே தொகுப்பில் " +"சேர்க்கப்படும்." + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "பிற கோப்புகள் உட்பட" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" +"மேலே பட்டியலிடப்பட்டுள்ள கோப்புகள் தானாகவே உங்கள்: கால: `மூல வழங்கல் <மூல வழங்கல் " +"(அல்லது\" SDIST \")>` இல் சேர்க்கப்படும். கூடுதல் கோப்புகளை நீங்கள் சேர்க்க விரும்பினால், " +"உங்கள் உருவாக்க பின்தளத்தில் ஆவணங்களைப் பார்க்கவும்." + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "விநியோக காப்பகங்களை உருவாக்குதல்" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" +"அடுத்த கட்டம் உருவாக்குவது: கால: `விநியோக தொகுப்புகள் <விநியோக தொகுப்பு>` " +"தொகுப்புக்கு. இவை பைதான் தொகுப்பு குறியீட்டில் பதிவேற்றப்படும் காப்பகங்கள் மற்றும் " +"நிறுவலாம்: ref: `பிப்`." + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" +"பைபாவின் அண்மைக் கால பதிப்பு உங்களிடம் இருப்பதை உறுதிப்படுத்திக் கொள்ளுங்கள்: குறிப்பு: " +"`பில்ட்` நிறுவப்பட்டுள்ளது:" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" +"இவற்றை நிறுவுவதில் சிக்கல் இருந்தால், இதைக் காண்க: டாக்: `நிறுவுதல்-பேக்கேச்கள்` டுடோரியல்." + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" +"இப்போது இந்த கட்டளையை அதே கோப்பகத்திலிருந்து இயக்கவும்: கோப்பு: `pyproject.toml` " +"அமைந்துள்ளது:" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" +"இந்த கட்டளை நிறைய உரையை வெளியிட வேண்டும் மற்றும் முடிந்ததும் இரண்டு கோப்புகளை உருவாக்க " +"வேண்டும்: கோப்பு: `Dist` அடைவு:" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" +"`` Tar.gz`` கோப்பு என்பது ஒரு: கால: `மூல வழங்கல் <மூல வழங்கல் (அல்லது\" SDIST \")>` " +"அதேசமயம் `` .Whl`` கோப்பு ஒரு: கால: `கட்டப்பட்ட வழங்கல் <கட்டமைக்கப்பட்ட விநியோகம்>`. " +"புதியது: ref: `பிப்` பதிப்புகள் முன்னுரிமையாக கட்டமைக்கப்பட்ட விநியோகங்களை " +"நிறுவுகின்றன, ஆனால் தேவைப்பட்டால் மூல விநியோகங்களுக்கு மீண்டும் வரும். நீங்கள் எப்போதும் ஒரு " +"மூல விநியோகத்தை பதிவேற்ற வேண்டும் மற்றும் உங்கள் திட்டம் இணக்கமான தளங்களுக்கு கட்டப்பட்ட " +"விநியோகங்களை வழங்க வேண்டும். இந்த வழக்கில், எங்கள் எடுத்துக்காட்டு தொகுப்பு எந்தவொரு " +"தளத்திலும் பைத்தானுடன் இணக்கமானது, எனவே கட்டப்பட்ட ஒரு வழங்கல் மட்டுமே தேவைப்படுகிறது." + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "விநியோக காப்பகங்களைப் பதிவேற்றுதல்" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" +"இறுதியாக, உங்கள் தொகுப்பை பைதான் தொகுப்பு குறியீட்டில் பதிவேற்ற வேண்டிய நேரம் இது!" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" +"நீங்கள் செய்ய வேண்டிய முதல் சேதி, டெச்ட்பைட்டில் ஒரு கணக்கைப் பதிவுசெய்வதுதான், இது சோதனை " +"மற்றும் பரிசோதனைக்கு நோக்கம் கொண்ட தொகுப்பு குறியீட்டின் தனி நிகழ்வு ஆகும். இந்த டுடோரியல் " +"போன்ற விசயங்களுக்கு இது சிறந்தது, அங்கு நாம் உண்மையான குறியீட்டில் பதிவேற்ற " +"விரும்பவில்லை. கணக்கைப் பதிவுசெய்ய, https://test.pypi.org/account/register/ க்குச் " +"சென்று அந்தப் பக்கத்தில் உள்ள படிகளை முடிக்கவும். நீங்கள் எந்த தொகுப்புகளையும் " +"பதிவேற்றுவதற்கு முன்பு உங்கள் மின்னஞ்சல் முகவரியை சரிபார்க்க வேண்டும். மேலும் " +"விவரங்களுக்கு, காண்க: DOC: `/வழிகாட்டிகள்/பயன்படுத்துதல்-டெச்ட்பைப்பைப் பயன்படுத்துதல்`." + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" +"உங்கள் திட்டத்தை பாதுகாப்பாக பதிவேற்ற, உங்களுக்கு ஒரு பைபி `ஏபிஐ டோக்கன்`_ தேவை. " +"Https://test.pypi.org/manage/account/#api-tokens இல் ஒன்றை உருவாக்கவும், " +"\"நோக்கம்\" ஐ \"முழு கணக்கு\" ஆகவும் அமைக்கவும். ** நீங்கள் கிள்ளாக்கை நகலெடுத்து " +"சேமிக்கும் வரை பக்கத்தை மூட வேண்டாம் - அந்த கிள்ளாக்கை நீங்கள் மீண்டும் பார்க்க மாட்டீர்கள். **" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" +"இப்போது நீங்கள் பதிவுசெய்துள்ளீர்கள், நீங்கள் பயன்படுத்தலாம்: Ref: `ட்வைன்` விநியோக " +"தொகுப்புகளை பதிவேற்ற. நீங்கள் கயிறு நிறுவ வேண்டும்:" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "நிறுவப்பட்டதும், காப்பகங்கள் அனைத்தையும் பதிவேற்ற கயிறு இயக்கவும்: கோப்பு: `DIST`:" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" +"பநிஇ டோக்கனுக்கு நீங்கள் கேட்கப்படுவீர்கள். `` பைபி-`` முன்னொட்டு உட்பட கிள்ளாக்கு மதிப்பைப் " +"பயன்படுத்தவும். உள்ளீடு மறைக்கப்படும் என்பதை நினைவில் கொள்க, எனவே சரியாக ஒட்டவும்." + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "கட்டளை முடிந்ததும், இதைப் போன்ற வெளியீட்டை நீங்கள் காண வேண்டும்:" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" +"பதிவேற்றியதும், உங்கள் தொகுப்பு டெச்ட்பைப்பில் பார்க்கப்பட வேண்டும்; எடுத்துக்காட்டாக: `` " +"https: // test.pypi.org/project/example_package_your_username_here``." + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "புதிதாக பதிவேற்றிய உங்கள் தொகுப்பை நிறுவுதல்" + +#: ../source/tutorials/packaging-projects.rst:424 +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: `பிப்` உங்கள் தொகுப்பை நிறுவவும், அது செயல்படுகிறதா என்பதை " +"சரிபார்க்கவும். ஒரு: ref: `மெய்நிகர் சூழல் <மெய்நிகர் சூழல்களை உருவாக்குதல் மற்றும் " +"பயன்படுத்துதல்>` மற்றும் டெச்ட்பைட்டிலிருந்து உங்கள் தொகுப்பை நிறுவவும்:" + +#: ../source/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "உங்கள் பயனர்பெயரை தொகுப்பு பெயரில் குறிப்பிடுவதை உறுதிசெய்க!" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" +"PIP டெச்ட்பைட்டிலிருந்து தொகுப்பை நிறுவ வேண்டும், வெளியீடு இதுபோன்றதாக இருக்க வேண்டும்:" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" +"இந்த எடுத்துக்காட்டு நேரடி பைபிக்கு பதிலாக டெச்ட்பை குறிப்பிட `` --index-url`` " +"கொடியைப் பயன்படுத்துகிறது. கூடுதலாக, இது `` --no-deps`` ஐக் குறிப்பிடுகிறது. " +"டெச்ட்பிபிக்கு லைவ் பைபியின் அதே தொகுப்புகள் இல்லை என்பதால், சார்புகளை நிறுவ முயற்சிப்பது " +"தோல்வியடையக்கூடும் அல்லது எதிர்பாராத ஒன்றை நிறுவக்கூடும். எங்கள் எடுத்துக்காட்டு " +"தொகுப்புக்கு எந்தவிதமான சார்புநிலைகளும் இல்லை என்றாலும், டெச்ட்பைப்பைப் பயன்படுத்தும் போது " +"சார்புகளை நிறுவுவதைத் தவிர்ப்பது ஒரு நல்ல நடைமுறை." + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" +"தொகுப்பை இறக்குமதி செய்வதன் மூலம் அது சரியாக நிறுவப்பட்டது என்பதை நீங்கள் சோதிக்கலாம். " +"நீங்கள் இன்னும் உங்கள் மெய்நிகர் சூழலில் இருக்கிறீர்கள் என்பதை உறுதிப்படுத்திக் கொள்ளுங்கள், " +"பின்னர் பைத்தானை இயக்கவும்:" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "மற்றும் தொகுப்பை இறக்குமதி செய்யுங்கள்:" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" +"** வாழ்த்துக்கள், நீங்கள் ஒரு பைதான் திட்டத்தை தொகுத்து விநியோகித்திருக்கிறீர்கள்! ** ✨ ✨" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" +"பைபியை சோதிக்க உங்கள் தொகுப்பை எவ்வாறு பதிவேற்றுவது என்பதை இந்த பயிற்சி உங்களுக்குக் " +"காட்டியது என்பதை நினைவில் கொள்ளுங்கள், இது நிரந்தர சேமிப்பு அல்ல. சோதனை அமைப்பு " +"எப்போதாவது தொகுப்புகள் மற்றும் கணக்குகளை நீக்குகிறது. இந்த டுடோரியல் போன்ற சோதனை மற்றும் " +"சோதனைகளுக்கு டெச்ட்பிபியைப் பயன்படுத்துவது சிறந்தது." + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" +"பைதான் தொகுப்பு குறியீட்டில் ஒரு உண்மையான தொகுப்பை பதிவேற்ற நீங்கள் தயாராக இருக்கும்போது, " +"இந்த டுடோரியலில் நீங்கள் செய்ததைப் போலவே நீங்கள் செய்ய முடியும், ஆனால் இந்த முக்கியமான " +"வேறுபாடுகளுடன்:" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" +"உங்கள் தொகுப்புக்கு மறக்கமுடியாத மற்றும் தனித்துவமான பெயரைத் தேர்வுசெய்க. டுடோரியலில் " +"நீங்கள் செய்ததைப் போல உங்கள் பயனர்பெயரை நீங்கள் சேர்க்க வேண்டியதில்லை, ஆனால் நீங்கள் ஏற்கனவே உள்ள " +"பெயரைப் பயன்படுத்த முடியாது." + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" +"ஒரு கணக்கை https://pypi.org இல் பதிவுசெய்க - இவை இரண்டு தனித்தனி சேவையகங்கள் மற்றும் " +"சோதனை சேவையகத்திலிருந்து உள்நுழைவு விவரங்கள் முதன்மையான சேவையகத்துடன் பகிரப்படவில்லை " +"என்பதை நினைவில் கொள்க." + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" +"உங்கள் தொகுப்பைப் பதிவேற்றவும் `` `ட்வைன் பதிவேற்றவும் DIST/*` `பயன்படுத்தவும் மற்றும் " +"உண்மையான PYPI இல் நீங்கள் பதிவுசெய்த கணக்கிற்கான உங்கள் சான்றுகளை உள்ளிடவும். இப்போது நீங்கள் " +"தயாரிப்பில் தொகுப்பை பதிவேற்றுகிறீர்கள், நீங்கள் `` --repository`` ஐ குறிப்பிட " +"தேவையில்லை; தொகுப்பு முன்னிருப்பாக https://pypi.org/ இல் பதிவேற்றும்." + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" +"`` பைதான் 3 -எம் பிஐபி நிறுவுதல் [உங்கள் தொகுப்பாக] `` ஆகியவற்றைப் பயன்படுத்தி உண்மையான " +"பைபியிலிருந்து உங்கள் தொகுப்பை நிறுவவும்." + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" +"இந்த கட்டத்தில் பைதான் நூலகங்களை பேக்கேசிங் பற்றி மேலும் படிக்க விரும்பினால் இங்கே நீங்கள் " +"செய்யக்கூடிய சில விசயங்கள் உள்ளன:" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" +"நீங்கள் தேர்ந்தெடுக்கப்பட்ட கட்டமைப்பிற்கான மேம்பட்ட உள்ளமைவைப் பற்றி படியுங்கள்: `அட்ச்லிங் " +"<அட்ச்லிங்-கான்ஃபிக்_>` _,: டாக்: `செட்டப்டூல்ச் <செட்டுப்டூல்ச்: யூசர்சூட்/" +"பைபிரோசெக்ட்_கான்ஃபிக்>`,: டாக்: `ஃபிளிட் <ஃப்ளிட்: பி.டி.எம்." + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" +"மேலும் மேம்பட்ட நடைமுறை தகவல்களுக்காக இந்த தளத்தில் `வழிகாட்டிகள் ` ஐப் பாருங்கள்: குறிப்பிட்ட தலைப்புகளில் விளக்கங்கள் மற்றும் பின்னணிக்கு: டாக்: " +"`விவாதங்கள் `." + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" +"திட்ட மேலாண்மை மற்றும் பேக்கேசிங்கிற்கான ஒற்றை கட்டளை-வரி இடைமுகத்தை வழங்கும் பேக்கேசிங் " +"கருவிகளைக் கவனியுங்கள், அதாவது: ref: `அட்ச்`,: ref:` ஃபிளிட்`,: ref: `PDM`, மற்றும்: " +"ref:` கவிதை`." + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "குறிப்புகள்" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" +"தொழில்நுட்ப ரீதியாக, நீங்கள் ஒரு `` __init __. Py`` கோப்பு இல்லாமல் பைதான் " +"தொகுப்புகளையும் உருவாக்கலாம், ஆனால் அவை அழைக்கப்படுகின்றன: DOC: `பெயர்வெளி தொகுப்புகள் " +"` மற்றும் ** மேம்பட்ட தலைப்பாக " +"கருதப்படுகிறது ** (இந்த டூட்டோரியலில் மறைக்கப்படவில்லை). நீங்கள் பைதான் பேக்கேசிங் மூலம் " +"மட்டுமே தொடங்கினால், * வழக்கமான தொகுப்புகள் * மற்றும் `__init __. பை`` (கோப்பு " +"காலியாக இருந்தாலும் கூட) ஒட்டிக்கொள்ள பரிந்துரைக்கப்படுகிறது." + +#~ msgid "" +#~ "This specification was originally defined in :pep:`518` and :pep:`621`." +#~ msgstr "" +#~ "இந்த விவரக்குறிப்பு முதலில் வரையறுக்கப்பட்டது: PEP: `518` மற்றும்: PEP:` 621`." + +#~ msgid "" +#~ "Refer to the `pkg_resources documentation `__ for more details." +#~ msgstr "" +#~ "மேலும் விவரங்களுக்கு `pkg_resources ஆவணங்கள் `_" +#~ msgstr "`Vagrant ` _" + +#, fuzzy +#~| msgid ":ref:`pyproject-toml-spec`" +#~ msgid "**Inspiration**: :ref:` pyproject-tool-table`" +#~ msgstr ": ref: `pyproject-toml-spec`" + +#~ 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." +#~ msgstr "" +#~ "ரூட் முகவரி க்கு கீழே ஒரு களஞ்சியத்தில் உள்ள ஒவ்வொரு தனிப்பட்ட திட்டத்திற்கும் மற்றொரு " +#~ "முகவரி உள்ளது. இந்த முகவரி இன் வடிவம் ``//`` ஆகும், அங்கு `` <திட்டம்> `` " +#~ "அந்த திட்டத்திற்கான இயல்பாக்கப்பட்ட பெயரால் மாற்றப்படுகிறது, எனவே \"ஓலி கிரெயில்\" " +#~ "என்ற திட்டத்திற்கு ``/ஓலிங்ரெயில்/`` போன்ற முகவரி இருக்கும். இந்த முகவரி " +#~ "திட்டத்திற்கான கோப்புக்கு ஒற்றை நங்கூர உறுப்புடன் செல்லுபடியாகும் HTML5 பக்கத்துடன் " +#~ "பதிலளிக்க வேண்டும். HREF பண்புக்கூறு ** பதிவிறக்கம் செய்வதற்கான கோப்பின் " +#~ "இருப்பிடத்துடன் இணைக்கும் முகவரி ஆக இருக்க வேண்டும், மேலும் நங்கூரம் குறிச்சொல்லின் உரை " +#~ "** ** முகவரி இன் இறுதி பாதை கூறுகளை (கோப்பு பெயர்) பொருத்த வேண்டும். முகவரி ** " +#~ "** பின்வரும் தொடரியல் கொண்ட ஒரு முகவரி துண்டு வடிவத்தில் ஒரு ஆசை சேர்க்க வேண்டும்: " +#~ "``# = ``, அங்கு `` `` என்பது ஆச் செயல்பாட்டின் " +#~ "சிறிய பெயர் (`` சா 256` `` `` `` `` `` `` `` `` `." + +#~ msgid "Adding \"Yank\" Support to the Simple API" +#~ msgstr "எளிய பநிஇ க்கு \"யாங்க்\" ஆதரவைச் சேர்ப்பது" + +#~ msgid "Signing the distribution packages" +#~ msgstr "விநியோக தொகுப்புகளில் கையொப்பமிடுதல்" + +#~ msgid "" +#~ "The following job signs the distribution packages with `Sigstore`_, the " +#~ "same artifact signing system `used to sign CPython `_." +#~ msgstr "" +#~ "பின்வரும் வேலை விநியோக தொகுப்புகளை `சிக்ச்டோர்`_ உடன் கையொப்பமிடுகிறது, அதே " +#~ "கலைப்பொருள் கையொப்பமிடும் அமைப்பு` cpython `_ இல் கையொப்பமிடப் பயன்படுகிறது." + +#~ 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 "" +#~ "முதலாவதாக, விநியோக தொகுப்புகளில் கையெழுத்திட இது `சிக்ச்டோர்/சிஎச்-ஆக்சன்-சிக்ச்டோர்-" +#~ "பைதான் அறிவிலிமையம் அதிரடி`_ ஐப் பயன்படுத்துகிறது. அடுத்த கட்டத்தில், தற்போதைய " +#~ "குறிச்சொல்லிலிருந்து வெற்று அறிவிலிமையம் வெளியீடு `` gh`` Cli ஐப் பயன்படுத்தி " +#~ "உருவாக்கப்படுகிறது. இந்த படி மேலும் தனிப்பயனாக்கப்படலாம் என்பதை நினைவில் கொள்க. " +#~ "`சிஎச் வெளியீட்டு ஆவணங்கள் _ _ ஒரு " +#~ "குறிப்பாகப் பார்க்கவும்." + +#~ 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." +#~ msgstr "" +#~ "அறிவிலிமையம் வெளியீட்டை உருவாக்க உங்கள் `` github_token`` அனுமதிகளை நிர்வகிக்க " +#~ "வேண்டியிருக்கலாம். `கிட்அப் ஆவணங்கள் `_ அறிவுறுத்தல்களுக்கு. குறிப்பாக, " +#~ "டோக்கனுக்கு `` உள்ளடக்கங்கள்: எழுது `அனுமதி தேவை." + +#~ msgid "" +#~ "Finally, the signed distributions are uploaded to the GitHub Release." +#~ msgstr "" +#~ "இறுதியாக, கையொப்பமிடப்பட்ட விநியோகங்கள் அறிவிலிமையம் வெளியீட்டில் பதிவேற்றப்படுகின்றன." + +#~ 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." +#~ msgstr "" +#~ "இது சிபிசி கையொப்பங்களுக்கு மாற்றாக உள்ளது, இதற்காக பைபி `_ இலிருந்து உதவி அகற்றப்பட்டுள்ளது. " +#~ "இருப்பினும், இந்த வேலை PYPI இல் பதிவேற்றுவதற்கு கட்டாயமில்லை, மேலும் தவிர்க்கப்படலாம்." + +#~ msgid "" +#~ "Text string that is a valid SPDX `license expression `__ as `defined in PEP " +#~ "639 `__." +#~ msgstr "" +#~ "செல்லுபடியாகும் SPDX `உரிம வெளிப்பாடு __ __ PEP 639 ____." + +#~ msgid "The table subkeys of the ``license`` key are deprecated." +#~ msgstr "`` உரிமம்`` விசையின் அட்டவணை துணைக் கீல்கள் நீக்கப்படுகின்றன." diff --git a/locales/th/LC_MESSAGES/messages.po b/locales/th/LC_MESSAGES/messages.po new file mode 100644 index 000000000..f1f5aab88 --- /dev/null +++ b/locales/th/LC_MESSAGES/messages.po @@ -0,0 +1,26789 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# toidev , 2025. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: Automatically generated\n" +"Language-Team: none\n" +"Language: th\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "" + +#: ../source/contribute.rst:14 +msgid "Translating the guide" +msgstr "" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "" + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "" + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "" + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "" + +#: ../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 +msgid "What is a source distribution?" +msgstr "" + +#: ../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 +msgid "What about eggs?" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python setup.py install``" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python -m pip install --editable .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:104 +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr "" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +msgid "Complete" +msgstr "" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +msgid "Versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +msgid "Calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +msgid "Other schemes" +msgstr "" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 ../source/flow.rst:143 +msgid "" +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../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 :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +msgid "Installed Project" +msgstr "" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +msgid "Project Root Directory" +msgstr "" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "" + +#: ../source/glossary.rst:257 +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:260 +msgid "Pyproject Metadata" +msgstr "" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +msgid "Pyproject Metadata Key" +msgstr "" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "" + +#: ../source/glossary.rst:344 +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:348 +msgid "Root License Directory" +msgstr "" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +msgid "Wheel Project" +msgstr "" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "" +"https://files.pythonhosted.org/packages/eb/" +"45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" +"sampleproject-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "" +"https://files.pythonhosted.org/packages/56/0a/" +"178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" +"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +msgid "" +"https://files.pythonhosted.org/packages/" +"63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" +"sampleproject_nomura-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +msgid "Creating the package" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +msgid "``pyproject.toml``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +msgid "Installing the package with ``pipx``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +msgid "Conclusion" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +msgid "1. Install twine" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +msgid "Dropping a Python version" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:108 +msgid "openSUSE" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:118 +msgid "Debian/Ubuntu and derivatives" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +msgid "Install packages in a virtual environment using pip and venv" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +msgid "Install packages using pip" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +msgid "Install extras" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +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/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python -m build``" +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:126 +msgid "``python -m build --no-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:127 +msgid "``python -m pip install --no-build-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../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 "" +"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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +msgid "Installation" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:233 +msgid "``appveyor-sample/build.cmd``" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:5 +msgid "Tool recommendations" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +msgid "Installing packages" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +msgid "Building distributions" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:313 +msgid "setuptools" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:317 +msgid "uv-build" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +msgid "`Kivy `_" +msgstr "" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "Subdirectory name" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +msgid "``licenses``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*object*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Schema version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "examples" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "version\\_info" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*number*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**implementation**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**flags**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**headers**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +msgid "Package Building" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +msgid ":ref:`Version `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +msgid "``toml``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +msgid "``dependency_groups``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +msgid "Installers" +msgstr "" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +msgid "Reference implementation in Python" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +msgid "Names and normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +msgid "Name normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +msgid "Project Status Markers" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +msgid "Installer semantics: none." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +msgid "Installer semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +msgid "``deprecated``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +msgid "``pylock.toml`` Specification" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +msgid "``lock-version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +msgid "**Required?**: yes" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +msgid "``environments``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +msgid "``dependency-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +msgid "``[[packages]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +msgid "``packages.version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +msgid "The version of the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +msgid "``[[packages.dependencies]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +msgid "The time the file was uploaded." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +msgid "``packages.index``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +msgid "``import-names``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +msgid "Legacy specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +msgid "Examples:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +msgid "Example:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +msgid "PyPA schemas" +msgstr "" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +msgid "Python Description Formats" +msgstr "" + +#: ../source/specifications/section-reproducible-environments.rst:3 +msgid "Reproducible Environments" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +msgid "Normalized Names" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +msgid "HTML Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +msgid "Project List" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +msgid "Project Detail" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +msgid "JSON Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +msgid "Content-Types" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +msgid "Version + Format Selection" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +msgid "Definitions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +msgid "Version scheme" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +msgid "Pre-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +msgid "Version epochs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +msgid "Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +msgid "Integer Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +msgid "Version exclusion" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +msgid "Well-known Project URLs in Metadata" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +msgid "Label normalization" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +msgid "Normalized" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"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/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "" + +#: ../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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "" + +#: ../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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" diff --git a/locales/tr/LC_MESSAGES/messages.po b/locales/tr/LC_MESSAGES/messages.po new file mode 100644 index 000000000..abef18066 --- /dev/null +++ b/locales/tr/LC_MESSAGES/messages.po @@ -0,0 +1,26816 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# Emr , 2024. +# Rüzgar Hünerel , 2025. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: 2025-09-29 04:02+0000\n" +"Last-Translator: Rüzgar Hünerel \n" +"Language-Team: Turkish \n" +"Language: tr\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=2; plural=n != 1;\n" +"X-Generator: Weblate 5.14-dev\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "Bu rehbere katkıda bulun" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "" +"|PyPUG| katkıda bulunanları memnuniyetle karşılar! Yardımcı olabileceğiniz " +"birçok yol vardır, bunlardan bazıları şunlardır:" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "Kılavuzu okumak ve geri bildirimde bulunmak" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "Yeni katkıları inceleme" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "Mevcut içeriğin revize edilmesi" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "Yeni içerik yazılması" + +#: ../source/contribute.rst:14 +msgid "Translating the guide" +msgstr "Kılavuzu çevirmek" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" +"|PyPUG| ile ilgili çalışmaların çoğu projenin GitHub deposunda " +"gerçekleştirilmektedir. Başlamak için, açık sorunlar ve open issues\"a göz " +"atın. Kılavuzu yazmayı veya düzenlemeyi planlıyorsanız, lütfen :ref:`style " +"guide ` okuyun." + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" +"|PyPUG|‘a katkıda bulunurken, PSF’nin Code of Conduct__’una uymanız beklenir." + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "Belgelendirme türleri" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" +"Bu proje, belirli amaçlara sahip dört farklı belgelendirme türünden oluşur. " +"Proje, kaliteli belgeler oluşturmak için Diátaxis process_’i takip etmeyi " +"amaçlamaktadır. Projeye yeni eklemeler önerirken lütfen uygun belgelendirme " +"türünü seçin." + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "Eğitimler" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" +"“Öğreticiler, okuyucuya yeni kavramları bir hedefe ulaşarak öğretmeye " +"odaklanır. Bunlar, görüş bildiren adım adım kılavuzlardır. Gereksiz uyarılar " +"veya bilgiler içermezler. example tutorial-style document_.”" + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "Kılavuzlar" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" +"Kılavuzlar, belirli bir görevi yerine getirmeye odaklanır ve belli bir ön " +"bilgi düzeyini varsayabilir. Bunlar öğreticilere benzer, ancak dar ve net " +"bir odakları vardır ve gerektiğinde birçok uyarı ve ek bilgi " +"sağlayabilirler. Görevi yerine getirmek için birden fazla yaklaşımı da " +"tartışabilirler. :doc:example guide-style document ." + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "Tartışmalar" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" +"Tartışmalar, anlamaya ve bilgiye odaklanır. Bunlar, belirli bir hedef " +"olmadan belirli bir konuyu inceler. example discussion-style document " +"." + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "Özellikler" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "" + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "" + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "" + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "" + +#: ../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 +msgid "What is a source distribution?" +msgstr "" + +#: ../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 +msgid "What about eggs?" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python setup.py install``" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python -m pip install --editable .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:104 +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr "" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +msgid "Complete" +msgstr "" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +msgid "Versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +msgid "Calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +msgid "Other schemes" +msgstr "" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 ../source/flow.rst:143 +msgid "" +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../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 :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +msgid "Installed Project" +msgstr "" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +msgid "Project Root Directory" +msgstr "" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "" + +#: ../source/glossary.rst:257 +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:260 +msgid "Pyproject Metadata" +msgstr "" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +msgid "Pyproject Metadata Key" +msgstr "" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "" + +#: ../source/glossary.rst:344 +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:348 +msgid "Root License Directory" +msgstr "" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +msgid "Wheel Project" +msgstr "" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "" +"https://files.pythonhosted.org/packages/eb/" +"45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" +"sampleproject-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "" +"https://files.pythonhosted.org/packages/56/0a/" +"178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" +"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +msgid "" +"https://files.pythonhosted.org/packages/" +"63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" +"sampleproject_nomura-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +msgid "Creating the package" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +msgid "``pyproject.toml``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +msgid "Installing the package with ``pipx``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +msgid "Conclusion" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +msgid "1. Install twine" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +msgid "Dropping a Python version" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:108 +msgid "openSUSE" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:118 +msgid "Debian/Ubuntu and derivatives" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +msgid "Install packages in a virtual environment using pip and venv" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +msgid "Install packages using pip" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +msgid "Install extras" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +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/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python -m build``" +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:126 +msgid "``python -m build --no-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:127 +msgid "``python -m pip install --no-build-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../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 "" +"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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +msgid "Installation" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:233 +msgid "``appveyor-sample/build.cmd``" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:5 +msgid "Tool recommendations" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +msgid "Installing packages" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +msgid "Building distributions" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:313 +msgid "setuptools" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:317 +msgid "uv-build" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +msgid "`Kivy `_" +msgstr "" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "Subdirectory name" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +msgid "``licenses``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*object*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Schema version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "examples" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "version\\_info" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*number*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**implementation**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**flags**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**headers**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +msgid "Package Building" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +msgid ":ref:`Version `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +msgid "``toml``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +msgid "``dependency_groups``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +msgid "Installers" +msgstr "" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +msgid "Reference implementation in Python" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +msgid "Names and normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +msgid "Name normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +msgid "Project Status Markers" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +msgid "Installer semantics: none." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +msgid "Installer semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +msgid "``deprecated``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +msgid "``pylock.toml`` Specification" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +msgid "``lock-version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +msgid "**Required?**: yes" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +msgid "``environments``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +msgid "``dependency-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +msgid "``[[packages]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +msgid "``packages.version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +msgid "The version of the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +msgid "``[[packages.dependencies]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +msgid "The time the file was uploaded." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +msgid "``packages.index``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +msgid "``import-names``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +msgid "Legacy specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +msgid "Examples:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +msgid "Example:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +msgid "PyPA schemas" +msgstr "" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +msgid "Python Description Formats" +msgstr "" + +#: ../source/specifications/section-reproducible-environments.rst:3 +msgid "Reproducible Environments" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +msgid "Normalized Names" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +msgid "HTML Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +msgid "Project List" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +msgid "Project Detail" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +msgid "JSON Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +msgid "Content-Types" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +msgid "Version + Format Selection" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +msgid "Definitions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +msgid "Version scheme" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +msgid "Pre-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +msgid "Version epochs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +msgid "Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +msgid "Integer Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +msgid "Version exclusion" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +msgid "Well-known Project URLs in Metadata" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +msgid "Label normalization" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +msgid "Normalized" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"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/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "" + +#: ../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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "" + +#: ../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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" diff --git a/locales/uk/LC_MESSAGES/messages.po b/locales/uk/LC_MESSAGES/messages.po new file mode 100644 index 000000000..4f6c1a667 --- /dev/null +++ b/locales/uk/LC_MESSAGES/messages.po @@ -0,0 +1,27885 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# Alex Solonenko , 2021. +# Sviatoslav Sydorenko , 2021, 2022, 2023, 2024. +# meowmeowmeowcat , 2021. +# Tymofii Lytvynenko , 2021. +# Olexandr , 2021. +# Artem , 2022. +# Юра , 2022. +# Алекс Острозький , 2022. +# Kari Kari , 2022. +# Dan , 2022. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: 2024-03-01 20:00+0000\n" +"Last-Translator: Sviatoslav Sydorenko \n" +"Language-Team: Ukrainian \n" +"Language: uk\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2);\n" +"X-Generator: Weblate 5.5-dev\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "Зробіть внесок до керівництва" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "" +"|PyPUG| запрошує контриб'юторів! Тут є багато способів, щоб допомогти, " +"зокрема:" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "Читання керівництва і надання відгуку" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "Оцінювання нових вкладів" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "Вивірення існуючого вмісту" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "Написання нового вмісту" + +#: ../source/contribute.rst:14 +#, fuzzy +#| msgid "Translate the guide" +msgid "Translating the guide" +msgstr "Перекладайте керівництво" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" +"Переважна більшість роботи над |PyPUG| відбувається у `репозиторії проєкту " +"на GitHub `__. Аби розпочати, ознайомтеся з " +"переліком `відкритих іш'ю `__ та `пул реквестів `__. Якщо ви збираєтеся написати статтю чи відредагувати це " +"керівництво, будь ласка, прочитайте наше :ref:`керівництво зі стилю " +"`." + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" +"Здійснюючи внесок до |PyPUG|, від вас очікуватиметься слідування `кодексу " +"честі `__ PSF." + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "Типи документації" + +#: ../source/contribute.rst:34 +#, fuzzy +#| msgid "" +#| "This project consists of four distinct documentation types with specific " +#| "purposes. When proposing new additions to the project please pick the " +#| "appropriate documentation type." +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" +"Цей проєкт містить чотири ясно виражені типи документації із чіткими " +"призначеннями. Пропонуючи нові доповнення до проєкту, будь ласка, оберіть " +"відповідний вид документації." + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "Навчальні посібники" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" +"Навчальні інструкції зосереджені на навчанні читача нових концептів шляхом " +"досягнення цілі. Це упевнені керівництва у вигляді крок-за-кроком. Вони не " +"містять додаткових попереджень чи інформації. `приклад документу у стилі " +"навчальної інструкції `_." + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "Керівництва" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" +"Керівництва зосереджені на досягненні конкретного завдання і можуть " +"покладатися на деякий рівень заздалегідь наявних знань. Вони подібні до " +"навчальних інструкцій, але мають вужчий та чіткіший фокус, а також можуть " +"перелічувати багато застережень й додаткової інформації де потрібно. Крім " +"того, керівництва можуть розбирати багато підходів до вирішення цього " +"завдання. :doc:`приклад документу у стилі керівництва `." + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "Обговорення" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" +"Обговорення зосереджені на роз'ясненні розумінні й інформації. Вони " +"досліджують конкретну тему, не маючи на меті нічого " +"конкретного. :doc:`приклад документу в стилі обговорення `." + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "Специфікації" + +#: ../source/contribute.rst:69 +#, fuzzy +#| msgid "" +#| "Specifications are reference documention focused on comprehensively " +#| "documenting an agreed-upon interface for interoperability between " +#| "packaging tools. :doc:`example specification-style document " +#| "`." +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" +"Специфікації — це довідкова документація, орієнтована на всебічне " +"документування погодженого інтерфейсу сумісності засобів " +"пакування. :doc:`приклад документу в стилі специфікації `." + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "Переклади" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" +"Ми використовуємо `Weblate`_ для управління перекладами цього проєкту. Будь " +"ласка відвідайте `packaging.python.org`_ проєкт на Weblate для внеску." + +#: ../source/contribute.rst:80 +#, fuzzy +#| msgid "" +#| "If you are experiencing issues while you are working on translations, " +#| "please open an issue on `Github`_." +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" +"Якщо у вас виникли проблеми під час роботи над перекладами, відкрийте іш'ю " +"на `Github`_." + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" +"Будь-які переклади цього проєкту мають відповідати `reStructuredText " +"syntax`_." + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "Додавання мови" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" +"Якщо вашої мови немає в списку на `packaging.python.org`_, натисніть " +"кнопку :guilabel:`Почати новий переклад` внизу списку мов і додайте мову, " +"яку ви хочете перекласти." + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "Дотримання синтаксису reStructuredText" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" +"Якщо ви не знайомі з синтаксисом reStructuredText (RST), прочитайте `цей " +"посібник`_ перед перекладом на Weblate." + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "**Не перекладайте текст у посиланні напряму**" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "" +"Перекладаючи текст посилання, будь ласка, не перекладайте його безпосередньо." + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "Неправильно: перекладіть наступний текст безпосередньо:" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" +"Праворуч: перекладіть наступний текст своєю мовою та додайте оригінальне " +"посилання:" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "Збирання цього керівництва локально" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" +"Хоча це й не вимагається для внесення вкладів, збирання цього керівництва " +"локально може бути корисним аби протестувати свої зміни. Щоб зібрати це " +"керівництво локально, вам знадобиться:" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" +":doc:`Nox `. Ви можете встановити чи оновити nox за допомогою " +"``pip``:" + +#: ../source/contribute.rst:136 +#, fuzzy +#| msgid "" +#| "Python 3.8. Our build scripts are usually tested with Python 3.8 only. " +#| "See the :doc:`Hitchhiker's Guide to Python installation instructions " +#| "` to install Python 3.8 on your " +#| "operating system." +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" +"Python 3.8. Наші скрипти зазвичай тестуються з Python 3.8. " +"Скористайтеся :doc:`керівництвом автостопера по інструкціях встановлення " +"Python `, аби встановити Python 3.8 у " +"вашій операційній системі." + +#: ../source/contribute.rst:140 +#, fuzzy +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" +"Для збирання цього керівництва запустіть нижченаведену команду bash у " +"директорії із джерельним кодом:" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" +"По завершенню процесу, ви можете знайти результуючий HTML у теці ``./build/" +"html``. Ви можете відкрити файл ``index.html`` для перегляду цього " +"керівництва у веб-оглядачі, втім рекомендується отримувати доступ до " +"керівництва через HTTP сервер." + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" +"Ви можете зібрати керівництво і організувати доступ до нього через HTTP " +"сервер за допомогою наведеної команди:" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "Керівництво можна буде переглядати через http://localhost:8000." + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "Куди це керівництво публікується" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" +"Це керівництво розгорнуте через ReadTheDocs і конфігурація живе на https://" +"readthedocs.org/projects/python-packaging-user-guide/. Доступ до нього " +"надається із додаткового домену через фронт-енд Fast.ly." + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "Керівництво по стилю" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" +"Це керівництво зі стилю містить поради щодо того, як вам слід писати |" +"PyPUG|. Перш, ніж почати, ознайомтеся з ним. Дотримуючись цього керівництва " +"по стилю, ваші внески допоможуть доповнити єдине ціле і спростять їх " +"схвалення для проєкту." + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "Призначення" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" +"|PyPUG| має на меті бути авторитетним ресурсом щодо того як пакувати, " +"публікувати та встановлювати проєкти на Python, використовуючи сучасні " +"засоби." + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "Охоплення" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" +"Керівництво має відповісти на запитання і вирішити проблеми за допомогою " +"точних і влучних порад." + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" +"Керівництво не має бути всеосяжним і не має на меті замінити документацію " +"окремих проєктів. Наприклад, pip містить дюжини команд, опцій та " +"налаштувань. Документація pip ретельно описує кожну з них, тоді як це " +"керівництво описує лише частини pip, що необхідні для виконання конкретних " +"завдань, описаних у цьому керівництві." + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "Читачі" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "" +"Цільова аудиторія цього керівництва — усі, хто користується Pythonом із " +"пакунками." + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" +"Не забувайте, що Python-спільнота — велика і привітна. Читачі можуть бути " +"іншого віку, статі, мати іншу освіту та належати іншій культурі, ніж ви, але " +"вони так само заслуговують дізнаватися про пакування, як і ви." + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" +"Зокрема, пам'ятайте, що не усі люди, які використовують Python, вважають " +"себе програмістами. До читачів цього керівництва можуть належати астрономи, " +"художники, учні так само, як і професійні розробники програмного " +"забезпечення." + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "Вираження і тон" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" +"Під час написання цього керівництва, намагайтеся виражатися доступно й " +"скромно, навіть якщо у вас є усі відповіді." + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" +"Уявіть, що ви працюєте над Python-проєктом з кимось, кого знаєте як розумну " +"людину з потужними навичками. Вам подобається працювати з цією людиною, як і " +"їй подобається працювати із вами. Ця людина спитала вас і ви знаєте " +"відповідь. Як би ви відповідали? *Саме так* і варто писати це керівництво." + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" +"Ось швидка перевірка: спробуйте прочитати вголос, щоб відчути виразність і " +"тон свого письма. Чи звучить це як щось, що ви б сказали, або ж це звучить " +"так, ніби ви граєте роль чи виголошуєте промову? Не соромтеся скористатися " +"скороченнями і не турбуйтеся про дотримання вимогливих граматичних правил. " +"Цим вам дозволено закінчити речення прийменником, якщо саме так ви бажаєте " +"його закінчити." + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" +"Під час написання керівництва, підлаштуйте свій тон на серйозність і " +"складність теми. Якщо ви пишете вступну навчальну інструкцію, можна " +"пожартувати, однак якщо ви покриваєте делікатну рекомендацію щодо безпеки, " +"можливо, вам захочеться взагалі уникнути жартів." + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "Домовленості й механіка" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "**Звертайтеся до читачів**" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" +"Коли ви даєте рекомендації або вказуєте необхідні кроки, звертайтеся до " +"читачів на *ви* або використовуйте наказовий спосіб." + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "Неправильно: Для встановлення, користувач запускає …" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "Правильно: Ви можете встановити це, виконавши …" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "Правильно: Щоб встановити це, виконайте…" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "**Оголошуйте припущення**" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" +"Уникайте невисловлених припущень. Читання в Інтернеті означає, що яка " +"завгодно сторінка керівництва може бути найпершою його сторінкою, яку читач " +"побачить узагалі. Якщо ж ви збираєтеся робити припущення, то скажіть, на які " +"саме припущення ви покладаєтесь." + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "**Щедро додавайте перехресні посилання**" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" +"Коли ви вперше згадуєте інструмент або підхід, дайте посилання на ту частину " +"керівництва, яка розповідає про нього, або ж на відповідну документацію " +"деінде. Не змушуйте читачів шукати інформацію." + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "**Дотримуйтеся практик іменування**" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" +"Згадуючи інструменти, сайти, людей чи інші власні назви, використовуйте їх " +"бажане написання великих літер." + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "Неправильно: Pip використовує…" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "Правильно: pip використовує…" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "Неправильно: ...розміщено на github." + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "Правильно: ...розміщено на GitHub." + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "**Використовуйте ґендерно нейтральний стиль**" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" +"Часто ви звертатиметеся до читача безпосередньо за допомогою *ви* і *ваш*. В " +"інших випадках використовуйте гендерно-нейтральні займенники *вони* та *їх*, " +"чи повністю уникайте займенників." + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "Неправильно: Доглядач завантажує файл. А потім він…" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "Правильно: Доглядачі завантажують файл. А потім вони…" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "Правильно: Доглядачі завантажують файл. А потім ці доглядачі…" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "**Заголовки**" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" +"Пишіть заголовки за допомогою слів, які читачі шукатимуть. Хороший спосіб це " +"зробити — скласти заголовок так, щоб він доповнював неявне запитання. " +"Наприклад, читачі можуть хотіти дізнатися *Як я можу встановити MyLibrary?*, " +"тож хорошим заголовком буде *Встановити MyLibrary*." + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" +"У заголовках розділів, дотримуйтеся регістру речень. Іншими словами, пишіть " +"заголовки так, як ви б написали звичайне речення." + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "Неправильно: Речі, Які Вам Слід Знати Про Python" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "Правильно: Речі, які вам слід знати про Python" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "**Числа**" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" +"У всередині тексту, пишіть числа від одного до дев'яти словами. Для інших " +"чисел або чисел у таблицях використовуйте цифри." + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "Розгортання Python-застосунків" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "Стан сторінки" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "Незавершено" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "Останнє рецензування" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "24.08.2021" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "Огляд" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "Підтримка декількох апаратних платформ" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "Пакування на рівні ОС та встановлювачі" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "Windows" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "Pynsist" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" +"`Pynsist `__ — це інструмент, який укладає " +"Python-програми разом із інтерпретатором Python у єдиний встановлювач на " +"основі NSIS. У більшості випадків пакування вимагає від користувача лише " +"вибору версії Python-інтерпретатора і оголошення залежностей програми. Цей " +"засіб завантажує вказаний інтерпретатор Python для Windows і загортає його з " +"усіма залежностями до єдиного Windows-виконуваного встановлювача." + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" +"Встановлену програму можна запустити черкз ярлик, який встановлювач додає до " +"меню \"Пуск\". Він використовує інтерпретатор Python, що знаходиться у " +"власній теці застосунку, незалежно від будь-якого іншого екземпляра Python " +"на тому ж комп’ютері." + +#: ../source/discussions/deploying-python-applications.rst:71 +#, fuzzy +#| msgid "" +#| "A big advantage of Pynsist is that the Windows packages can be built on " +#| "Linux. There are several examples for different kinds of programs " +#| "(console, GUI) in the `documentation `. The tool is " +#| "released under the MIT-licence." +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" +"Значною перевагою Pynsist є те, що пакунки для Windows можуть бути зібрані " +"під Linux. У `документації ` є кілька прикладів різних видів " +"програм (консольних, графічних). Інструмент доступний під ліцензією MIT." + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "Колекції застосунків" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "py2exe" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "macOS" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "py2app" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" +"`py2app `__ — це команда інструментних " +"налаштувань Python, яка дозволить вам створювати автономні комплекти " +"застосунків і плагіни macOS зі сценаріїв Python. Зауважте, що py2app ПОВИНЕН " +"використовуватися в macOS для створення застосунків, він не може створювати " +"застосунки Mac на інших платформах. py2app випущено під ліцензією MIT." + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "Unix (включаючи Linux і macOS)" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "pex" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" +"`pex `__ — це бібліотека для створення " +"файлів. pex (виконуваних файлів Python), які є виконуваними середовищами " +"Python у дусі virtualenvs. pex є розширенням ідей, викладених у :pep:`441`, " +"і робить розгортання застосунків Python таким же простим, як cp. файли pex " +"можуть навіть включати кілька специфічних для платформи дистрибутивів " +"Python, що означає, що один файл pex можна переносити на Linux і macOS. pex " +"випущено за ліцензією Apache 2.0." + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "Керування конфігуруванням" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +#, fuzzy +#| msgid "Distribution Package" +msgid "Distribution package vs. import package" +msgstr "Дистриб'юторський пакет" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +#, fuzzy +#| msgid "Distribution Package" +msgid "What's a distribution package?" +msgstr "Дистриб'юторський пакет" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +#, fuzzy +#| msgid "Import Package" +msgid "What's an import package?" +msgstr "Імпорт пакету" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:51 +#, fuzzy +#| msgid "Distribution Package" +msgid "Provide complete source distributions" +msgstr "Дистриб'юторський пакет" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +#, fuzzy +#| msgid "zest.releaser" +msgid "Aim for stable releases" +msgstr "zest.releaser" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" +"**Обговорення** зосереджені на наданні вичерпної інформації щодо певної " +"теми. Якщо ви просто намагаєтеся виконати певну роботу, зверніться до :doc:`/" +"guides/index`." + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "install_requires проти файлів requirements" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "install_requires" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" +"``install_requires`` — ключове слово у :ref:`setuptools`-" +"файлі :file:`setup.py`, яке слід використовувати для зазначення того, що " +"проєкт потребує **мінімально**, аби запускатися коректно. Коли проєкт " +"інстальовано за допомогою :ref:`pip`, це специфікація, яка використовується " +"для встановлення його залежностей." + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" +"Наприклад, якщо проєкт потребує A чи B, ваш ``install_requires`` виглядатиме " +"ось так:" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" +"До того ж, позначення будь-яких відомих нижніх чи верхніх меж вважається " +"найкращою практикою." + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" +"Наприклад, може бути відомо, що ваш проєкт потребує щонайменше v1 залежності " +"'A' та v2 залежності 'B', тоді це виглядатиме отак:" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +#, fuzzy +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" +"Крім того, може бути відомо, що проєкт A використовує семантичне " +"версіонування і що 'A' v2 означає несумісну зміну, тож має сенс не дозволяти " +"v2:" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" +"Закріплення точних версій залежностей у ``install_requires`` не вважається " +"найкращою практикою, так само, не варто вказувати під-залежності (тобто " +"залежності ваших залежностей). Це надміру обмежувально і перешкоджає " +"користувачам скористатися перевагами оновлення залежностей." + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" +"Наостанок, важливо розуміти, що ``install_requires`` перелічує «Абстрактні» " +"залежності, тобто лише обмеження назв і версій, які не визначають звідки ті " +"залежності будуть заповнені (тобто, із якого реєстру чи джерела). Звідки " +"(тобто, яким чином вони мають стати «Конкретними») визначається під час " +"встановлення за допомогою опцій :ref:`pip`. [1]_" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "Файли requirements" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" +":ref:`Файли requirements `, описуючи дуже спрощено, " +"це лише перелік аргументів для :ref:`pip:pip install`, записаних у файл." + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" +"У той час як ``install_requires`` визначає залежності для єдиного " +"проєкту, :ref:`файли requirements ` часто " +"використовуються для визначення залежностей для певного середовища Python " +"environment." + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" +"У той час як залежності в ``install_requires`` мінімальні, файли " +"requirements часто містіть вичерпний перелік конкретних версій задля " +"досягнення :ref:`повторюваних встановлень ` повного " +"середовища." + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" +"У той час як залежності в ``install_requires`` «Абстрактні», тобто не " +"пов'язані із жодним конкретним реєстром, файли requirements часто містять " +"опції pip на кшталт ``--index-url`` чи ``--find-links``, щоб зробити " +"залежності «Конкретними», тобто асоційованими із певним реєстром чи " +"каталогом пакунків. [1]_" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" +"У той час як pip автоматично аналізує метадані з ``install_requires`` під " +"час встановлення, цього не відбувається із файлами requirements, вони лиш " +"використовуються коли користувачі явно встановлюють їх через ``python -m pip " +"install -r``." + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" +"Щоб дізнатися більше про «Абстрактні» залежності проти «Конкретних», читайте " +"https://caremad.io/posts/2013/07/setup-vs-requirement/." + +#: ../source/discussions/package-formats.rst:5 +#, fuzzy +#| msgid "Package Index" +msgid "Package Formats" +msgstr "Реєстр Пакунків" + +#: ../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 "Distribution Package" +msgid "What is a source distribution?" +msgstr "Дистриб'юторський пакет" + +#: ../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..." +msgid "What about eggs?" +msgstr "А як щодо..." + +#: ../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 +#, fuzzy +msgid "Here's a breakdown of the important differences between wheel and egg." +msgstr "Ось розподіл важливих відмінностей між :term:`Wheel` і :term:`Egg`." + +#: ../source/discussions/package-formats.rst:146 +#, fuzzy +#| msgid "" +#| "The :term:`Egg` format was introduced by :ref:`setuptools` in 2004, " +#| "whereas the :term:`Wheel` format was introduced by :pep:`427` in 2012." +msgid "" +"The egg format was introduced by :ref:`setuptools` in 2004, whereas the " +"wheel format was introduced by :pep:`427` in 2012." +msgstr "" +"Формат :term:`Egg` був представлений :ref:`setuptools` у 2004 році, тоді як " +"формат :term:`Wheel` був представлений :pep:`427` у 2012 році." + +#: ../source/discussions/package-formats.rst:149 +#, fuzzy +msgid "" +"Wheel has an :doc:`official standard specification `. Egg did not." +msgstr ":term:`Wheel` має :pep:`офіційний PEP <427>`. :term:`Egg` ні." + +#: ../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 +#, 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/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 +#, fuzzy +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 "" +"За певних обставин, у деяких випадках wheels можна використовувати як " +"імпортований формат середовища виконання, хоча :pep:`наразі це офіційно не " +"підтримується <427#is-it-possible-to-import-python-code-directly-from- a-" +"wheel-file>`." + +#: ../source/discussions/pip-vs-easy-install.rst:6 +msgid "pip vs easy_install" +msgstr "pip проти easy_install" + +#: ../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`. Він був помітний у ті часи, " +"завдяки встановленням :term:`пакунків ` із :term:`PyPI " +"` з використанням специфікаторів вимог і " +"автоматичному встановленню залежностей." + +#: ../source/discussions/pip-vs-easy-install.rst:14 +#, fuzzy +#| 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." +msgid "" +":ref:`pip` came later in 2008, as an 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:`pip` з'явився пізніше у 2008 році, як альтернатива :ref:`easy_install " +"`, хоча він все ще був значною мірою створений на базі " +"компонентів :ref:`setuptools`. Він виділявся тим, що *не* встановлював " +"пакунки ні як :term:`Eggs `, ні із :term:`Eggs ` (але натомість як " +"прості «пласкі» пакунки із :term:`sdists `), вводячи ідею :ref:`файлів requirements `, які надавали користувачам можливість легко повторювати середовища." + +#: ../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/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "**pip**" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "**easy_install**" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "Встановлення з :term:`колес `" + +#: ../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`` і ``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/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +#, fuzzy +#| msgid "Yes (``python -m pip uninstall``)" +msgid "``python setup.py install``" +msgstr "Так (``python -m pip uninstall``)" + +#: ../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 "" + +#: ../source/discussions/setup-py-deprecated.rst:25 +#: ../source/discussions/setup-py-deprecated.rst:39 +#: ../source/guides/modernize-setup-py-project.rst:36 +#, fuzzy +#| msgid "``python_requires``" +msgid "``python setup.py sdist``" +msgstr "``python_requires``" + +#: ../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 "" + +#: ../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 +#, fuzzy +#| msgid "Packaging tool recommendations" +msgid "Recommendation" +msgstr "Поради щодо засобу пакування" + +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +#, fuzzy +#| msgid "Yes (``python -m pip uninstall``)" +msgid "``python -m pip install .``" +msgstr "Так (``python -m pip uninstall``)" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +#, fuzzy +#| msgid "Yes (``python -m pip uninstall``)" +msgid "``python -m pip install --editable .``" +msgstr "Так (``python -m pip uninstall``)" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +#, fuzzy +#| msgid "``python_requires``" +msgid "``python setup.py test``" +msgstr "``python_requires``" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +#, fuzzy +#| msgid "Yes (``python -m pip uninstall``)" +msgid "``python -m twine check --strict dist/*``" +msgstr "Так (``python -m pip uninstall``)" + +#: ../source/discussions/setup-py-deprecated.rst:104 +#, fuzzy +#| msgid "Yes (``python -m pip uninstall``)" +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "Так (``python -m pip uninstall``)" + +#: ../source/discussions/setup-py-deprecated.rst:105 +#, fuzzy +#| msgid "Yes (``python -m pip uninstall``)" +msgid "``python -m twine upload dist/*``" +msgstr "Так (``python -m pip uninstall``)" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +#, fuzzy +#| msgid "``python_requires``" +msgid "``python setup.py --version``" +msgstr "``python_requires``" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +#, fuzzy +#| msgid "Yes (``python -m pip uninstall``)" +msgid "``python -m setuptools_scm``" +msgstr "Так (``python -m pip uninstall``)" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:130 +#, fuzzy +msgid "``bdist``" +msgstr "``text/x-rst``" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +#, fuzzy +#| msgid "build" +msgid "``build``" +msgstr "build" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +#, fuzzy +msgid "``build_scripts``" +msgstr "``scripts``" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:141 +#, fuzzy +#| msgid "**easy_install**" +msgid "``easy_install``" +msgstr "**easy_install**" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:144 +#, fuzzy +#| msgid "``pip install app``" +msgid "``install_data``" +msgstr "``pip install app``" + +#: ../source/discussions/setup-py-deprecated.rst:145 +#, fuzzy +#| msgid "``install_requires``" +msgid "``install_egg_info``" +msgstr "``install_requires``" + +#: ../source/discussions/setup-py-deprecated.rst:146 +#, fuzzy +#| msgid "``install_requires``" +msgid "``install_headers``" +msgstr "``install_requires``" + +#: ../source/discussions/setup-py-deprecated.rst:147 +#, fuzzy +#| msgid "``install_requires``" +msgid "``install_lib``" +msgstr "``install_requires``" + +#: ../source/discussions/setup-py-deprecated.rst:148 +#, fuzzy +#| msgid "``console_scripts``" +msgid "``install_scripts``" +msgstr "``console_scripts``" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:150 +#, fuzzy +#| msgid "``scripts``" +msgid "``saveopts``" +msgstr "``scripts``" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +#, fuzzy +#| msgid "pyproject.toml" +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "pyproject.toml" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr "" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +#, fuzzy +#| msgid "Incomplete" +msgid "Complete" +msgstr "Незавершено" + +#: ../source/discussions/single-source-version.rst:8 +#, fuzzy +#| msgid "2021-8-24" +msgid "2024-10-07" +msgstr "24.08.2021" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +#, fuzzy +#| msgid "`Flatpak `_" +msgid "`Flit `_" +msgstr "`Flatpak `_" + +#: ../source/discussions/single-source-version.rst:56 +#, fuzzy +#| msgid "`AppImage `_" +msgid "`Hatchling `_" +msgstr "`AppImage `_" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +#, fuzzy +#| msgid "`Flexx `_" +msgid "`setuptools_scm `_" +msgstr "`Flexx `_" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +#, fuzzy +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "Ось аналіз важливих розбіжностей між pip та застарілим easy_install:" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +#, fuzzy +#| msgid "Version" +msgid "Versioning" +msgstr "Version" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" + +#: ../source/discussions/versioning.rst:12 +#, fuzzy +#| msgid "Date based versioning" +msgid "Valid version numbers" +msgstr "Версіонування базоване на датах" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +#, fuzzy +#| msgid "Semantic versioning (preferred)" +msgid "Semantic versioning vs. calendar versioning" +msgstr "Семантичне версіонування (надається перевага)" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +#, fuzzy +#| msgid "Serial versioning" +msgid "Semantic versioning" +msgstr "Порядкове версіонування" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +#, fuzzy +#| msgid "Serial versioning" +msgid "Calendar versioning" +msgstr "Порядкове версіонування" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +#, fuzzy +msgid "Other schemes" +msgstr "Version" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../source/flow.rst:3 +#, fuzzy +msgid "The Packaging Flow" +msgstr "Флоу пакування" + +#: ../source/flow.rst:5 +#, fuzzy +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 "" +"Цей документ має на меті окреслити процес публікації/" +"розповсюдження :term:`дистрибутивного пакета <дистрибутивного пакета>`, " +"зазвичай до `Індексу пакетів Python (PyPI)`_. Він написаний для видавців " +"пакетів, які вважаються авторами." + +#: ../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:`tutorial ` описує процес підготовки " +"простого пакета до випуску, він не повністю прораховує, які кроки та файли " +"потрібні, і для якої мети." + +#: ../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 "" + +#: ../source/flow.rst:22 +#, fuzzy +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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:60 +#, fuzzy +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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 ../source/flow.rst:143 +msgid "" +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../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 :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +#, fuzzy +#| msgid "Distribution Package" +msgid "Distribution Archive" +msgstr "Дистриб'юторський пакет" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "Дистриб'юторський пакет" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "Яйце" + +#: ../source/glossary.rst:108 +#, fuzzy +#| msgid "" +#| "The :term:`Egg` format was introduced by :ref:`setuptools` in 2004, " +#| "whereas the :term:`Wheel` format was introduced by :pep:`427` in 2012." +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:`Egg` був представлений :ref:`setuptools` у 2004 році, тоді як " +"формат :term:`Wheel` був представлений :pep:`427` у 2012 році." + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "Модуль розширення" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "Імпорт пакету" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +#, fuzzy +#| msgid "Installer" +msgid "Installed Project" +msgstr "Встановлювач" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +#, fuzzy +#| msgid "``classifiers``" +msgid "License Classifier" +msgstr "``classifiers``" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +#, fuzzy +#| msgid "Local version identifiers" +msgid "License Identifier" +msgstr "Ідентифікатори місцевих версій" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "Модуль" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "Реєстр Пакунків" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "Індекс за проєктом" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "Проєкт" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +#, fuzzy +#| msgid "Project name" +msgid "Project Root Directory" +msgstr "Назва проєкту" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "Чистий модуль" + +#: ../source/glossary.rst:257 +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:260 +#, fuzzy +#| msgid "Project name" +msgid "Pyproject Metadata" +msgstr "Назва проєкту" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +#, fuzzy +#| msgid "pyproject.toml" +msgid "Pyproject Metadata Key" +msgstr "pyproject.toml" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "Управління з пакування Python (PyPA)" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "Реєстр Python-пакунків (PyPI)" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "pypi.org" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "pyproject.toml" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "Випуск" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "Специфікатор вимоги" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "" + +#: ../source/glossary.rst:344 +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:348 +#, fuzzy +#| msgid "Project name" +msgid "Root License Directory" +msgstr "Назва проєкту" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "setup.py" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "setup.cfg" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "Вихідний архів" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "Специфікатор версії" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +#, fuzzy +#| msgid "Format::" +msgid "Wheel Format" +msgstr "Формат::" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "Колесо" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +#, fuzzy +#| msgid "Project" +msgid "Wheel Project" +msgstr "Проєкт" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "Публічний набір даних" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "Налаштування" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "Перейдіть до `веб-інтерфейсу BigQuery `_." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "Створіть новий проєкт." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" +"Увімкніть `BigQuery API `__." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "Структура даних" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "Стовпець" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "Опис" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "Приклади" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "Дата й час" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "Назва проєкту" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "Версія пакунку" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "Встановлювач" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "pip, :ref:`bandersnatch`" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "Версія Python" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "Корисні запити" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "Підрахунок завантажень пакунків" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" +"Нижченаведений запит підраховує загальну кількість завантажень для проєкту " +"«pytest»." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "26190085" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +#, fuzzy +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" +"Щоб підрахувати лише завантаження з pip, відфільтруйте стовпець " +"``details.installer.name``." + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "24334215" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "month" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "1956741" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "2018-01-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "2344692" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "2017-12-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "1730398" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "2017-11-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "2047310" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "2017-10-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "1744443" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "2017-09-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "1916952" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "2017-08-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "3.7" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "18051328726" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "3.6" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "9635067203" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "3.8" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "7781904681" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "2.7" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "6381252241" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "null" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +#, fuzzy +msgid "url" +msgstr "``url``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "" +"https://files.pythonhosted.org/packages/eb/" +"45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" +"sampleproject-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "" +"https://files.pythonhosted.org/packages/56/0a/" +"178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" +"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +msgid "" +"https://files.pythonhosted.org/packages/" +"63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" +"sampleproject_nomura-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "Додаткові інструменти" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +#, fuzzy +#| msgid "Installing packages" +msgid "Creating the package" +msgstr "Встановлення пакунків" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +#, fuzzy +#| msgid "pyproject.toml" +msgid "``pyproject.toml``" +msgstr "pyproject.toml" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +#, fuzzy +#| msgid "Installing packages" +msgid "Installing the package with ``pipx``" +msgstr "Встановлення пакунків" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +#, fuzzy +#| msgid "Version Specifier" +msgid "Conclusion" +msgstr "Специфікатор версії" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +#, fuzzy +#| msgid "2013-12-08" +msgid "2023-12-14" +msgstr "08.12.2013" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "README.rst / README.md" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "MANIFEST.in" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "LICENSE.txt" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "``install_requires``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "``scripts``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "Вибір схеми версіонування" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "Створіть обліковий запис" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +#, fuzzy +#| msgid "Installation format" +msgid "1. Install twine" +msgstr "Формат встановлення" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +#, fuzzy +#| msgid "Python version" +msgid "Dropping a Python version" +msgstr "Версія Python" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 +#, fuzzy +#| msgid "Package Index" +msgid "Package upload" +msgstr "Реєстр Пакунків" + +#: ../source/guides/hosting-your-own-index.rst:64 +msgid "PyPI fall-through [2]_" +msgstr "" + +#: ../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 +#, fuzzy +#| msgid ":ref:`pip`" +msgid ":ref:`devpi`" +msgstr ":ref:`pip`" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +#, fuzzy +#| msgid ":ref:`pip`" +msgid ":ref:`simpleindex`" +msgstr ":ref:`pip`" + +#: ../source/guides/hosting-your-own-index.rst:78 +#, fuzzy +#| msgid "pypiserver" +msgid ":ref:`pypiserver`" +msgstr "pypiserver" + +#: ../source/guides/hosting-your-own-index.rst:83 +#, fuzzy +#| msgid ":ref:`pip`" +msgid ":ref:`pypiprivate`" +msgstr ":ref:`pip`" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +#, fuzzy +#| msgid ":ref:`pip`" +msgid ":ref:`pypicloud`" +msgstr ":ref:`pip`" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +#, fuzzy +#| msgid ":ref:`pip`" +msgid ":ref:`pywharf`" +msgstr ":ref:`pip`" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +#, fuzzy +#| msgid ":ref:`pip`" +msgid ":ref:`pulppython`" +msgstr ":ref:`pip`" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +#, fuzzy +#| msgid ":ref:`pip`" +msgid ":ref:`pip2pi`" +msgstr ":ref:`pip`" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +#, fuzzy +#| msgid ":ref:`pip`" +msgid ":ref:`dumb-pypi`" +msgstr ":ref:`pip`" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +#, fuzzy +#| msgid "`AppImage `_" +msgid "`Apache `_" +msgstr "`AppImage `_" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:5 +msgid "Package index mirrors and caches" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:8 +#, fuzzy +#| msgid "2013-12-08" +msgid "2023-11-08" +msgstr "08.12.2013" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +#, fuzzy +#| msgid "pip, :ref:`bandersnatch`" +msgid ":ref:`bandersnatch`" +msgstr "pip, :ref:`bandersnatch`" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +#, fuzzy +#| msgid ":ref:`pip`" +msgid ":ref:`proxpi`" +msgstr ":ref:`pip`" + +#: ../source/guides/index-mirrors-and-caches.rst:93 +#: ../source/guides/index-mirrors-and-caches.rst:99 +#, fuzzy +#| msgid "per project index" +msgid "multiple proxied indexes" +msgstr "окремі реєстри для проєктів" + +#: ../source/guides/index-mirrors-and-caches.rst:95 +msgid ":ref:`nginx_pypi_cache`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +#, fuzzy +#| msgid ":ref:`pip`" +msgid ":ref:`flaskpypiproxy`" +msgstr ":ref:`pip`" + +#: ../source/guides/index-mirrors-and-caches.rst:105 +#, fuzzy +#| msgid "Maintainer" +msgid "unmaintained" +msgstr "Доглядач" + +#: ../source/guides/installing-scientific-packages.rst:5 +msgid "Installing scientific packages" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:8 +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." +msgstr "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "pipx встановлюється через pip:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "Наприклад:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "Fedora" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "CentOS/RHEL" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:108 +msgid "openSUSE" +msgstr "openSUSE" + +#: ../source/guides/installing-using-linux-tools.rst:118 +#, fuzzy +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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "Arch Linux" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +#, fuzzy +#| msgid "Installing packages" +msgid "Install packages in a virtual environment using pip and venv" +msgstr "Встановлення пакунків" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +#, fuzzy +#| msgid "install_requires vs requirements files" +msgid "Use and create a requirements file" +msgstr "install_requires проти файлів requirements" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../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 +#, fuzzy +#| msgid "Create a new project." +msgid "Create a new virtual environment" +msgstr "Створіть новий проєкт." + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:37 +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." +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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +#, fuzzy +#| msgid "Installing packages" +msgid "Install packages using pip" +msgstr "Встановлення пакунків" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +#, fuzzy +#| msgid "Installing packages" +msgid "Install a package" +msgstr "Встановлення пакунків" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +#, fuzzy +#| msgid "Installing packages" +msgid "Install a specific package version" +msgstr "Встановлення пакунків" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +#, fuzzy +msgid "Install extras" +msgstr "Встановлення пакунків" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +#, fuzzy +#| msgid "Installing packages" +msgid "Install a package from source" +msgstr "Встановлення пакунків" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +#, fuzzy +#| msgid "Installing packages" +msgid "Install from other package indexes" +msgstr "Встановлення пакунків" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +#, fuzzy +#| msgid "Requirements files" +msgid "Using a requirements file" +msgstr "Файли requirements" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +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/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +#, fuzzy +#| msgid "Installing packages" +msgid "Installing packages using virtualenv" +msgstr "Встановлення пакунків" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +#, fuzzy +#| msgid "Examples" +msgid "Licensing Examples" +msgstr "Приклади" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +#, fuzzy +#| msgid "For example:" +msgid "Basic example" +msgstr "Наприклад:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +#, fuzzy +#| msgid "For example:" +msgid "Advanced example" +msgstr "Наприклад:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +#, fuzzy +#| msgid "Here are some examples of compliant version numbers::" +msgid "The appropriate license expressions are:" +msgstr "Ось кілька прикладів сумісних номерів версій::" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +#, fuzzy +#| msgid "For example:" +msgid "Expression examples" +msgstr "Наприклад:" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../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 "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "``setuptools >= 38.6.0``" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "``wheel >= 0.31.0``" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "``twine >= 1.11.0``" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "``twine`` 1.8.0" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "``setuptools`` 27.0.0" + +#: ../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 "" +"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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +#, fuzzy +#| msgid "pyproject.toml" +msgid "Should ``pyproject.toml`` be added?" +msgstr "pyproject.toml" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:36 +#, fuzzy +#| msgid "Yes (``python -m pip uninstall``)" +msgid "``python -m build``" +msgstr "Так (``python -m pip uninstall``)" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +#, fuzzy +#| msgid "Distribution Package" +msgid ":ref:`distributing-packages`" +msgstr "Дистриб'юторський пакет" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:126 +#, fuzzy +#| msgid "Yes (``python -m pip uninstall``)" +msgid "``python -m build --no-isolation``" +msgstr "Так (``python -m pip uninstall``)" + +#: ../source/guides/modernize-setup-py-project.rst:127 +#, fuzzy +#| msgid "Yes (``python -m pip uninstall``)" +msgid "``python -m pip install --no-build-isolation``" +msgstr "Так (``python -m pip uninstall``)" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +#, fuzzy +#| msgid "pyproject.toml" +msgid ":ref:`pyproject-toml-spec`" +msgstr "pyproject.toml" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "08.12.2013" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "Недоліки" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +#, fuzzy +#| msgid "Extension Module" +msgid "Extension module lifecycle" +msgstr "Модуль розширення" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../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 "" +"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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +#, fuzzy +#| msgid ":file:`setup.cfg`" +msgid "Or :file:`setup.py`:" +msgstr ":file:`setup.cfg`" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "Це все, добродії!" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +#, fuzzy +#| msgid "Installation format" +msgid "Installation" +msgstr "Формат встановлення" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "24.12.2014" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "03.12.2015" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "appveyor.yml" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "``DISTUTILS_USE_SDK``" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "``MSSdk``" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "``INCLUDE``" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +msgstr "``LIB``" + +#: ../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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/tool-recommendations.rst:20 +#, fuzzy +#| msgid "Create a new project." +msgid "Virtual environments" +msgstr "Створіть новий проєкт." + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +msgid "Installing packages" +msgstr "Встановлення пакунків" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +#, fuzzy +#| msgid "Built Distribution" +msgid "Building distributions" +msgstr "Вбудований дистрибутив" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +#, fuzzy +#| msgid "Using TestPyPI" +msgid "Uploading to PyPI" +msgstr "Використання TestPyPI" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +#, fuzzy +#| msgid ":ref:`pip`" +msgid ":ref:`Flit`," +msgstr ":ref:`pip`" + +#: ../source/guides/tool-recommendations.rst:180 +#, fuzzy +#| msgid "pip, :ref:`bandersnatch`" +msgid ":ref:`Hatch`," +msgstr "pip, :ref:`bandersnatch`" + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +#, fuzzy +#| msgid ":ref:`pip`" +msgid ":ref:`PDM`," +msgstr ":ref:`pip`" + +#: ../source/guides/tool-recommendations.rst:183 +#, fuzzy +#| msgid ":ref:`pip`" +msgid ":ref:`Pipenv`," +msgstr ":ref:`pip`" + +#: ../source/guides/tool-recommendations.rst:184 +#, fuzzy +#| msgid ":ref:`pip`" +msgid ":ref:`Poetry`," +msgstr ":ref:`pip`" + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +#, fuzzy +#| msgid "pyproject.toml" +msgid "Writing your ``pyproject.toml``" +msgstr "pyproject.toml" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "``name``" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "``version``" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +#, fuzzy +#| msgid "install_requires vs requirements files" +msgid "Dependencies and requirements" +msgstr "install_requires проти файлів requirements" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "``dependencies``/``optional-dependencies``" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "``requires-python``" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "``authors``/``maintainers``" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "``description``" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "``readme``" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +#, fuzzy +#| msgid "``license``" +msgid "``license`` and ``license-files``" +msgstr "``license``" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +#, fuzzy +#| msgid "hatch" +msgid "hatchling" +msgstr "hatch" + +#: ../source/guides/writing-pyproject-toml.rst:313 +#, fuzzy +#| msgid "setuptools" +msgid "setuptools" +msgstr "setuptools" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +#, fuzzy +#| msgid "poetry" +msgid "poetry-core" +msgstr "poetry" + +#: ../source/guides/writing-pyproject-toml.rst:317 +#, fuzzy +#| msgid "build" +msgid "uv-build" +msgstr "build" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "``license``" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +#, fuzzy +#| msgid "``license``" +msgid "``license-files``" +msgstr "``license``" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "``keywords``" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "``classifiers``" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "``urls``" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +#, fuzzy +#| msgid "For example:" +msgid "A full example" +msgstr "Наприклад:" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "Користувацьке керівництво з пакування Python" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" + +#: ../source/index.rst:36 +#, fuzzy +#| msgid "Overview" +msgid "Overview and Flow" +msgstr "Огляд" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +#, fuzzy +#| msgid "Deploying Python applications" +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "Розгортання Python-застосунків" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../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 "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "build" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "cibuildwheel" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "distlib" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +msgstr "distutils" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "flit" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "hatch" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "пакування" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "pip" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "Pipenv" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "Pipfile" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "pipx" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "Це керівництво!" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "readme_renderer" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +#, fuzzy +#| msgid "setuptools" +msgid "Setuptools" +msgstr "setuptools" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "trove-classifiers" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "twine" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "virtualenv" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "Warehouse" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "wheel" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "buildout" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "conda" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "devpi" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "enscons" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "Hashdist" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "multibuild" + +#: ../source/key_projects.rst:546 +#, fuzzy +#| msgid "`pip-tools `_" +msgid "`GitHub `__" +msgstr "`pip-tools `_" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "pip-tools" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "piwheels" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "poetry" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +#, fuzzy +#| msgid "pypiserver" +msgid "pypiprivate" +msgstr "pypiserver" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "pypiserver" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "scikit-build" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +#, fuzzy +#| msgid "scikit-build" +msgid "scikit-build-core" +msgstr "scikit-build" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "shiv" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "zest.releaser" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "ensurepip" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +#, fuzzy +#| msgid "pypiserver" +msgid "http.server" +msgstr "pypiserver" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "venv" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "Новини" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "вересень 2019" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "серпень 2019" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "липень 2019" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "червень 2019" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "травень 2019" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "квітень 2019" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "березень 2019" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "лютий 2019" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "січень 2019" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "грудень 2018" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "листопад 2018" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "жовтень 2018" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "вересень 2018" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "серпень 2018" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "липень 2018" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "червень 2018" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "травень 2018" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "квітень 2018" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "березень 2018" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "лютий 2018" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "січень 2018" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "грудень 2017" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "листопад 2017" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "жовтень 2017" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "вересень 2017" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "серпень 2017" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "липень 2017" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "червень 2017" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "травень 2017" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "квітень 2017" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "березень 2017" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "лютий 2017" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +msgid "`Kivy `_" +msgstr "`Kivy `_" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "`Beeware `_" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "`Brython `_" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "`Flexx `_" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr ":gh:`shiv ` (потребує Python 3)" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +#, fuzzy +msgid "" +"`ActiveState ActivePython `_" +msgstr "`ActiveState ActivePython `_" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "`WinPython `_" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" +"`pyInstaller `_ - крос-" +"платформовий" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "`AppImage `_" + +#: ../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 "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "А як щодо..." + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "Безпека" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "Підсумок" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "дистрибутив" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "Назва розповсюджуваного пакунка, наприклад, 'django', 'pyramid'." + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "Реалізація мови та теґ версії" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "Наприклад, 'py27', 'py2', 'py3'." + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../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/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +#, fuzzy +#| msgid "Project name" +msgid "Subdirectory name" +msgstr "Назва проєкту" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#, fuzzy +#| msgid "``license``" +msgid "``licenses``" +msgstr "``license``" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +#, fuzzy +#| msgid "``license``" +msgid "``license_files``" +msgstr "``license``" + +#: ../source/specifications/binary-distribution-format.rst:266 +#, fuzzy +#| msgid "``LIB``" +msgid "``LICENSES``" +msgstr "``LIB``" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "ЧаПи" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "Додаток" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +#, fuzzy +msgid "Example" +msgstr "Приклади" + +#: ../source/specifications/build-details/index.rst:35 +#, fuzzy +#| msgid "Changes" +msgid "Changelog" +msgstr "Зміни" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "Специфікація" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Project" +msgid "*object*" +msgstr "Проєкт" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Serial versioning" +msgid "Schema version." +msgstr "Порядкове версіонування" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "enscons" +msgid "const" +msgstr "enscons" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Examples" +msgid "examples" +msgstr "Приклади" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +msgid "linux-x86\\_64" +msgstr "Наприклад, 'linux_x86_64', 'any'." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Subversion" +msgid "**version**" +msgstr "Subversion" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Version" +msgid "version\\_info" +msgstr "Version" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Release" +msgid "releaselevel" +msgstr "Випуск" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Mercurial" +msgid "serial" +msgstr "Mercurial" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "**Numbers**" +msgid "*number*" +msgstr "**Числа**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Additional resources" +msgid "additionalProperties" +msgstr "Додаткові матеріали" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Documentation types" +msgid "**implementation**" +msgstr "Типи документації" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +msgid "cpython" +msgstr "``description``" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "**Headings**" +msgid "**flags**" +msgstr "**Заголовки**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +msgid "extensions" +msgstr "Version" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +msgid "libpython" +msgstr "``description``" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "``dynamic``" +msgid "dynamic" +msgstr "``dynamic``" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "**Numbers**" +msgid "**headers**" +msgstr "**Числа**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "``Metadata-Version``" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "``Name``" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "``Version``" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "Усі інші поля необов'язкові." + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "Приклад::" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "Name" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "Version" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "Приклади::" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "Підсумок" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "Формат::" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "Частина ``type/subtype`` може містити лише кілька прийнятних значень:" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "``text/plain``" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "``text/x-rst``" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "``text/markdown``" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "Author" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "Author-email" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "Доглядач" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "Maintainer-email" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "License" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +#, fuzzy +#| msgid "Requirements files" +msgid "Requires" +msgstr "Файли requirements" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +#, fuzzy +#| msgid "Dependency Overrides" +msgid "Dependency Groups" +msgstr "Перевизначення залежностей" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +#, fuzzy +#| msgid "Dependency Overrides" +msgid "Dependency Group Include" +msgstr "Перевизначення залежностей" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +#, fuzzy +#| msgid "Package Index" +msgid "Package Building" +msgstr "Реєстр Пакунків" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +#, fuzzy +msgid "Installing Dependency Groups & Extras" +msgstr "Встановлення пакунків" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +#, fuzzy +#| msgid "Documentation types" +msgid "Reference Implementation" +msgstr "Типи документації" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +#, fuzzy +msgid "Names" +msgstr "Name" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +#, fuzzy +msgid "Versions" +msgstr "Version" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:248 +#, fuzzy +msgid "Python equivalent" +msgstr "Версія Python" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +#, fuzzy +msgid "``os_name``" +msgstr "``name``" + +#: ../source/specifications/dependency-specifiers.rst:252 +#, fuzzy +msgid ":py:data:`os.name`" +msgstr "``name``" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +#, fuzzy +msgid "``platform_version``" +msgstr "``version``" + +#: ../source/specifications/dependency-specifiers.rst:277 +#, fuzzy +msgid ":py:func:`platform.version()`" +msgstr "``version``" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:282 +#, fuzzy +msgid "``python_version``" +msgstr "``version``" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +#, fuzzy +#| msgid "Version Specifier" +msgid ":ref:`Version `" +msgstr "Специфікатор версії" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:286 +#, fuzzy +msgid "``python_full_version``" +msgstr "``python_requires``" + +#: ../source/specifications/dependency-specifiers.rst:287 +#, fuzzy +msgid ":py:func:`platform.python_version()`" +msgstr "``version``" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +#, fuzzy +msgid "``cpython``" +msgstr "``description``" + +#: ../source/specifications/dependency-specifiers.rst:294 +#, fuzzy +msgid "``implementation_version``" +msgstr "Реалізація мови та теґ версії" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +#, fuzzy +#| msgid "pyproject.toml" +msgid "``toml``" +msgstr "pyproject.toml" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +#, fuzzy +msgid "``dependency_groups``" +msgstr "Перевизначення залежностей" + +#: ../source/specifications/dependency-specifiers.rst:312 +#, fuzzy +msgid "``{\"test\"}``" +msgstr "``text/x-rst``" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "``pip install https://example.com/app-1.0.tgz``" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "``pip install https://example.com/app-1.0.whl``" + +#: ../source/specifications/direct-url.rst:51 +#, fuzzy +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" +"``pip install \"git+https://example.com/repo/" +"app.git#egg=app&subdirectory=setup\"``" + +#: ../source/specifications/direct-url.rst:52 +msgid "``pip install ./app``" +msgstr "``pip install ./app``" + +#: ../source/specifications/direct-url.rst:53 +msgid "``pip install file:///home/user/app``" +msgstr "``pip install file:///home/user/app``" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "``pip install -e ./app``" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "``pip install app``" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "``pip install app --no-index --find-links https://example.com/``" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "Git" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "Домашня сторінка" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "https://git-scm.com/" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "git" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "Mercurial" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "https://www.mercurial-scm.org/" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "hg" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "Bazaar" + +#: ../source/specifications/direct-url-data-structure.rst:199 +#, 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:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "bzr" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "Subversion" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "https://subversion.apache.org/" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "svn" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "Модель даних" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +#, fuzzy +#| msgid "distribution" +msgid "distro" +msgstr "дистрибутив" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "пакунок" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +#, fuzzy +#| msgid "Installing packages" +msgid "Python-specific package manager" +msgstr "Встановлення пакунків" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +#, fuzzy +#| msgid "PyPA specifications" +msgid "This specification is twofold." +msgstr "Специфікації PyPA" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +#, fuzzy +#| msgid "Create a new project." +msgid "Guide users towards virtual environments" +msgstr "Створіть новий проєкт." + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +#, fuzzy +#| msgid "Documentation types" +msgid "Implementation Notes" +msgstr "Типи документації" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +#, fuzzy +#| msgid "``pip install app``" +msgid "``pip install``" +msgstr "``pip install app``" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +#, fuzzy +#| msgid "``pip install -e ./app``" +msgid "``pip install --prefix=/some/path``" +msgstr "``pip install -e ./app``" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +#, fuzzy +#| msgid "``pip install -e ./app``" +msgid "``pip install --user``" +msgstr "``pip install -e ./app``" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "Авторське право" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +#, fuzzy +#| msgid "Installer" +msgid "Installers" +msgstr "Встановлювач" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +#, fuzzy +#| msgid "Documentation types" +msgid "Reference implementation in Python" +msgstr "Типи документації" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "Специфікації PyPA" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +#, fuzzy +#| msgid "Packaging tool recommendations" +msgid "Recommendations" +msgstr "Поради щодо засобу пакування" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +#, fuzzy +#| msgid "Here are some examples of compliant version numbers::" +msgid "Examples of valid license expressions:" +msgstr "Ось кілька прикладів сумісних номерів версій::" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +#, fuzzy +msgid "Names and normalization" +msgstr "Версія пакунку" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +#, fuzzy +msgid "Name normalization" +msgstr "Переклади" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +#, fuzzy +msgid "'py27', 'cp33'" +msgstr "Наприклад, 'py27', 'py2', 'py3'." + +#: ../source/specifications/platform-compatibility-tags.rst:21 +#, fuzzy +msgid "'cp32dmu', 'none'" +msgstr "Наприклад, 'cp33m', 'abi3', 'none'." + +#: ../source/specifications/platform-compatibility-tags.rst:23 +#, fuzzy +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +#, fuzzy +msgid "cp: CPython" +msgstr "``description``" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +#, fuzzy +msgid "linux_x86_64" +msgstr "Наприклад, 'linux_x86_64', 'any'." + +#: ../source/specifications/platform-compatibility-tags.rst:106 +#, fuzzy +msgid "``manylinux``" +msgstr "``manylinux1``" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "Інструмент" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "``manylinux1``" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "``manylinux2010``" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "``manylinux2014``" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "``manylinux_x_y``" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "``>=8.1.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "``>=19.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "``>=19.3``" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "``>=20.3``" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "auditwheel" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "``>=1.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "``>=2.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "``>=3.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "``>=3.3.0`` [#]_" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +#, fuzzy +msgid "``musllinux``" +msgstr "``manylinux1``" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +#, fuzzy +#| msgid "``version``" +msgid "``universal2``" +msgstr "``version``" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +#, fuzzy +#| msgid "``version``" +msgid "``universal``" +msgstr "``version``" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +#, fuzzy +#| msgid "``pip install app``" +msgid "``intel``" +msgstr "``pip install app``" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +#, fuzzy +#| msgid "Project name" +msgid "Project Status Markers" +msgstr "Назва проєкту" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +#, fuzzy +#| msgid "Installation format" +msgid "Installer semantics: none." +msgstr "Формат встановлення" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +#, fuzzy +#| msgid "Installer" +msgid "Installer semantics:" +msgstr "Встановлювач" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +#, fuzzy +msgid "``deprecated``" +msgstr "Перевизначення залежностей" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +#, fuzzy +#| msgid "pyproject.toml" +msgid "``pylock.toml`` Specification" +msgstr "pyproject.toml" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +#, fuzzy +#| msgid "Name" +msgid "File Name" +msgstr "Name" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +#, fuzzy +#| msgid "``version``" +msgid "``lock-version``" +msgstr "``version``" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +#, fuzzy +#| msgid "Requirements files" +msgid "**Required?**: yes" +msgstr "Файли requirements" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +#, fuzzy +#| msgid "Create a new project." +msgid "``environments``" +msgstr "Створіть новий проєкт." + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +#, fuzzy +msgid "``dependency-groups``" +msgstr "Перевизначення залежностей" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +#, fuzzy +#| msgid "pyproject.toml" +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "pyproject.toml" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +#, fuzzy +#| msgid "package" +msgid "``[[packages]]``" +msgstr "пакунок" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +#, fuzzy +msgid "``packages.name``" +msgstr "``name``" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +#, fuzzy +#| msgid "Package version" +msgid "``packages.version``" +msgstr "Версія пакунку" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +#, fuzzy +#| msgid "Installing packages" +msgid "The version of the package." +msgstr "Встановлення пакунків" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +#, fuzzy +#| msgid "``requires-python``" +msgid "``packages.requires-python``" +msgstr "``requires-python``" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +#, fuzzy +msgid "``[[packages.dependencies]]``" +msgstr "Перевизначення залежностей" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +#, fuzzy +#| msgid "Where the guide is deployed" +msgid "The time the file was uploaded." +msgstr "Куди це керівництво публікується" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +#, fuzzy +#| msgid "Package Index" +msgid "``packages.index``" +msgstr "Реєстр Пакунків" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +#, fuzzy +#| msgid "pyproject.toml" +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "pyproject.toml" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "Файл :file:`.pypirc`" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +#, fuzzy +#| msgid "The :file:`.pypirc` file" +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "Файл :file:`.pypirc`" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +#, fuzzy +#| msgid "pyproject.toml" +msgid "``pyproject.toml`` specification" +msgstr "pyproject.toml" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:134 +#, fuzzy +msgid "``authors``" +msgstr "``author``" + +#: ../source/specifications/pyproject-toml.rst:136 +#, fuzzy +msgid "``dependencies``" +msgstr "Перевизначення залежностей" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "``dynamic``" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:140 +#, fuzzy +msgid "``gui-scripts``" +msgstr "``scripts``" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +#, fuzzy +#| msgid "``name``" +msgid "``import-names``" +msgstr "``name``" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +#, fuzzy +msgid "``maintainers``" +msgstr "Доглядач" + +#: ../source/specifications/pyproject-toml.rst:148 +#, fuzzy +msgid "``optional-dependencies``" +msgstr "``dependencies``/``optional-dependencies``" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +#, fuzzy +#| msgid "PyPA specifications" +msgid "Legacy specification" +msgstr "Специфікації PyPA" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +#, fuzzy +#| msgid "Examples::" +msgid "Examples:" +msgstr "Приклади::" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +#, fuzzy +#| msgid "Example::" +msgid "Example:" +msgstr "Приклад::" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "Файл METADATA" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "Файл RECORD" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "Файл INSTALLER" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +#, fuzzy +#| msgid "Data schema" +msgid "PyPA schemas" +msgstr "Структура даних" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 "Installation format" +msgid "Package Installation Metadata" +msgstr "Формат встановлення" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +#, fuzzy +#| msgid "Python version" +msgid "Python Description Formats" +msgstr "Версія Python" + +#: ../source/specifications/section-reproducible-environments.rst:3 +#, fuzzy +#| msgid "Create a new project." +msgid "Reproducible Environments" +msgstr "Створіть новий проєкт." + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +#, fuzzy +msgid "Normalized Names" +msgstr "Переклади" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +#, fuzzy +#| msgid "Contents" +msgid "Clients" +msgstr "Зміст" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +#, fuzzy +msgid "HTML Serialization" +msgstr "Переклади" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +#, fuzzy +#| msgid "Project" +msgid "Project List" +msgstr "Проєкт" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +#, fuzzy +#| msgid "Project name" +msgid "Project Detail" +msgstr "Назва проєкту" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +#, fuzzy +msgid "JSON Serialization" +msgstr "Переклади" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +#, fuzzy +#| msgid "For example:" +msgid "As an example:" +msgstr "Наприклад:" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +#, fuzzy +#| msgid "Contents" +msgid "Content-Types" +msgstr "Зміст" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +#, fuzzy +#| msgid "Version" +msgid "Version + Format Selection" +msgstr "Version" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +#, fuzzy +#| msgid "Specifications" +msgid "Definitions" +msgstr "Специфікації" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +#, fuzzy +msgid "Version scheme" +msgstr "Version" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +#, fuzzy +#| msgid "Local version identifiers" +msgid "Public version identifiers" +msgstr "Ідентифікатори місцевих версій" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "Наприклад::" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +#, fuzzy +#| msgid "Pre-release versioning" +msgid "Pre-releases" +msgstr "Версіонування попередніх випусків" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +#, fuzzy +#| msgid "zest.releaser" +msgid "Post-releases" +msgstr "zest.releaser" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +#, fuzzy +msgid "Version epochs" +msgstr "Version" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +#, fuzzy +msgid "Normalization" +msgstr "Переклади" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +#, fuzzy +msgid "Integer Normalization" +msgstr "Переклади" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +#, fuzzy +#| msgid "Pre-release versioning" +msgid "Pre-release separators" +msgstr "Версіонування попередніх випусків" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +#, fuzzy +#| msgid "Pre-release versioning" +msgid "Pre-release spelling" +msgstr "Версіонування попередніх випусків" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +#, fuzzy +#| msgid "Pre-release versioning" +msgid "Post release spelling" +msgstr "Версіонування попередніх випусків" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +#, fuzzy +#| msgid "Local version identifiers" +msgid "Local version segments" +msgstr "Ідентифікатори місцевих версій" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +#, fuzzy +#| msgid "Here are some examples of compliant version numbers::" +msgid "Examples of compliant version schemes" +msgstr "Ось кілька прикладів сумісних номерів версій::" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +#, fuzzy +#| msgid "Serial versioning" +msgid "Simple \"major.minor\" versioning::" +msgstr "Порядкове версіонування" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +#, fuzzy +#| msgid "Date based versioning" +msgid "DVCS based version labels" +msgstr "Версіонування базоване на датах" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +#, fuzzy +#| msgid "Date based versioning" +msgid "Olson database versioning" +msgstr "Версіонування базоване на датах" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +#, fuzzy +#| msgid "Version" +msgid "Version matching" +msgstr "Version" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +#, fuzzy +#| msgid "Version Specifier" +msgid "Version exclusion" +msgstr "Специфікатор версії" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +#, fuzzy +#| msgid "For example::" +msgid "Remote URL examples::" +msgstr "Наприклад::" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +#, fuzzy +#| msgid "Project name" +msgid "Well-known Project URLs in Metadata" +msgstr "Назва проєкту" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +#, fuzzy +msgid "Label normalization" +msgstr "Переклади" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +#, fuzzy +msgid "Normalized" +msgstr "Переклади" + +#: ../source/specifications/well-known-project-urls.rst:76 +#, fuzzy +#| msgid "Home page" +msgid "``Homepage``" +msgstr "Домашня сторінка" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +#, fuzzy +#| msgid "Home page" +msgid "``homepage``" +msgstr "Домашня сторінка" + +#: ../source/specifications/well-known-project-urls.rst:78 +#, fuzzy +#| msgid "Home page" +msgid "``Home-page``" +msgstr "Домашня сторінка" + +#: ../source/specifications/well-known-project-urls.rst:80 +#, fuzzy +#| msgid "Home page" +msgid "``Home page``" +msgstr "Домашня сторінка" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +#, fuzzy +#| msgid "Additional tools" +msgid "Funding Information" +msgstr "Додаткові інструменти" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +#, fuzzy +msgid "Example behavior" +msgstr "Приклади" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"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/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "" + +#: ../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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "" + +#: ../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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +#, fuzzy +msgid "Installing \"Extras\"" +msgstr "Встановлення пакунків" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "Наступні кроки" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "**Вітаємо, ви запакували та розповсюдили Python-проєкт!** ✨ 🍰 ✨" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" +"Майте на увазі, що цей туторіал показав вам, як опублікувати свій пакунок до " +"Test PyPI, який не є постійним сховищем. Тестова система час від часу " +"видаляє пакунки та облікові записи. Краще використовувати TestPyPI для " +"тестування та експериментів, як у цьому туторіалі." + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" +"Коли ви будете готові завантажити справжній пакунок до Реєстру Python-" +"пакунків, ви можете зробити те ж саме, що і в цьому туторіалі, але з цими " +"важливими відмінностями:" + +#: ../source/tutorials/packaging-projects.rst:498 +#, fuzzy +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 "" +"Оберіть пам'ятну й унікальну назву для свого пакунку. Вам не потрібно " +"додавати своє ім'я користувача, як ви це робили в туторіалі." + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" +"Зареєструйте обліковий запис на https://pypi.org - запримітьте, що це два " +"окремих сервери, а дані для входу для тестового сервера не підходять до " +"основного." + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" +"Використайте ``twine upload dist/*`` аби опублікувати свій пакунок і введіть " +"облікові дані запису, який ви зареєстрували на справжньому PyPI. Тепер, " +"коли ви публікуєте пакунок як продакшн-версію, вам не потрібно вказувати ``--" +"repository``; пакунок буде опубліковано на https://pypi.org/ за " +"замовчуванням." + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" +"Встановіть свій пакунок зі справжнього PyPI за допомогою ``python3 -m pip " +"install [your-package]``." + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" +"На цьому етапі, якщо ви бажаєте почитати більше про пакування Python-" +"бібліотек, то ось що ви можете зробити:" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" + +#, fuzzy +#~ msgid "" +#~ "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" +#~ "serialization-01" +#~ msgstr "" +#~ "https://self-issued.info/docs/draft-jones-jose-jws-json-serialization.html" + +#, fuzzy +#~ msgid "" +#~ "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" +#~ msgstr "" +#~ "https://self-issued.info/docs/draft-jones-jose-json-private-key.html" + +#~ msgid "`Vagrant `_" +#~ msgstr "`Vagrant `_" + +#, fuzzy +#~| msgid "pyproject.toml" +#~ msgid "**Inspiration**: :ref:` pyproject-tool-table`" +#~ msgstr "pyproject.toml" + +#, fuzzy +#~| msgid "Distribution Package" +#~ msgid "Signing the distribution packages" +#~ msgstr "Дистриб'юторський пакет" + +#, fuzzy +#~| msgid "Additional tools" +#~ msgid "Additional file information" +#~ msgstr "Додаткові інструменти" + +#~ msgid "Wheel vs Egg" +#~ msgstr "Wheel чи Egg" + +#, fuzzy +#~ 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 "Installation tool recommendations" +#~ msgstr "Поради щодо засобу встановлення" + +#~ msgid "Packaging tool recommendations" +#~ msgstr "Поради щодо засобу пакування" + +#~ msgid "Here are some examples of compliant version numbers::" +#~ msgstr "Ось кілька прикладів сумісних номерів версій::" + +#~ msgid "Date based versioning" +#~ msgstr "Версіонування базоване на датах" + +#~ msgid "" +#~ "This is the simplest possible versioning scheme, and consists of a single " +#~ "number which is incremented every release." +#~ msgstr "" +#~ "Це найпростіша з можливих схем версіонування, яка складається з єдиного " +#~ "числа, яке збільшується при кожній публікації." + +#~ msgid "Pre-release versioning" +#~ msgstr "Версіонування попередніх випусків" + +#~ msgid "" +#~ "`Heroku `_" +#~ msgstr "" +#~ "`Heroku `_" + +#~ msgid "" +#~ "`Google App Engine `_" +#~ msgstr "" +#~ "`Google App Engine `_" + +#~ msgid "`PythonAnywhere `_" +#~ msgstr "`PythonAnywhere `_" + +#~ msgid "`OpenShift `_" +#~ msgstr "`OpenShift `_" + +#~ msgid "``url``" +#~ msgstr "``url``" + +#~ msgid "``author``" +#~ msgstr "``author``" + +#~ msgid "``project_urls``" +#~ msgstr "``project_urls``" + +#~ msgid "``python_requires``" +#~ msgstr "``python_requires``" + +#~ msgid "``console_scripts``" +#~ msgstr "``console_scripts``" + +#~ msgid "Rationale" +#~ msgstr "Обґрунтування" + +#~ msgid "This document has been placed into the public domain." +#~ msgstr "Цей документ передано у суспільне надбання." + +#, fuzzy +#~ msgid ":ref:`declaring-build-dependencies`" +#~ msgstr "``dependencies``/``optional-dependencies``" + +#~ msgid "Read about :doc:`/guides/packaging-binary-extensions`." +#~ msgstr "Прочитайте про :doc:`/guides/packaging-binary-extensions`." + +#, fuzzy +#~| msgid "Packaging tool recommendations" +#~ msgid "Current recommendation" +#~ msgstr "Поради щодо засобу пакування" + +#~ msgid ":file:`setup.cfg`" +#~ msgstr ":file:`setup.cfg`" + +#~ msgid ":file:`README`" +#~ msgstr ":file:`README`" + +#~ msgid ":file:`README.txt`" +#~ msgstr ":file:`README.txt`" + +#~ msgid ":file:`README.rst` (Python 3.7+ or setuptools 0.6.27+)" +#~ msgstr ":file:`README.rst` (Python 3.7+ або setuptools 0.6.27+)" + +#~ msgid ":file:`README.md` (setuptools 36.4.0+)" +#~ msgstr ":file:`README.md` (setuptools 36.4.0+)" + +#~ msgid ":file:`pyproject.toml` (setuptools 43.0.0+)" +#~ msgstr ":file:`pyproject.toml` (setuptools 43.0.0+)" + +#~ msgid ":file:`MANIFEST.in`" +#~ msgstr ":file:`MANIFEST.in`" + +#~ msgid ":file:`MANIFEST.in` commands" +#~ msgstr "Команди в :file:`MANIFEST.in`" + +#~ msgid "Command" +#~ msgstr "Команда" + +#~ msgid ":samp:`include {pat1} {pat2} ...`" +#~ msgstr ":samp:`include {pat1} {pat2} ...`" + +#~ msgid ":samp:`exclude {pat1} {pat2} ...`" +#~ msgstr ":samp:`exclude {pat1} {pat2} ...`" + +#~ msgid ":samp:`recursive-include {dir-pattern} {pat1} {pat2} ...`" +#~ msgstr ":samp:`recursive-include {dir-pattern} {pat1} {pat2} ...`" + +#~ msgid ":samp:`recursive-exclude {dir-pattern} {pat1} {pat2} ...`" +#~ msgstr ":samp:`recursive-exclude {dir-pattern} {pat1} {pat2} ...`" + +#~ msgid ":samp:`global-include {pat1} {pat2} ...`" +#~ msgstr ":samp:`global-include {pat1} {pat2} ...`" + +#~ msgid ":samp:`global-exclude {pat1} {pat2} ...`" +#~ msgstr ":samp:`global-exclude {pat1} {pat2} ...`" + +#~ msgid ":samp:`graft {dir-pattern}`" +#~ msgstr ":samp:`graft {dir-pattern}`" + +#~ msgid ":samp:`prune {dir-pattern}`" +#~ msgstr ":samp:`prune {dir-pattern}`" + +#~ msgid "Installing pip" +#~ msgstr "Встановлення pip" + +#~ msgid "Learn more" +#~ msgstr "Дізнатися більше" + +#, fuzzy +#~ msgid "_`https://bazaar.canonical.com` *(Not responding as of 5/2023)*" +#~ msgstr "https://bazaar.canonical.com" + +#~ msgid "" +#~ "It may also be known that project A follows semantic versioning, and that " +#~ "v2 of 'A' will indicate a break in compatibility, so it makes sense to " +#~ "not allow v2:" +#~ msgstr "" +#~ "Крім того, може бути відомо, що проєкт A використовує семантичне " +#~ "версіонування і що 'A' v2 означає несумісну зміну, тож має сенс не " +#~ "дозволяти v2:" + +#~ msgid ":term:`Wheel` has an :pep:`official PEP <427>`. :term:`Egg` did not." +#~ msgstr ":term:`Wheel` має :pep:`офіційний PEP <427>`. :term:`Egg` ні." + +#, fuzzy +#~ msgid "" +#~ "Circumstantially, in some cases, wheels can be used as an importable " +#~ "runtime format, although :pep:`this is not officially supported at this " +#~ "time <427#is-it-possible-to-import-python-code-directly-from-a-wheel-" +#~ "file>`." +#~ msgstr "" +#~ "За певних обставин, у деяких випадках wheels можна використовувати як " +#~ "імпортований формат середовища виконання, хоча :pep:`наразі це офіційно " +#~ "не підтримується <427#is-it-possible-to-import-python-code-directly-from- " +#~ "a-wheel-file>`." + +#~ msgid "" +#~ "To only count downloads from pip, filter on the " +#~ "``details.installer.name`` column." +#~ msgstr "" +#~ "Щоб підрахувати лише завантаження з pip, відфільтруйте стовпець " +#~ "``details.installer.name``." + +#~ msgid "Debian/Ubuntu" +#~ msgstr "Debian/Ubuntu" + +#~ msgid "https://bazaar.canonical.com" +#~ msgstr "https://bazaar.canonical.com" + +#~ msgid "" +#~ "Read more about using :ref:`setuptools` to package libraries in :doc:`/" +#~ "guides/distributing-packages-using-setuptools`." +#~ msgstr "" +#~ "Прочитайте більше про використання :ref:`setuptools` для пакування " +#~ "бібліотек в :doc:`/guides/distributing-packages-using-setuptools`." + +#~ msgid "" +#~ "Consider alternatives to :ref:`setuptools` such " +#~ "as :ref:`flit`, :ref:`hatch`, and :ref:`poetry`." +#~ msgstr "" +#~ "Розгляньте альтернативи до :ref:`setuptools` такі " +#~ "як :ref:`flit`, :ref:`hatch` і :ref:`poetry`." + +#~ msgid "`Poetry `_" +#~ msgstr "`Poetry `_" + +#~ msgid "" +#~ "https://self-issued.info/docs/draft-ietf-jose-json-web-signature.html" +#~ msgstr "" +#~ "https://self-issued.info/docs/draft-ietf-jose-json-web-signature.html" + +#~ msgid "https://self-issued.info/docs/draft-ietf-jose-json-web-key.html" +#~ msgstr "https://self-issued.info/docs/draft-ietf-jose-json-web-key.html" + +#~ msgid "2014-11-11" +#~ msgstr "11.11.2014" + +#~ msgid "2015-09-17" +#~ msgstr "17.09.2015" + +#~ msgid "Fedora 21:" +#~ msgstr "Fedora 21:" + +#~ msgid "For Python 2.7" +#~ msgstr "Для Python 2.7" + +#~ msgid "Done." +#~ msgstr "Готово." + +#~ msgid "For Python 3.4" +#~ msgstr "Для Python 3.4" + +#~ msgid "For Python 3.5" +#~ msgstr "Для Python 3.5" + +#~ msgid "bento" +#~ msgstr "bento" + +#~ msgid "`Enthought Canopy `_" +#~ msgstr "`Enthought Canopy `_" diff --git a/locales/vi/LC_MESSAGES/messages.po b/locales/vi/LC_MESSAGES/messages.po new file mode 100644 index 000000000..1bf82d356 --- /dev/null +++ b/locales/vi/LC_MESSAGES/messages.po @@ -0,0 +1,27012 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# Lenny Tran , 2024, 2025. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: 2025-09-23 05:02+0000\n" +"Last-Translator: Lenny Tran \n" +"Language-Team: Vietnamese \n" +"Language: vi\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=1; plural=0;\n" +"X-Generator: Weblate 5.14-dev\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "Đóng góp cho chỉ dẫn này" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "" +"|PyPUG| Chào mừng các nhà đóng góp! Có nhiều cách mà bạn có thể giúp đỡ " +"chúng tôi, bao gồm:" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "Đọc hướng dẫn và gửi phản hồi" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "Đánh giá những đóng góp mới" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "Sửa đổi nội dung hiện có" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "Viết nội dung mới" + +#: ../source/contribute.rst:14 +msgid "Translating the guide" +msgstr "Dịch bản hướng dẫn" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" +"Hầu hết công việc trên |PyPUG| diễn ra trên `GitHub repository của dự án`__. " +"Để bắt đầu, hãy xem qua danh sách `open issues`__ và `pull requests`__. Nếu " +"bạn dự định viết hoặc chỉnh sửa hướng dẫn, vui lòng đọc :ref:`styleguide " +"`." + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" +"Bằng việc đóng góp cho |PyPUG|, bạn được kỳ vọng sẽ tuân theo `Quy tắc ứng " +"xử`__ của PSF." + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "Loại tài liệu" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" +"Dự án này bao gồm bốn loại tài liệu khác nhau với những mục đích cụ thể. Dự " +"án mong muốn tuân theo `quy trình Diátaxis`_ để tạo tài liệu chất lượng. Khi " +"đề xuất bổ sung mới cho dự án, vui lòng chọn loại tài liệu thích hợp." + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "Các chỉ dẫn" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" +"Các chỉ dẫn tập trung vào việc dạy cho người đọc những khái niệm mới bằng " +"cách hoàn thành mục tiêu. Các hướng dẫn thể hiện các bước thực hiện một cách " +"tuần tự. Chúng không bao gồm các cảnh báo hoặc thông tin không liên quan. " +"`example tutorial-style document`_." + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "Hướng dẫn" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" +"Hướng dẫn tập trung vào việc hoàn thành một nhiệm vụ cụ thể và có thể cần có " +"một số mức độ kiến thức cần thiết trước đó. Những nội dung này tương tự như " +"chỉ dẫn nhưng có trọng tâm hẹp và rõ ràng, đồng thời có thể cung cấp nhiều " +"cảnh báo và thông tin bổ sung nếu cần. Họ cũng có thể thảo luận về nhiều " +"cách tiếp cận để hoàn thành nhiệm vụ. :doc:`example guide-style document " +"` ." + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "Thảo luận" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" +"Các cuộc thảo luận tập trung vào việc hiểu biết và thông tin. Chúng khám phá " +"một chủ đề cụ thể mà không có mục tiêu cụ thể nào cả. :doc:`example " +"discussion-style document `" + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "Các thông số kỹ thuật" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" +"Thông số kỹ thuật là tài liệu tham khảo tập trung vào việc ghi lại một cách " +"toàn diện giao diện đã được thống nhất về khả năng tương tác giữa các công " +"cụ đóng gói. :doc:`example specification-style document`." + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "Những bản dịch" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" +"Chúng tôi sử dụng `Weblate`_ để quản lý bản dịch của dự án này. Vui lòng " +"truy cập `packaging.python.org`_ trên Weblate để đóng góp." + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "" +"Nếu bạn gặp sự cố khi đang thực hiện bản dịch, vui lòng mở một vấn đề trên " +"`GitHub`_." + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "" +"Bất kỳ bản dịch nào của dự án này nên theo sau `reStructuredText syntax`_." + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "Thêm một ngôn ngữ" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" +"Nếu ngôn ngữ của bạn không được liệt kê trên `packaging.python.org`_, nhấp " +"vào nút :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "Theo cú pháp reStructuredText" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" +"Nếu bạn không quen với cú pháp reStructuredText (RST), vui lòng đọc `this " +"guide`_ trước khi dịch trên Weblate." + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "**Không dịch trực tiếp văn bản tham khảo**" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "Khi dịch văn bản tham khảo, vui lòng không dịch trực tiếp." + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "Sai: Dịch trực tiếp văn bản sau:" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" +"Đúng: Dịch văn bản sau sang ngôn ngữ của bạn và thêm tài liệu tham khảo gốc:" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "Xây dựng hướng dẫn tại địa phương" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" +"Mặc dù không bắt buộc phải đóng góp, nhưng việc xây dựng hướng dẫn này tại " +"địa phương có thể hữu ích để kiểm tra các thay đổi của bạn. Để xây dựng " +"hướng dẫn này tại địa phương, bạn cần:" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr "" +":doc:`Nox `. Bạn có thể cài đặt hoặc nâng cấp nox bằng cách sử " +"dụng ``pip``:" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" +"Python 3.11. Các tập lệnh xây dựng của chúng tôi thường được thử nghiệm với " +"Python 3.11 only. See the :doc:`Hitchhiker's Guide to Python installation " +"instructions ` để cài đặt Python 3.11 " +"trên hệ điều hành của bạn." + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "" +"Để xây dựng hướng dẫn, hãy chạy lệnh shell sau trong thư mục gốc của dự án:" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" +"Sau khi quá trình hoàn tất, bạn có thể tìm thấy HTML output trong đường dẫn " +"``./build/html``. Bạn có thể mở tệp ``index.html`` để xem hướng dẫn trong " +"trình duyệt web, nhưng bạn nên sử dụng máy chủ HTTP để sử dụng cho việc " +"hướng dẫn." + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" +"Bạn có thể xây dựng hướng dẫn và phục vụ nó thông qua một máy chủ HTTP sử " +"dụng lệnh sau:" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "Hướng dẫn có thể được truy cập qua http://localhost:8000." + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "Nơi hướng dẫn được triển khai" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" +"Hướng dẫn được triển khai thông qua ReadTheDocs và cấu hình phát hành tại " +"https://readthedocs.org/projects/python-packaging-user-guide/. Hướng dẫn " +"được cung cấp từ một tên miền tùy chỉnh và được bảo vệ bởi Fast.ly." + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "Hướng dẫn phong cách" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" +"Hướng dẫn về phong cách này đưa ra các khuyến nghị về cách bạn nên viết |" +"PyPUG|. Vui lòng xem qua trước khi bắt đầu viết. Bằng cách tuân thủ hướng " +"dẫn về phong cách, những đóng góp của bạn sẽ góp phần tạo nên một tổng thể " +"thống nhất và giúp dự án dễ dàng tiếp nhận hơn." + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "Mục đích" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" +"Mục đích của |PyPUG| là trở thành nguồn tài nguyên có thẩm quyền về cách " +"đóng gói, xuất bản và cài đặt các dự án Python bằng các công cụ hiện tại." + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "Phạm vi" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "" +"Hướng dẫn này nhằm mục đích trả lời các câu hỏi và giải quyết vấn đề bằng " +"những khuyến nghị chính xác và tập trung." + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" +"Hướng dẫn này không nhằm mục đích cung cấp đầy đủ thông tin và không thay " +"thế tài liệu hướng dẫn của từng dự án. Ví dụ, pip có hàng tá lệnh, tùy chọn " +"và thiết lập. Tài liệu hướng dẫn pip mô tả chi tiết từng lệnh, trong khi " +"hướng dẫn này chỉ mô tả các phần của pip cần thiết để hoàn thành các tác vụ " +"cụ thể được mô tả trong hướng dẫn này." + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "Đối tượng" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "Đối tượng của hướng dẫn này là bất kỳ ai sử dụng Python với các gói." + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" +"Đừng quên rằng cộng đồng Python rất lớn và thân thiện. Người đọc có thể " +"không cùng độ tuổi, giới tính, trình độ học vấn, văn hóa, v.v. với bạn, " +"nhưng họ xứng đáng được tìm hiểu về đóng gói nhiều như bạn vậy." + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" +"Đặc biệt, cần lưu ý rằng không phải tất cả những người sử dụng Python đều tự " +"coi mình là lập trình viên. Đối tượng của hướng dẫn này bao gồm các nhà " +"thiên văn học, họa sĩ, sinh viên, cũng như các nhà phát triển phần mềm " +"chuyên nghiệp." + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "Giọng nói và âm điệu" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" +"Khi viết hướng dẫn này, hãy cố gắng viết bằng giọng văn dễ hiểu và khiêm " +"tốn, ngay cả khi bạn có tất cả câu trả lời." + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" +"Hãy tưởng tượng bạn đang làm việc trên một dự án Python với một người mà bạn " +"biết là thông minh và có kỹ năng. Bạn thích làm việc với họ và họ cũng thích " +"làm việc với bạn. Người đó đã hỏi bạn một câu hỏi và bạn biết câu trả lời. " +"Bạn sẽ trả lời thế nào? *Đó* chính là cách bạn nên viết hướng dẫn này." + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" +"Đây là một cách kiểm tra nhanh: hãy thử đọc to để cảm nhận giọng văn và ngữ " +"điệu của bài viết. Nó nghe giống như bạn sẽ nói hay giống như bạn đang diễn " +"một vai diễn hoặc đang thuyết trình? Cứ thoải mái sử dụng các từ rút gọn và " +"đừng lo lắng về việc tuân thủ các quy tắc ngữ pháp cầu kỳ. Bạn được phép kết " +"thúc câu bằng một giới từ, nếu bạn muốn." + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" +"Khi viết hướng dẫn, hãy điều chỉnh giọng điệu cho phù hợp với mức độ nghiêm " +"túc và khó khăn của chủ đề. Nếu bạn đang viết hướng dẫn giới thiệu, việc nói " +"đùa là bình thường, nhưng nếu bạn đang đề cập đến một khuyến nghị bảo mật " +"nhạy cảm, bạn nên tránh nói đùa hoàn toàn." + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "Các quy ước và cơ chế" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "**Viết cho người đọc**" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" +"Khi đưa ra khuyến nghị hoặc các bước cần thực hiện, hãy xưng hô với người " +"đọc là *bạn* hoặc sử dụng cách nói mệnh lệnh." + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "Sai: Để cài đặt, người dùng chạy…" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "Đúng: Bạn có thể cài đặt bằng cách chạy…" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "Đúng: Để cài đặt, hãy chạy…" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "**Nêu giả định**" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" +"Tránh đưa ra những giả định không rõ ràng. Đọc trên web đồng nghĩa với việc " +"bất kỳ trang nào của hướng dẫn cũng có thể là trang đầu tiên mà người đọc " +"nhìn thấy. Nếu bạn định đưa ra giả định, hãy nói rõ bạn sẽ đưa ra những giả " +"định nào." + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "**Tham chiếu chéo rộng rãi**" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" +"Lần đầu tiên bạn đề cập đến một công cụ hoặc phương pháp, hãy liên kết đến " +"phần hướng dẫn đề cập đến công cụ hoặc phương pháp đó, hoặc liên kết đến một " +"tài liệu liên quan khác. Lưu tìm kiếm cho người đọc." + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "**Tôn trọng các thông lệ đặt tên**" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" +"Khi đặt tên cho công cụ, trang web, người và danh từ riêng khác, hãy sử dụng " +"chữ viết hoa theo quy chuẩn mà nhà phát hành mong muốn." + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "Sai: Pip sử dụng…" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "Đúng: pip sử dụng…" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "Sai: …được lưu trữ trên github." + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "Đúng: …được lưu trữ trên GitHub." + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "**Sử dụng phong cách trung tính về giới tính**" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" +"Thông thường, bạn sẽ xưng hô trực tiếp với người đọc bằng *you*, *your* và " +"*yours*. Nếu không, hãy sử dụng các đại từ trung tính như *they*, *their* và " +"*theirs* hoặc tránh dùng đại từ một cách hoàn toàn." + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "Sai: Người bảo trì tải tệp lên. Sau đó, anh ta…" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "Phải: Người bảo trì tải tệp lên. Sau đó, họ…" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "Đúng: Người bảo trì tải tệp lên. Sau đó, người bảo trì…" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "**Tiêu đề**" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" +"Viết tiêu đề sử dụng các từ mà người đọc đang tìm kiếm. Một cách hay để làm " +"điều này là đặt tiêu đề hoàn thành một câu hỏi ngụ ý. Ví dụ, người đọc có " +"thể muốn biết *Làm thế nào để cài đặt MyLibrary?*, vậy một tiêu đề tốt có " +"thể là *Cài đặt MyLibrary*." + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" +"Trong tiêu đề phần, hãy sử dụng cách viết hoa chữ cái đầu câu. Nói cách " +"khác, hãy viết tiêu đề như cách bạn viết một câu thông thường." + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "Sai: Những điều bạn nên biết về Python" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "Đúng: Những điều bạn nên biết về Python" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "**Chữ số**" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" +"Trong phần thân bài, hãy viết các số từ một đến chín dưới dạng chữ. Đối với " +"các số khác hoặc số trong bảng, hãy sử dụng chữ số." + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "Triển khai ứng dụng Python" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "Trạng thái trang" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "Chưa hoàn thành" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "Đã xem xét lần cuối" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "24-08-2021" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "Tổng quan" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "Hỗ trợ nhiều nền tảng phần cứng" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "Đóng gói và cài đặt hệ điều hành" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" +"`Pynsist `__ là một công cụ đóng gói các " +"chương trình Python cùng với trình thông dịch Python thành một trình cài đặt " +"duy nhất dựa trên NSIS. Trong hầu hết các trường hợp, việc đóng gói chỉ yêu " +"cầu người dùng chọn một phiên bản trình thông dịch Python và khai báo các " +"phụ thuộc của chương trình. Công cụ này tải xuống trình thông dịch Python " +"được chỉ định cho Windows và đóng gói nó cùng với tất cả các phụ thuộc trong " +"một trình cài đặt thực thi Windows duy nhất." + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" +"Chương trình đã cài đặt có thể được khởi động từ một phím tắt mà trình cài " +"đặt thêm vào menu bắt đầu. Chương trình sử dụng trình thông dịch Python được " +"cài đặt trong thư mục ứng dụng, độc lập với bất kỳ cài đặt Python nào khác " +"trên máy tính." + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" +"Một lợi thế lớn của Pynsist là các gói Windows có thể được xây dựng trên " +"Linux. Có một số ví dụ cho các loại chương trình khác nhau (console, GUI) " +"trong tài liệu :any:`documentation `. Công cụ này được phát " +"hành theo giấy phép MIT." + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "Gói ứng dụng" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" +"`py2exe `__ là một tiện ích mở rộng " +"distutils cho phép xây dựng các chương trình thực thi Windows độc lập (32-" +"bit và 64-bit) từ các tập lệnh Python. Các phiên bản Python có trong chu kỳ " +"phát triển chính thức đều được hỗ trợ (tham khảo `Trạng thái các nhánh " +"Python`__). py2exe có thể xây dựng các tệp thực thi console và các tệp thực " +"thi Windows (GUI). Việc xây dựng các dịch vụ Windows và máy chủ COM DLL/EXE " +"có thể hoạt động nhưng nó không được hỗ trợ tích cực. Tiện ích mở rộng " +"distutils được phát hành theo giấy phép MIT và Giấy phép Công cộng Mozilla " +"2.0." + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" +"`py2app `__ là lệnh setuptools của Python " +"cho phép bạn tạo các gói ứng dụng và plugin macOS độc lập từ các tập lệnh " +"Python. Lưu ý rằng py2app PHẢI được sử dụng trên macOS để xây dựng ứng dụng, " +"nó không thể tạo ứng dụng Mac trên các nền tảng khác. py2app được phát hành " +"theo giấy phép MIT." + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "" + +#: ../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 +msgid "What is a source distribution?" +msgstr "" + +#: ../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 +msgid "What about eggs?" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python setup.py install``" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python -m pip install --editable .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:104 +msgid "``python -m twine register dist/*.whl`` [#not-pypi]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr "" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +msgid "Complete" +msgstr "" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +msgid "Versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +msgid "Calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +msgid "Other schemes" +msgstr "" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 ../source/flow.rst:143 +msgid "" +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../source/glossary.rst:3 +msgid "Glossary" +msgstr "" + +#: ../source/glossary.rst:8 +msgid "Binary Distribution" +msgstr "Phân phối nhị phân" + +#: ../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 :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "Nhập gói" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +msgid "Installed Project" +msgstr "" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +msgid "Project Root Directory" +msgstr "" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "" + +#: ../source/glossary.rst:257 +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:260 +msgid "Pyproject Metadata" +msgstr "" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +msgid "Pyproject Metadata Key" +msgstr "" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "" + +#: ../source/glossary.rst:344 +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:348 +msgid "Root License Directory" +msgstr "" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +msgid "Wheel Project" +msgstr "" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "" +"https://files.pythonhosted.org/packages/eb/" +"45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" +"sampleproject-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "" +"https://files.pythonhosted.org/packages/56/0a/" +"178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" +"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +msgid "" +"https://files.pythonhosted.org/packages/" +"63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" +"sampleproject_nomura-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +msgid "Creating the package" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +msgid "``pyproject.toml``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +msgid "Installing the package with ``pipx``" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +msgid "Conclusion" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +msgid "1. Install twine" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +msgid "Dropping a Python version" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:89 +msgid ":ref:`proxpi`" +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +msgid ":ref:`flaskpypiproxy`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:108 +msgid "openSUSE" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:118 +msgid "Debian/Ubuntu and derivatives" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:2 +msgid "Install packages in a virtual environment using pip and venv" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +msgid "Install packages using pip" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +msgid "Install extras" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +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/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python -m build``" +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:126 +msgid "``python -m build --no-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:127 +msgid "``python -m pip install --no-build-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:5 +msgid "Packaging binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:8 +msgid "2013-12-08" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../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 "" +"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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +msgid "Installation" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:10 +msgid "2014-12-24" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:36 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:8 +msgid "2015-12-03" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:10 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:233 +msgid "``appveyor-sample/build.cmd``" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:5 +msgid "Tool recommendations" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:7 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +msgid "Installing packages" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +msgid "Building distributions" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:313 +msgid "setuptools" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:317 +msgid "uv-build" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "2.2.0" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "0.7.19" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "``license`` (giấy phép)" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" +"Định dạng mới cho ``license`` hợp lệ :term:`SPDX license expression ` bao gồm một hay nhiều :term:`license identifiers `. Giấy phép đầy đủ sẵn có tại `SPDX license list page " +"`_. Phiên bản danh sách được hỗ trợ là 3.17 hoặc bất kỳ " +"phiên bản tương thích nào mới hơn." + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" +"Nếu bạn gặp lỗi biên dịch khiến ``license`` phải là dict/table, thì chương " +"trình biên dịch của bạn chưa hỗ trợ định dạng mới. Xem `above section " +"`_ để biết thêm ngữ cảnh. Định dạng lỗi thời " +"hiện đã được `mô tả trong PEP 621 `__." + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"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 "" +"Theo nguyên tắc chung, tốt nhất là nên sử dụng giấy phép chuẩn, được nhiều " +"người biết đến, vừa để tránh nhầm lẫn vừa vì một số tổ chức tránh sử dụng " +"phần mềm có giấy phép không được chấp thuận." + +#: ../source/guides/writing-pyproject-toml.rst:353 +#, fuzzy +#| msgid "" +#| "If your project is licensed with a license that doesn't have an existing " +#| "SPDX identifier, you can create a custom one in format ``LicenseRef-" +#| "[idstring]``. The custom identifiers must follow the SPDX specification, " +#| "`clause 10.1 `_ of the version 2.2 or any later " +#| "compatible one." +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" +"Nếu dự án của bạn được cấp phép theo giấy phép chưa có mã định danh SPDX, " +"bạn có thể tạo mã định danh tùy chỉnh theo định dạng ``LicenseRef-" +"[idstring]``. Mã định danh tùy chỉnh phải tuân theo đặc tả SPDX, điều khoản " +"10.1 ``_ của phiên bản 2.2 hoặc bất kỳ phiên bản tương thích " +"nào mới hơn." + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "``license-files`` (các tệp giấy phép)" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" +"Đây là danh sách các tệp giấy phép và tệp chứa thông tin pháp lý khác mà bạn " +"muốn phân phối cùng với gói của bạn." + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "Các mẫu glob phải tuân theo đặc tả sau:" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" +"Các ký tự chữ và số, dấu gạch dưới (``_``), dấu gạch nối (``-``) và dấu chấm " +"(``.``) sẽ được khớp nguyên văn." + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" +"Các ký tự đặc biệt: ``*``, ``?``, ``**`` và phạm vi ký tự: [] được hỗ trợ." + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "Dấu phân cách đường dẫn phải là ký tự gạch chéo (``/``)." + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" +"Các mẫu liên quan đến thư mục chứa :file:`pyproject.toml` và do đó không " +"được bắt đầu bằng ký tự gạch chéo." + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "Không được sử dụng chỉ báo thư mục cha (``..``)." + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "Mỗi glob phải khớp với ít nhất một tệp." + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" +"Đường dẫn theo nghĩa đen là các glob hợp lệ. Bất kỳ ký tự hoặc chuỗi ký tự " +"nào không được đề cập trong đặc tả này đều không hợp lệ." + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "``keywords`` (các từ khóa)" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" +"Điều này sẽ giúp hộp tìm kiếm của PyPI gợi ý dự án của bạn khi mọi người tìm " +"kiếm các từ khóa này." + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "``classifiers`` (bộ phân loại)" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" +"Danh sách các bộ phân loại PyPI áp dụng cho dự án của bạn. Kiểm tra trong " +"`full list of possibilities `_." + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" +"Mặc dù danh sách các bộ phân loại thường được sử dụng để khai báo phiên bản " +"Python mà một dự án hỗ trợ, thông tin này chỉ được sử dụng để tìm kiếm và " +"duyệt các dự án trên PyPI, chứ không phải để cài đặt dự án. Để thực sự hạn " +"chế các phiên bản Python mà một dự án có thể được cài đặt, hãy sử dụng đối " +"số :ref:`requires-python`." + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" +"Để ngăn chặn việc tải gói lên PyPI, hãy sử dụng trình phân loại đặc biệt " +"``Private :: Do Not Upload``. PyPI sẽ luôn từ chối các gói có trình phân " +"loại bắt đầu bằng ``Private ::``." + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "``urls`` (các đường dẫn)" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" +"Danh sách các URL liên quan đến dự án của bạn, được hiển thị ở thanh bên " +"trái của trang dự án PyPI." + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" +"Xem :ref:`well-known-labels` để biết danh sách các nhãn mà PyPI và các công " +"cụ đóng gói khác đặc biệt nhận biết cùng với `PyPI's project metadata docs " +"`_ để biết cách xử lý " +"URL cụ thể của PyPI." + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" +"Lưu ý rằng nếu nhãn chứa khoảng trắng, nhãn cần được trích dẫn, ví dụ: " +"``Website = \"https://example.com\"`` nhưng ``\"Trang web chính thức\" = " +"\"https://example.com\"``." + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" +"Người dùng được khuyên nên sử dụng :ref:`well-known-labels` cho URL dự án " +"của họ khi thích hợp, vì siêu dữ liệu người dùng (như chỉ mục gói) có thể " +"chuyên biệt hóa cách trình bày của họ." + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" +"Ví dụ, trong siêu dữ liệu sau, ``MyHomepage`` và ``\"Download Link\"`` không " +"phải là nhãn được biết đến rộng rãi, do đó chúng sẽ được hiển thị nguyên văn:" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" +"Trong khi đó, trong siêu dữ liệu này, ``HomePage`` và ``Download`` đều có " +"các từ tương đương nổi tiếng (``homepage`` và ``download``) và có thể được " +"trình bày theo ngữ nghĩa đó (lần lượt là trang chủ của dự án và vị trí tải " +"xuống bên ngoài)." + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "Các plugin nâng cao" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" +"Một số gói có thể được mở rộng thông qua plugin. Ví dụ như Pytest_ và " +"Pygments_. Để tạo một plugin như vậy, bạn cần khai báo nó trong một bảng con " +"của ``[project.entry-points]`` như sau:" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "Xem :ref:`Plugin guide ` để biết thêm thông tin" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "Một ví dụ đầy đủ" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" +"Hãy suy nghĩ cẩn trọng trước khi áp dụng giới hạn trên như ``requires-python " +"= \"<= 3.10\"`` ở đây. `This blog post `_ chứa " +"một số thông tin liên quan đến các vấn đề có thể xảy ra." + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" +"flit-core `does not yet `_ trong các biểu thức giấy phép " +"SPDX." + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +msgid "`Kivy `_" +msgstr "" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "Subdirectory name" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +msgid "``licenses``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*object*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Schema version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "examples" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "version\\_info" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*number*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**implementation**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**flags**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**headers**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +msgid "Package Building" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +msgid "Reference Implementation" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +msgid ":ref:`Version `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +msgid "``toml``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +msgid "``dependency_groups``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +msgid "Installers" +msgstr "" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +msgid "Reference implementation in Python" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +msgid "Names and normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +msgid "Name normalization" +msgstr "" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +msgid "Project Status Markers" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +msgid "Installer semantics: none." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +msgid "Installer semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +msgid "``deprecated``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +#, fuzzy +#| msgid "Specifications" +msgid "``pylock.toml`` Specification" +msgstr "Các thông số kỹ thuật" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +msgid "``lock-version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +msgid "**Required?**: yes" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +msgid "``environments``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +msgid "``dependency-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +msgid "``[[packages]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +msgid "``packages.version``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +msgid "The version of the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +msgid "``[[packages.dependencies]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +msgid "The time the file was uploaded." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +msgid "``packages.index``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +msgid "``import-names``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +#, fuzzy +#| msgid "Specifications" +msgid "Legacy specification" +msgstr "Các thông số kỹ thuật" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +msgid "Examples:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +msgid "Example:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +msgid "PyPA schemas" +msgstr "" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +msgid "Python Description Formats" +msgstr "" + +#: ../source/specifications/section-reproducible-environments.rst:3 +msgid "Reproducible Environments" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +msgid "Normalized Names" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +msgid "HTML Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +msgid "Project List" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +msgid "Project Detail" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +msgid "JSON Serialization" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +msgid "Content-Types" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +msgid "Version + Format Selection" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +msgid "Definitions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +msgid "Version scheme" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +msgid "Pre-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +msgid "Version epochs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +msgid "Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +msgid "Integer Normalization" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +msgid "Version exclusion" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +msgid "Well-known Project URLs in Metadata" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +msgid "Label normalization" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +msgid "Normalized" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"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/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "" + +#: ../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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "" + +#: ../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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" diff --git a/locales/zh_Hans/LC_MESSAGES/messages.po b/locales/zh_Hans/LC_MESSAGES/messages.po new file mode 100644 index 000000000..28cd87624 --- /dev/null +++ b/locales/zh_Hans/LC_MESSAGES/messages.po @@ -0,0 +1,28413 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# meowmeowmeowcat , 2021, 2022, 2024. +# Zuorong Zhang , 2021, 2022. +# bluewindde <13548563428@139.com>, 2021. +# Cube Kassaki <2524737581@qq.com>, 2021. +# xlivevil , 2021. +# Eric , 2021. +# YangYulin , 2021, 2022. +# 大胖纸 , 2021. +# JY3 , 2021, 2022. +# Eric , 2022. +# 王玎珰 <1330274738@qq.com>, 2022, 2023. +# Xu ZhuoHan , 2022. +# Harvey Li , 2022. +# Eric , 2022. +# Xiang Heng Wei , 2022, 2023. +# Eric , 2022. +# Eric , 2022, 2023. +# 陈星宇 , 2023. +# keven <1364712143@qq.com>, 2023. +# xiTiRuoLiWong , 2023. +# Eric , 2023, 2024. +# Autuamn End , 2023. +# Thomas , 2023, 2024. +# 大王叫我来巡山 , 2024, 2025, 2026. +# Peter Shen , 2024. +# hello_wac , 2024. +# Xianpeng Shen , 2024. +# tjuliuzibo , 2025. +# Jesse205 <2055675594@qq.com>, 2025. +# 小风 , 2025. +# 黄奕铭 , 2025. +# "Cheng R.Zhu" , 2025. +# inworless <20262029@aliyun.com>, 2025. +# del1 <3933676724@qq.com>, 2025. +# rand777 , 2025. +# monios , 2025. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: 2026-03-03 14:09+0000\n" +"Last-Translator: 大王叫我来巡山 " +"\n" +"Language-Team: Chinese (Simplified Han script) \n" +"Language: zh_Hans\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=1; plural=0;\n" +"X-Generator: Weblate 5.17-dev\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "为本指南做出贡献" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "|PyPUG| 欢迎贡献者！有很多方法可以帮助我们，包括：" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "阅读指南并提供反馈" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "审查新的贡献" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "修改现有内容" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "撰写新内容" + +#: ../source/contribute.rst:14 +msgid "Translating the guide" +msgstr "翻译指南" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" +"大部分关于 |PyPUG| 的工作发生于`项目的 GitHub 存储库`__ 。要开始，请查看 " +"`open issues`__ 和 `pull requests`__ 的列表。如果你打算编写或编辑指南，请阅" +"读 :ref:`style guide `。" + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "为 |PyPUG| 作贡献，你应该遵守 PSF 的 `行为准则`__." + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "文档类型" + +#: ../source/contribute.rst:34 +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" +"本项目由四种不同的文件类型组成，并具有特定的目的。项目希望遵循 `Diátaxis " +"process`_ 来创建高质量的文档。在向项目提出新的补充内容时，请选择相应的文件类" +"型。" + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "教程" + +#: ../source/contribute.rst:44 +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" +"教程的重点是通过完成一个目标来教导读者新的概念。它们是主观的分步指南。它们不" +"包括非必要的警告或信息。`示例教程式文件`_." + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "指南" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" +"指南的重点是完成一项具体的任务，并可以假定有一定程度的前提知识。这类似于教" +"程，但有一个狭窄和明确的重点，并可以根据需要提供大量的注意事项和附加信息。他" +"们还可以讨论完成任务的多种方法。 :doc:`example guide-style document `。" + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "讨论" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" +"讨论 (Discussions) 的重点是理解和信息。这些探索一个特定的主题，没有具体的目" +"标。 :doc:`example discussion-style document `。" + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "规格" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" +"规范 (Specifications) 是参考文档，侧重于全面记录包装工具之间互操作性的一致接" +"口。 :doc:`example specification-style document `。" + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "翻译" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" +"我们使用 `Weblate`_ 来管理这个项目的翻译工作。请访问 Weblate 上的 " +"`packaging.python.org`_ 项目，以做出贡献。" + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "如果你在翻译工作中遇到问题，请在`Github`_ 上开一个 issue 。" + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "本项目的任何翻译都应遵循 `reStructuredText 语法`_ 。" + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "添加一种语言" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" +"如果你的语言没有列在 `packaging.python.org`_ 上，请单击语言列表底部" +"的 :guilabel:`Start new translation` 按钮并添加你要翻译的语言。" + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "按照 reStructuredText 的语法" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" +"如果你不熟悉 reStructuredText （RST） 语法，请在 Weblate 上翻译之前阅读 `本指" +"南`_ 。" + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "**不要直接翻译参考（reference）中的文字**" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "在翻译参考（reference）的时候，请不要直接翻译它们。" + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "错误：直接翻译以下文本：" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "正确：使用你自己的语言翻译以下文本并添加原始引用：" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "在本地构建指南" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" +"虽然这不需要做出贡献，但为了测试你的改动，在本地建立本指南可能是有用的。为了" +"在本地构建本指南，你需要：" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr ":doc:`Nox `。你可以用 ``pip`` 安装或升级 nox：" + +#: ../source/contribute.rst:136 +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" +"Python 3.11。我们的构建脚本通常仅使用 Python 3.11 进行测试。请参" +"阅 :doc:`Hitchhiker's Guide to Python installation instructions ` 将 Python 3.11 安装于你的操作系统中。" + +#: ../source/contribute.rst:140 +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "要构建指南，在项目根文件夹中运行以下 shell 命令：" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" +"在该过程完成后，你可以在 ``./build/html`` 目录中找到 HTML 输出。你可以打开 " +"``index.html`` 文件，并在浏览器中查看指南，但我们建议使用 HTTP 服务器为指南服" +"务。" + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "你可以使用以下命令建立指南并通过 HTTP 服务器为其提供服务：" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "该指南将可通过 http://localhost:8000 进行浏览。" + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "指南的部署地点" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" +"该指南是通过ReadTheDocs部署的，配置位于 https://readthedocs.org/projects/" +"python-packaging-user-guide/ 。它由一个自定义域名提供服务，并由 Fast.ly 提供" +"支持。" + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "风格指南" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" +"本风格指南提供了关于如何编写 |PyPUG| 的建议。在开始写作之前，请先查看它。通过" +"遵循样式指南，你的贡献将有助于增加一个有凝聚力的整体，并使你的贡献更容易被项" +"目接受。" + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "目的" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" +"|PyPUG| 的目的是成为关于如何使用当前工具打包、发布和安装 Python 项目的权威资" +"源。" + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "范围" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "该指南旨在通过准确和有针对性的建议来回答问题和解决问题。" + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" +"本指南并不意味着是全面的，也不意味着可以取代单个项目的文档。例如，pip 有几十" +"个命令、选项和设置。pip 文档详细描述了它们中的每一个，而本指南只描述了完成本" +"指南中描述的特定任务所需的 pip 部分。" + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "读者" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "本指南的受众是任何使用 Python 包的人。" + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" +"不要忘记，Python 社区是很大，而且很受欢迎的。读者可能与你的年龄、性别、教育、" +"文化等不尽相同，但他们和你一样值得学习包装知识。" + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" +"特别是要记住，不是所有使用 Python 的人都把自己看作是程序员。本指南的受众包括" +"天文学家，画家或学生以及专业的软件开发人员。" + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "声音和语气" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" +"在撰写本指南时，即使你已经掌握了所有答案，也要努力以平易近人且谦逊的语气写" +"作。" + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" +"想象一下，你正在和一个你知道是聪明和熟练的人一起做 Python 项目。你喜欢和他们" +"一起工作，他们也喜欢和你一起工作。那个人问了你一个问题，你知道答案。你怎么回" +"答？*这* 就是你应该如何写这个指南的方式。" + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" +"这里有一个快速检查：试着大声朗读以了解你写作的声音和语气。它听起来像你会说的" +"话，还是听起来像你在演戏或发表演讲？随意使用缩略语，不要担心拘泥于繁琐的语法" +"规则。你在此允许用介词来结束一个句子，如果这是你想结束它的话。" + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" +"在写指南时，根据主题的严肃性和难度调整你的语气。如果你写的是一个介绍性的教" +"程，开个玩笑是可以的，但如果你涉及的是一个敏感的安全建议，你可能要完全避免玩" +"笑。" + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "公约和机制" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "**写给读者**" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "在提出建议或采取的步骤时，你应称呼读者为 *你* 或使用命令语气。" + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "错误：要安装它，用户运行…" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "正确：你可以安装它，方法是运行…" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "正确：要安装它，请运行…" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "**陈述假设**" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" +"避免做出未说明的假设。在网上阅读意味着指南的任何一页都可能是读者所看到的指南" +"的第一页。如果你要做假设，那就要说明你要做什么假设。" + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "**慷慨地交叉参考**" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" +"当你第一次提到一个工具或做法时，请链接到指南中涉及它的部分，或链接到其他地方" +"的相关文件。这样可以为读者省去搜索的麻烦。" + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "**尊重命名的做法**" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "当给工具、网站、人和其他专有名词命名时，请使用它们的首选大写字母。" + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "错误：Pip 使用…" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "正确：pip 使用…" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "错误：...托管在 github 上。" + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "正确：……托管在 GitHub 上。" + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "**使用中性风格**" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" +"通常，你会用 *you*、*your* 和 *yours* 来直接称呼读者。否则，请使用性别中立的" +"代词 *they*、*their* 和 *theirs* ，或者完全避免使用代词。" + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "错误：一个维护人员上传了文件。然后他…" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "正确：一个维护人员上传了文件。然后他们…" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "正确：A maintainer uploads the file. Then the maintainer…" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "**标题**" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" +"写标题时要使用读者正在搜索的词。一个好方法是让你的标题完成一个隐含的问题。例" +"如，读者可能想知道 *How do I install MyLibrary?*，所以一个好的标题可能是 " +"*Install MyLibrary* 。" + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" +"在章节标题中，使用句子大小写。换句话说，要像写一个典型的句子那样写标题。" + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "错误：Things You Should Know About Python" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "正确：Things you should know about Python" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "**数字**" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "在正文中，将数字1到9写成单词。对于其他数字或表格中的数字，使用数字。" + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "部署 Python 应用程序" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "页面状态" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "不完全" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "最后审查" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "2021-8-24" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "总览" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "支持多种硬件平台" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "操作系统包装和安装程序" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "Windows 系统" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "Pynsist" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" +"`Pynsist `__ 是一个基于NSIS的单一安装程序，" +"并将 Python 程序与 Python 解释器捆绑在一起的工具。在大多数情况下，打包 " +"(packaging) 只需要用户选择 Python 解释器的版本并声明程序的依赖性 " +"(dependencies) 。该工具会下载用于 Windows 的 Python 解释器，并将其与所有依赖" +"项打包成一个可在 Windows 执行的安装程序。" + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" +"安装的程序可以从安装程序添加到开始菜单的快捷方式启动。它使用一个安装在其应用" +"程序目录中的Python解释器，与计算机上的任何其他 Python 安装无关。" + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" +"Pynsist 的一大优势是可以在 Linux 上构建 Windows 软件包。在 :any:`文档 " +"`中，有几个不同类型程序（控制台、GUI）的例子。该工具是在 MIT " +"许可证下发布的。" + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "应用捆绑" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "py2exe" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" +"`py2exe `__ 是一个 distutils 扩展，允许从 " +"Python 脚本构建独立的 Windows 可执行程序（32位和64位）。支持包含在官方开发周" +"期中的 Python 版本（参考 `Python 分支的状态`__ ）。 py2exe 可以构建控制台可执" +"行文件和窗口（GUI）可执行文件。构建 windows 服务和 DLL/EXE COM 服务器可能有" +"效，但不被积极支持。distutils 扩展是在 MIT-licence 和 Mozilla Public License " +"2.0 下发布的。" + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "macOS" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "py2app" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" +"`py2app `__ 是一个 Python setuptools 命令，" +"它将允许你从 Python 脚本中制作独立的 macOS 应用程序包和插件。请注意，py2app " +"必须在 macOS 上用来构建应用程序，它不能在其他平台上创建 Mac 应用程序。 " +"py2app 在 MIT 许可下发布。" + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "Unix（包括 Linux 和 macOS）" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "pex" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" +"`pex `__是一个用于生成.pex（PythonEXecutable）" +"文件的库，它是可执行的Python环境，符合virtualenvs精神。pex是对:pep:`441`中概" +"述的思想的扩展，使部署Python应用程序像cp一样简单。pex文件甚至可以包括多个特定" +"平台的Python分布，这意味着一个pex文件可以跨Linux和macOS移植。pex是根据Apache " +"2.0许可证发布的。" + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "配置管理" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "分发包与导入包比较" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" +"多个不同的概念通常会用 \"package\" 一词来表示。本页面将澄清 Python 打包管理中" +"涉及的两个概念，他们既相关又有不同的含义，以及他们之间的区别，即 \"分发包" +"\"（distribution package）和 \"导入包\"（import package）。" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "什么是分发包？" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" +"分发包（distribution package）是可安装的一段软件。通常情况下，它与 \"项目" +"\"（project）同义。当你输入 ``pip install pkg`` ，或在 ``pyproject.toml`` 文" +"件中写入 ``dependencies = [\"pkg\"]`` 时， ``pkg`` 就是一个分发包的名称。当你" +"在PyPI_（目前最广为人知的 Python 库和工具的集中安装源）上搜索或浏览时，所看到" +"的列表就是分发包的列表。另外，\"分发包\" 这个术语也可以用来指代包含项目特定版" +"本的某个文件。" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" +"请注意，在 Linux 领域中，“分发软件包”通常缩写为 “distro package” 或简单称为 " +"“package”，指的是由 ` Linux 发行版 `_ 的系统包管理器提供的内容，这" +"与 Python 中的含义不同。" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "什么是导入包？" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" +"导入包（import package）是一个 Python 模块。因此，当你在 Python 代码中编写 " +"``import pkg`` 或 ``from pkg import func`` 时， ``pkg`` 就是导入包的名称。更" +"准确地说，导入包是可以包含子模块的特殊 Python 模块。例如， ``numpy`` 包包含" +"像 ``numpy.linalg`` 和 ``numpy.fft`` 这样的模块。通常，导入包是文件系统中的一" +"个目录，其中包含作为 ``.py`` 文件的模块和作为子目录的子包。" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "一旦你安装了提供该包的分发包，你就可以使用导入包。" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "分发包和导入包之间有什么联系？" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" +"大多数情况下，分发包会提供一个具有匹配名称的导入包（或非包模块）。例如，" +"``pip install numpy``允许你``import numpy``。" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" +"然而，这只是一种约定。PyPI 和其他包索引 *并不强制要求* 分发包的名称与其提供的" +"导入包之间存在任何关系。（其结果是，当你看到 ``import foo`` 时，不能盲目地安" +"装 PyPI 包 ``foo`` ；这样可能会安装一个非预期的，甚至是恶意的包。）" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" +"一个分发包可以提供一个名称不同的导入包。一个例子是广受欢迎的图像处理库 " +"Pillow_ 。它的分发包名称是 ``Pillow``，但它提供的导入包名称是 ``PIL``。这是出" +"于历史原因：Pillow 最初是 PIL 库的一个分支，因此它保留了 ``PIL`` 作为导入名" +"称，以便现有的 PIL 用户可以轻松切换到 Pillow 。更普遍来说，现有库的分支是导致" +"分发包和导入包名称不同的常见原因。" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" +"在特定的包索引(如 PyPI)上，分发包名称必须是唯一的。另一方面，导入包则没有这种" +"要求。多个分发包可以提供同名的导入包。同样地，分支（fork）是导致这种情况的常" +"见原因。" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" +"相反，一个分发包也可以提供多个导入包，尽管这种情况较为少见。一个例子是 " +"attrs_ 分发包，它提供了一个带有较新 API 的 ``attrs`` 导入包，以及一个较旧但仍" +"受支持的 ``attr`` 导入包。" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "分发包名称和导入包名称如何比较？" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" +"导入包的名称应为有效的 Python 标识符（具体规则可以在 Python 文档中找" +"到：:ref:``）[＃non-identifier-mod-name]_ 。特别地，它们" +"使用下划线 ``_`` 作为单词分隔符，并且区分大小写。" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" +"另一方面，分发包可以使用连字符 ``-`` 或下划线 ``_`` 。它们还可以包含点号 " +"``.`` ，这有时用于打包 :ref:`命名空间包` 的子" +"包。对于大多数用途，它们对大小写和 ``-`` 与 ``_`` 的区别不敏感，例如， ``pip " +"install Awesome_Package`` 和 ``pip install awesome-package`` 是相同的（具体规" +"则可以在 ```` 名称规范中找到）。" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" +"尽管从技术上讲，通过使用 :doc:`importlib ` 可以导入" +"名称不是有效 Python 标识符的包/模块，但这种情况极为罕见且强烈不推荐。" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "支持下游打包" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "草稿" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "2025年-？" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" +"虽然 PyPI 和 Python 打包工具（例如：:ref:`pip`）是分发 Python 包的主要方式，" +"但它们也常常被包含在其他打包生态系统中。这些重新打包的工作统称为*下游*打包" +"（你自己的工作则称为 *上游* 打包），包括 Linux 发行版、Conda、Homebrew 和 " +"MacPorts 等项目。它们通常旨在为无法仅通过 Python 打包工具处理的用例提供更好的" +"支持，例如与特定操作系统的原生集成，或与特定版本的非 Python 软件确保兼容性。" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" +"本次讨论试图解释下游打包通常是如何进行的，以及下游打包者通常面临的额外挑战。" +"它旨在提供一些可选的指南，项目维护者可以选择遵循这些指南，从而帮助使下游打包 " +"*明显地* 更轻松（同时不会给上游项目带来任何重大的维护麻烦）。请注意，这并不是" +"一个全有或全无的提议——上游维护者所做的任何事情都是有用的，即使只是其中的一小" +"部分。下游维护者也愿意准备补丁来解决这些问题。将这些补丁合并会非常有帮助，因" +"为这消除了不同下游需要携带并持续重新应用相同补丁的必要性，以及对同一问题应用" +"不一致解决方案的风险。" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" +"在软件维护者和下游打包者之间建立良好的关系可以带来互利共赢。下游方通常愿意分" +"享他们的经验、时间和硬件来改进你的软件包。他们有时更能看清你的软件包在实际中" +"的使用情况，并提供关于它与其他软件包之间关系的信息，而这些信息通常需要付出相" +"当大的努力才能获得。打包者通常可以在你的用户在生产环境中遇到问题之前发现漏" +"洞，提供高质量的漏洞报告，并在可能的情况下提供补丁。例如，他们经常积极确保他" +"们重新分发的软件包在新的 Python 版本发布时更新，以解决任何出现的兼容性问题。" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" +"请注意，下游构建不仅包括二进制文件的重新分发，还包括在用户系统上进行的源码构" +"建（例如在以源码优先的发行版中，像Gentoo Linux）。" + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "提供完整的源分发" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "为什么？" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" +"绝大多数下游打包者倾向于从源代码构建软件包，而不是使用上游提供的二进制软件" +"包。在某些情况下，使用源代码实际上是软件包被包含在发行版中的必要条件。这同样" +"适用于提供通用轮的纯 Python 软件包。使用源码分发的原因可能包括：" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "能够审核所有软件包的源代码。" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "能够运行测试套件并构建文档。" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" +"能够轻松地应用补丁，包括从项目资源库反向移植提交内容，以及将补丁发送回项目。" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "可以在一个特定的但上游没有相应构建的平台上构建。" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "可以根据特定版本的系统库进行构建。" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "在所有 Python 软件包中使用一致的构建流程。" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "虽然通常可以从 Git 存储库中构建包，提供静态归档会更好，具体理由如下：" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" +"获取单个文件通常比Git克隆等方式更高效、更可靠、更被支持。这有助于网络连接不佳" +"的用户。" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" +"下游经常使用哈希来验证后续构建中源文件的真实性，而这需要文件长期保持二进制相" +"同。举个例子，自动生成的 Git 存档就不保证这一点，因为如果服务器上的 gzip 升级" +"了，那么压缩的数据可能会改变。" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" +"可以镜像已存档文件，降低上下游带宽用量。之后可以在用防火墙保护的环境或离线环" +"境中执行实际构建，这些环境只能访问本地镜像提供的源文件或之前分发的源文件。" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" +"明确发布存档文件可以确保在创建源归档时解决对版本控制系统元数据的任何依赖。例" +"如，自动生成的Git存档会省略所有提交标签信息，可能会导致生成的构建中版本详细信" +"息不正确。" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "如何做？" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" +"理想情况下，**在 PyPI 上发布的源分发存档应包括来自软件包 Git 存储库的所有文件" +"**，这些文件是构建软件包本身、运行其测试套件、构建和安装其文档以及可能对最终" +"用户有用的任何其他文件所必需的，如 shell 补全文件、编辑器支持文件等。" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" +"这一点仅适用于属于软件包本身的文件。下游打包过程与Python软件包管理器非常类" +"似，将提供您的软件包及其构建脚本所需的必要的Python依赖项、系统工具和外部库。" +"然而，还应包括列出这些依赖项的文件（例如，``requirements*.txt`` 文件），帮助" +"下游确定所需的依赖项，并检查其中是否有变化。" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" +"一些项目对使用PyPI源分发的Python软件包管理器有关。他们不想用这些工具不使用的" +"文件来增加它们的大小，或者他们根本不想发布源分发，因为它们允许从源代码构建特" +"定项目的问题或完全无功能的后退。在这些情况下，一个好的折衷方案可能是发布一个" +"单独的源代码归档，以便在其他地方下游使用，例如将其附加到GitHub版本中。或者，" +"大型文件，如测试数据，可以拆分成单独的档案。" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" +"另一方面，一些项目（例如NumPy_）决定在其已安装的软件包中包含测试。这具有允许" +"用户在安装后运行测试的额外优势，例如在升级依赖项后检查回归。另一种方法是将测" +"试或测试数据分割成一个单独的 Python 软件包。加密_项目采取了这种方法，将大型测" +"试向量拆分为加密矢量_包。" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" +"在发布流程中使用源分发是个不错的做法。例如，:ref:`build` 工具正是这样操作的——" +"它首先构建源分发，然后用它来构建 wheel 包。这能确保源分发实际可用，同时避免意" +"外遗漏官方 wheel 包中的文件。" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" +"理想情况下，您还可以使用源分发来运行测试、构建文档等，或者添加特定测试以确保" +"包含所有必要的文件。可以理解的是，这需要付诸更多努力，所以不这样也没啥——下游" +"的打包工具会立即报告任何可能的缺失文件。" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "构建过程中请勿连接互联网" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" +"下游构建通常在无法访问互联网的沙箱环境中进行。软件包源码会被解压到该环境中，" +"并安装所有必要的依赖项。" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" +"即便不存在此类情况，且假设您已严格确保下载验证，出于多方面考虑，仍不建议在构" +"建过程中接入互联网：" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" +"网络连接可能不稳定（例如由于信号接收不佳），或存在临时性问题，这可能导致流程" +"执行失败或陷入停滞。" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" +"远程资源可能会暂时甚至永久不可用，从而导致无法完成构建。当有人需要构建旧的软" +"件包版本时，这个问题尤其突出。" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "远程资源可能发生变更，导致构建结果无法重现。" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" +"访问远程服务器会带来隐私泄露和潜在的安全风险，因为这会暴露执行软件包构建的系" +"统信息。" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" +"用户可能正在使用有限数据套餐的服务，此时无限制的网络访问可能导致产生额外费用" +"或引发其他不便。" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" +"若软件包在实施使用互联网的任何自定义 *backend* 构建操作（例如自动下载供应商依" +"赖或获取Git子模块），其源码分发包必须包含所有这些文件，或允许通过外部方式提供" +"这些文件。当这些文件已存在时不准使用互联网。" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" +"注意，本条要求不适用于在软件包元数据中指定，由*前端*在构建和安装过程中自动获" +"取 的 Python依赖项（如 :ref:`build` 或 :ref:`pip`）。下游环节使用的前端是通过" +"本地方式提供 Python 依赖项的。" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" +"理想情况下，自定义构建脚本甚至不应尝试访问互联网，除非被明确要求这样做。如果" +"缺少任何需要获取的资源，它们应当先征得用户许可。若无法实现此机制，次优方案是" +"提供禁用所有网络访问的退出开关。例如，可通过检查 ``NO_NETWORK`` 环境变量是否" +"设置为非空值来实现。" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" +"考虑到下游环节通常还需执行测试及构建文档，理想情况下上述规范应同样适用于这些" +"流程。" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" +"同时请记住，若获取远程资源，您必须 *verify their authenticity*（通常核对哈希" +"值），以防文件被恶意方替换的风险。" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "支持针对系统依赖进行构建" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" +"某些Python项目包含非Python依赖项（例如使用C或C++编写的库）。在上游软件包构建" +"过程中尝试使用系统版本的这些依赖项，可能会给最终用户带来诸多问题：" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" +"发布的wheel包要求用户系统必须存在二进制兼容版本的依赖库。若该库缺失或安装了不" +"兼容的版本，Python软件包可能会因报错信息对入门用户不够清晰而运行失败，甚至可" +"能在运行时出现异常行为。" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" +"从源码分发版进行构建时，不仅要求存在源码兼容版本的依赖项，还需要其开发头文件" +"及其他辅助文件——这些组件在某些操作系统中会与主程序库本身分开打包。" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" +"即便对于资深用户而言，安装兼容版本的依赖项也可能极为困难。例如，其所用的Linux" +"发行版可能未提供所需版本，亦或是其他软件包要求使用不兼容的版本。" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" +"Python软件包与其系统依赖项之间的链接关系并未被包管理系统记录。后续的系统更新" +"可能会将程序库升级至与Python软件包二进制不兼容的新版本，从而需要用户手动干预" +"修复。" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" +"基于上述原因，您可以合理选择以下方案：静态链接依赖项，或在安装包中提供本地副" +"本。您也可以在源码分发版中内置依赖项。某些情况下，这些依赖项还会被重新打包至" +"PyPI，此时即可像声明普通Python包依赖那样将其列为项目依赖项。" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" +"然而，这些问题均不适用于下游打包场景，且下游环节有充分理由倾向于动态链接系统" +"依赖项。具体而言：" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" +"许多情况下，可靠地在各组件间共享动态依赖项是下游打包生态系统的主要 " +"*purpose*。支持这种机制能使这些系统的用户更便捷地以其偏好的格式访问上游项目。" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "静态链接与内置依赖项会掩盖外部依赖的使用情况，增加源码审计的难度。" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" +"动态链接使得能够快速且系统性地在整个下游打包生态中替换所使用的程序库，这在发" +"现程序库存在安全漏洞或关键错误时显得尤为关键。" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" +"使用系统依赖可使软件包受益于下游定制化改进，从而在特定平台上提升用户体验，而" +"无需下游维护者对不同软件包中内置的依赖项进行持续修补。这类改进可能包括兼容性" +"优化与安全加固。" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" +"静态链接与内置依赖可能导致同一进程加载多个不同版本的相同库（例如，尝试导入两" +"个链接至同一库不同版本的Python包）。这种情况有时能正常运行，但也可能引发从库" +"加载错误、微妙的运行时缺陷，到灾难性故障（如突然崩溃并丢失数据）等一系列问" +"题。" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" +"最后同样重要的是，静态链接与内置依赖会导致资源重复，并可能显著增加磁盘空间和" +"内存的使用量。" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" +"在满足双方需求方面，一个较好的折衷方案是提供在内置依赖与系统依赖之间切换的选" +"项。理想情况下，若软件包包含多个内置依赖项，应同时提供针对每个依赖项的独立切" +"换选项及控制默认行为的全局开关，例如通过 ``USE_VENDORED_DEPS`` 环境变量来实" +"现。" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" +"若用户请求使用系统依赖项，而特定依赖项缺失或不兼容时，构建过程应终止并给出解" +"释性提示信息，而非回退至内置版本。这能让打包人员及时察觉配置疏漏，并有机会自" +"主决定解决方案。" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" +"上游项目将用系统依赖项构建的 *testing* 工作交由下游重打包者处理是合理的，这些" +"指导原则旨在促进上游项目与下游重打包者之间更高效的协作，而非建议上游项目承担" +"本应由更专业的下游重打包者完成的任务。" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "支持下游测试" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" +"各类下游项目会对打包后的Python项目进行不同程度的测试。根据具体情况，测试范围" +"可能从最小化的冒烟测试到完整测试套件的全面执行。进行此类测试可能出于多种原" +"因，例如：" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "已稳定版本为目的" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" +"**讨论 (Discussions)** 的重点是提供关于特定主题的全面信息。如果你只是想把事情" +"做好，请看 :doc:`/guides/index` 。" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "install_requires 与 requirements files" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "install_requires" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" +"``install_requires`` 是一个 :ref:`setuptools` :file:`setup.py` 关键字，它应该" +"用来指定一个项目 **最小** 需要正确运行的内容。当项目由 :ref:`pip` 安装时，这" +"就是用来安装其依赖的规范。" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "例如，如果项目需要 A 和 B ，你的 ``install_requires`` 会是这样的：" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "此外，最好的做法是指出任何已知的下限或上限。" + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" +"例如，你可能知道你的项目至少需要 'A' 的 v1 ，'B' 的 v2 ，所以它会是这样的：" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" +"也可以了解到，项目 'A' 在其 v2 版本中引入了一个更改，破坏了你的项目与 'A' 的 " +"v2 及以后的版本的兼容性，因此不允许使用 v2 是有意义的：" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" +"使用 ``install_requires`` 将依赖关系固定在特定的版本上，或者指定子依赖关系" +"（即你的依赖关系的依赖关系），都不是最佳做法。 这是对用户的过度限制，使用户无" +"法获得依赖性升级的好处。" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" +"最后，重要的是要了解 ``install_requires`` 是“Abstract”要求的列表，即只是名称" +"和版本限制，并不能确定从哪里满足依赖关系（即从什么索引或来源）。在安装时使" +"用 :ref:`pip` 选项确定在哪里（即如何使它们“Concrete”）。 [1]_" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "必需文件" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" +":ref:`Requirements Files ` 最简单的描述，只是放在文件" +"中的 :ref:`pip:pip install` 参数列表。" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" +"``install_requires`` 定义了单个项目的依赖项， :ref:`Requirements Files " +"` 通常用于定义完整 Python 环境的要求。" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" +"尽管 ``install_requires`` 要求是最低限度的，但要求文件通常包含固定版本的详尽" +"列表，目的是实现完整环境的 :ref:`repeatable installations " +"`。" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" +"而 ``install_requires`` 需求是“Abstract”的，即不与任何特定索引相关联，需求文" +"件通常包含 pip 选项，如 ``--index-url`` 或 ``--find-links`` 使需" +"求“Concrete”，即与包的特定索引或目录相关联。 [1]_" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" +"在安装过程中，``install_requires`` 元数据会被 pip 自动分析，而需求文件则不" +"会，而它只有在用户使用 ``python -m pip install -r`` 专门安装时才会使用。" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" +"抽象 (Abstract) \"与 \"具体 (Concrete)\"要求的更多信息，请参阅 https://" +"caremad.io/posts/2013/07/setup-vs-requirement/ 。" + +#: ../source/discussions/package-formats.rst:5 +msgid "Package Formats" +msgstr "包的格式" + +#: ../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 "本页讨论了用于分发 Python 包的文件格式及其之间的区别。" + +#: ../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 "" +"在像 PyPI_ 这样的包索引中，你会找到两种格式的文件：**源代码分发包**（简称 " +"**sdists**）和 **二进制分发包**，通常称为 **wheels**。例如，`PyPI 的 pip " +"23.3.1 页面 `_ 允许你下载两个文件，``pip-23.3.1.tar.gz`` 和 " +"``pip-23.3.1-py3-none-any.whl``。前者是一个 sdist，后者是一个 wheel。如下面所" +"解释的，这两者有不同的用途。当在 PyPI（或其他地方）发布包时，你应该始终上传一" +"个 sdist 和一个或多个 wheel 文件。" + +#: ../source/discussions/package-formats.rst:21 +msgid "What is a source distribution?" +msgstr "什么是源分发？" + +#: ../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 "" +"从概念上讲，源代码分发包是原始形式的源代码归档。具体来说，sdist 是一个 " +"``.tar.gz`` 压缩包，包含源代码以及一个额外的特殊文件 ``PKG-INFO`` ，该文件存" +"储项目的元数据。这个文件的存在帮助打包工具提高效率，因为它不需要自己计算元数" +"据。 ``PKG-INFO`` 文件遵循 :ref:`core-metadata` 中规定的格式，并不打算手动编" +"写 [#core-metadata-format]_ 。" + +#: ../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 压缩文件的标准工具解压缩 sdist 来检查其内容，这些工" +"具包括 UNIX 平台上的 ``tar -xvf`` （ Linux 和 macOS 也一样），或者在任何平台" +"上使用 :ref:`the command line interface of Python's tarfile module " +"`。" + +#: ../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 "" +"Sdists 在打包生态系统中有多个用途。当标准的 Python 包安装工具 :ref:`pip` 无法" +"找到要安装的 wheel 时，它会回退到下载源代码分发包，从中编译一个 wheel 并安装" +"这个 wheel。此外，sdists 经常作为下游打包者（如 Linux 发行版、Conda、macOS 上" +"的 Homebrew 和 MacPorts 等）的包源，因为各种原因，他们可能会更倾向于使用源代" +"码分发包，而不是例如从 Git 仓库中拉取代码。" + +#: ../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/package-formats.rst:50 +msgid "" +"If you want technical details on the sdist format, read the :ref:`sdist " +"specification `." +msgstr "" +"如果您需要有关 sdist 格式的技术细节，请阅读：:ref:`sdist specification " +"`。" + +#: ../source/discussions/package-formats.rst:55 +msgid "What is a wheel?" +msgstr "什么是 wheel ?" + +#: ../source/discussions/package-formats.rst:57 +msgid "" +"Conceptually, a wheel contains exactly the files that need to be copied when " +"installing the package." +msgstr "从概念上讲，wheel 包含在安装包时所需要复制的文件。" + +#: ../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 "" +"对于包含 :term:`extension modules ` 的包（这些模块用 C、C+" +"+ 和 Rust 等编译语言编写，需要编译成平台相关的机器代码），sdists 和 wheels 之" +"间存在很大区别。对于这些包，wheels 不包含源代码（如 C 源文件），而是包含已编" +"译的可执行代码（例如 Linux 上的 ``.so`` 文件或 Windows 上的 DLL 文件）。" + +#: ../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 "" +"此外，虽然每个版本的项目只有一个 sdist，但可能有多个 wheels。同样，这在扩展模" +"块的上下文中最为相关。扩展模块的编译代码与操作系统和处理器架构相关，通常还与 " +"Python 解释器的版本相关（除非使用 :ref:`Python stable ABI ` ）。" + +#: ../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 "" +"对于纯 Python 包，sdists 和 wheels 之间的区别较小。通常情况下，所有平台和 " +"Python 版本共享一个单一的 wheel。Python 是一种解释型语言，不需要预编译，因此 " +"wheels 和 sdists 一样，包含 ``.py`` 文件。" + +#: ../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 "" +"如果你对 ``.pyc`` 字节码文件有所疑问：它们不包含在 wheels 中，因为生成它们的" +"成本很低，而且包含它们会不必要地迫使大量包为每个 Python 版本分发一个 wheel，" +"而不是一个单一的 wheel。相反，像 :ref:`pip` 这样的安装工具会在安装包时生成这" +"些文件。" + +#: ../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 "" +"尽管如此，即使对于纯 Python 项目，sdists 和 wheels 之间仍然存在重要的区别。" +"Wheels 的目的是包含要安装的内容，并且不包含其他内容。特别是，wheels 不应包含" +"测试和文档，而 sdists 通常会包含这些。此外，wheel 格式比 sdist 更复杂。例如，" +"它包含一个特殊文件—— ``RECORD`` ，该文件列出了 wheel 中的所有文件及其内容的哈" +"希值，用作下载完整性的安全检查。" + +#: ../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 "" +"乍一看，你可能会想，\"纯粹的基础\" Python 项目是否真的需要 wheels。请记住，由" +"于 sdists 的灵活性，像 pip 这样的安装工具不能直接从 sdists 安装——它们需要首先" +"通过调用 sdist 指定的 :term:`build backend` 来构建一个 wheel（构建后端在构建 " +"wheel 时可能会执行各种转换，例如编译 C 扩展）。因此，即使是纯 Python 项目，你" +"也应该始终将 *sdist* 和 *wheel* 都上传到 PyPI 或其他包索引。这会使你的用户安" +"装速度更快，因为 wheel 可以直接安装。通过只包含必须安装的文件，wheels 也使得" +"下载文件更小。" + +#: ../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 "" +"在技术层面上，wheel 是一个 ZIP 归档文件（与 sdist 的 TAR 归档文件不同）。你可" +"以通过像处理普通 ZIP 归档文件一样解压它来检查其内容，例如，在 Linux 和 macOS " +"等 UNIX 平台上使用 ``unzip`` ，在 Windows 上使用 Powershell 的 ``Expand-" +"Archive`` ，或使用 :ref:`the command line interface of Python's zipfile " +"module `。这对于检查 wheel 是否包含你需要的所有文" +"件非常有用。" + +#: ../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 "" +"在 wheel 中，你会找到包的文件，以及一个名为 :samp:`{package_name}-" +"{version}.dist-info` 的额外目录。该目录包含多个文件，其中包括 ``METADATA`` 文" +"件，它相当于 sdist 中的 ``PKG-INFO`` ，以及 ``RECORD`` 文件。这对于确保你的 " +"wheel 中没有缺失文件非常有用。" + +#: ../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 "" +"一个 wheel 的文件名（忽略一些很少使用的特性）看起来是这样" +"的： :samp:`{package_name}-{version}-{python_tag}-{abi_tag}-" +"{platform_tag}.whl`。这种命名约定用于标识 wheel 与哪些平台和 Python 版本兼" +"容。例如，文件名 ``pip-23.3.1-py3-none-any.whl`` 意味着：" + +#: ../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 "" +"（ ``py3`` ）这个 wheel 可以安装在任何 Python 3 的实现上，无论是最广泛使用的 " +"Python 实现 CPython，还是像 PyPy_ 这样的替代实现;" + +#: ../source/discussions/package-formats.rst:124 +msgid "(``none``) It does not depend on the Python version;" +msgstr "( ``none`` ) 不依赖于 Python 版本;" + +#: ../source/discussions/package-formats.rst:125 +msgid "(``any``) It does not depend on the platform." +msgstr "(``any``) 它不依赖于任何平台。" + +#: ../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 "" +"``py3-none-any`` 这个模式通常用于纯 Python 项目。包含扩展模块的包通常会提供多" +"个具有更复杂标签的 wheels 。" + +#: ../source/discussions/package-formats.rst:130 +msgid "" +"All technical details on the wheel format can be found in the :ref:`wheel " +"specification `." +msgstr "" +"有关 wheel 格式的所有技术细节均可在 :ref:`wheel specification ` 中找到。" + +#: ../source/discussions/package-formats.rst:138 +msgid "What about eggs?" +msgstr "那么 eggs 格式呢？" + +#: ../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 "" +"\"Egg\" 是一种旧的包格式，已经被 wheel 格式取代。现在不应再使用它。从 2023 " +"年 8 月起，PyPI 已经 `拒绝上传 egg 格式包 `_ 。" + +#: ../source/discussions/package-formats.rst:144 +msgid "Here's a breakdown of the important differences between wheel and egg." +msgstr "下面是 Wheel 和 Egg 之间重要区别的详细说明。" + +#: ../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 "" +":term:`Egg` 格式是由 :ref:`setuptools` 在2004年引入的，而 :term:`Wheel` 格式" +"是由 :pep:`427` 在2012年引入。" + +#: ../source/discussions/package-formats.rst:149 +msgid "" +"Wheel has an :doc:`official standard specification `. Egg did not." +msgstr "" +"Wheel 有一个 :doc:`official standard specification `，而 Egg 没有。" + +#: ../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 "" +"Wheel 是一种 :term:`distribution ` 格式，也就是一种打包" +"格式。 [#wheel-importable]_ Egg 既是一种分发格式，也是一种运行时的安装格式" +"（如果是压缩状态），并被设计为可导入。" + +#: ../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 "" +"Wheel 压缩文件不包括 ``.pyc`` 文件。因此，当发行版只包含 Python 文件时 (即没" +"有已编译的扩展), 且兼容 Python 2 and 3 时，可以让 wheel \"universal\"，类似" +"于 :term:`sdist `." + +#: ../source/discussions/package-formats.rst:161 +msgid "" +"Wheel uses standard :ref:`.dist-info directories `. Egg used ``.egg-info``." +msgstr "" +"Wheel 使用标准 :ref:`.dist-info directories ` 。Egg 使用 ``.egg-info`` 。" + +#: ../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 "" +"Wheel 有一个 :ref:`richer file naming convention `。一" +"个单一的 wheel 档案可以表明它与许多 Python 语言版本和实现、ABI 以及系统架构的" +"兼容性。" + +#: ../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 "" +"Wheel 是版本化的。每个 wheel 文件都包含 wheel 规范的版本和打包它的实现。" + +#: ../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 "" +"Wheel 内部由 `sysconfig 路径类型 `_ 所组织，因此更容易转换为其他格式。" + +#: ../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 "" +"该格式是基于电子邮件的。尽管今天不太可能选择这种格式，但出于向后兼容性考虑，" +"它仍然作为规范格式保留下来。从用户的角度来看，这通常是不可见的，因为元数据是" +"以构建后端可以理解的方式由用户指定的，通常是在 ``pyproject.toml`` 中的 " +"``[project]`` 部分，并由构建后端转换为 ``PKG-INFO`` 文件。" + +#: ../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 "" +"在某些情况下，wheels 可以作为可导入的运行时格式使用，尽管 :ref:`this is not " +"officially supported at this time `。" + +#: ../source/discussions/pip-vs-easy-install.rst:6 +msgid "pip vs easy_install" +msgstr "pip 与 easy_install" + +#: ../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 `，现`已弃用`_，作为 :ref:`setuptools` 的一" +"部分于 2004 年发布。当时值得注意的是，使用需求说明符从 :term:`PyPI ` 安装 :term:`packages `，并自动安" +"装依赖项。" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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:`pip` 作为 :ref:`easy_install ` 的替代品于 2008 年出现，尽" +"管其仍然主要构建在 :ref:`setuptools` 组件之上。当时它引人关注的原因是 *不* 将" +"软件包作为 :term:`Eggs ` 安装或不从 :term:`Eggs ` 安装软件包（只作" +"为来自 :term:`sdists ` 的 'flat' 包进行安" +"装 ），并引入 :ref:`Requirements Files ` 的概念，使用" +"户能够轻松复制环境。" + +#: ../source/discussions/pip-vs-easy-install.rst:22 +msgid "" +"Here's a breakdown of the important differences between pip and the " +"deprecated easy_install:" +msgstr "下面是 pip 和被废弃的 easy_install 之间的重要区别的分类：" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "**pip**" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "**easy_install**" + +#: ../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 Files `)" + +#: ../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` 元数据的“Flat”包。" + +#: ../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/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "``setup.py`` 被废弃了吗？" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "不，:term:`setup.py` 和 :ref:`setuptools` 并没有被弃用。" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" +"Setuptools 完全可以作为打包 Python 项目的 :term:`构建后端` 使用。" +"而 :file:`setup.py` 是一个有效的 :ref:`setuptools` 配置文件，它恰好是用 " +"Python 编写的，而不是使用 *TOML* （例如，其他工具如 *nox* 及" +"其 :file:`noxfile.py` 配置文件，或 *pytest* 及其 :file:`conftest.py` 文件也采" +"用类似做法）。" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" +"然而，``python setup.py`` 和使用 :file:`setup.py` 作为命令行工具已被废弃。" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "这意味着 **不得** 再运行以下命令：" + +#: ../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]_" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" +"这需要 :ref:`build` 依赖项。建议始终构建并发布项目的源代码分发包和 wheel，这" +"正是 ``python -m build`` 所做的。如果需要，可以使用 ``--sdist`` 和 ``--" +"wheel`` 选项仅生成其中之一。" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" +"为了安装基于 setuptools 的项目，过去通常会运行 :file:`setup.py` 的 " +"``install`` 命令，例如： ``python setup.py install`` 。如今，推荐的方法是直接" +"使用 :ref:`pip` ， 命令如下： ``python -m pip install .`` 。其中点号 ``.`` 实" +"际上是一个文件系统路径，表示当前目录的路径符号。实际上， *pip* 接受本地文件系" +"统上项目源代码目录的路径作为其 ``install`` 子命令的参数。因此，以下命令也是有" +"效的： ``python -m pip install path/to/project`` 。" + +#: ../source/discussions/setup-py-deprecated.rst:65 +msgid "" +"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 "" +"至于 *develop* 模式，也就是 *editable* 模式的安装，除了使用 ``python " +"setup.py develop`` ，还可以使用 pip 的 *install* 子命令的 ``--editable`` 选" +"项： ``python -m pip install --editable .`` 。" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" +"构建 :term:`source distributions ` " +"和 :term:`wheels ` 的一种推荐、简单且直接的方法是使用 :ref:`build` 工" +"具，命令如下： ``python -m build``，该命令会触发生成这两种分发格式。如果需" +"要，可以使用 ``--sdist`` 和 ``--wheel`` 选项仅生成其中之一。请注意，build 工" +"具需要单独安装。" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" +"命令 ``python setup.py install`` 已在 *58.3.0* 版 setuptools 中被废弃。" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +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/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "``python setup.py test``" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "建议使用 pytest_ 等测试运行程序。" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" +"``python setup.py check`` ， ``python setup.py register`` ，和 ``python " +"setup.py upload``" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "一个值得信赖的替代品是 :ref:`twine`：" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "``python -m twine check --strict dist/*``" + +#: ../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/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "``python -m twine upload dist/*``" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" +"在 :term:`PyPI ` 上不必要，也不被支持。但在其" +"他 :term:`package indexes ` 上可能是必要的（例" +"如 :ref:`devpi` ）。" + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "``python setup.py --version``" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "一种可能的替代解决方案（除其他外）是依赖 setuptools-scm_ ：" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "``python -m setuptools_scm``" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "其余命令" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "本指南不会就替换这些命令而建议解决方案：" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "``alias``" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "``bdist``" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "``bdist_dumb``" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "``bdist_egg``" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "``bdist_rpm``" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "``build``" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "``build_clib``" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "``build_ext``" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "``build_py``" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "``build_scripts``" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "``clean``" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "``dist_info``" + +#: ../source/discussions/setup-py-deprecated.rst:141 +msgid "``easy_install``" +msgstr "``easy_install``" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "``editable_wheel``" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "``egg_info``" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "``install_data``" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "``install_egg_info``" + +#: ../source/discussions/setup-py-deprecated.rst:146 +msgid "``install_headers``" +msgstr "``install_headers``" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "``install_lib``" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "``install_scripts``" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "``rotate``" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "``saveopts``" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "``setopt``" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "``upload_docs``" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "那自定义命令又如何？" + +#: ../source/discussions/setup-py-deprecated.rst:158 +msgid "" +"Likewise, custom :file:`setup.py` commands are deprecated. The " +"recommendation is to migrate those custom commands to a task runner tool or " +"any other similar tool. Some examples of such tools are: chuy, make, nox or " +"tox, pydoit, pyinvoke, taskipy, and thx." +msgstr "" +"同样，自定义 :file:`setup.py` 命令已被弃用。建议将这些自定义命令迁移到任务运" +"行工具或其他类似工具中。这类工具包括：chuy、make、nox 或 tox、pydoit、" +"pyinvoke、taskipy 和 thx。" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "自定义构建步骤要怎么做？" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" +"自定义构建步骤，例如覆盖现有步骤（如 ``build_py`` 、 ``build_ext`` 和 " +"``bdist_wheel`` ）或添加新的构建步骤，并没有被弃用。这些步骤将会按预期自动调" +"用。" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "是否应该删除 ``setup.py``？" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" +"虽然将 :file:`setup.py` 用作可执行脚本已被废弃，但将其用作 setuptools 的配置" +"文件完全没有问题，甚至可能不需要修改 :file:`setup.py`。" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "``pyproject.toml`` 是强制性的吗？" + +#: ../source/discussions/setup-py-deprecated.rst:185 +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/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "指南 :ref:`modernize-setup-py-project` 有更多相关细节。" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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:`build frontend ` 的标准回退行为是默认假" +"设 :term:`build backend ` 是 setuptools。" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "为什么？这一切意味着什么？" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "一种看法是，setuptools 的作用范围现在已被缩小至构建后端的角色。" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "从哪里可以了解更多相关信息？" + +#: ../source/discussions/setup-py-deprecated.rst:213 +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "" +"`为什么你不应该再直接使用 setup.py `__ by Paul Ganssle" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr ":doc:`setuptools:deprecated/commands`" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "单一来源项目版本" + +#: ../source/discussions/single-source-version.rst:7 +msgid "Complete" +msgstr "完成" + +#: ../source/discussions/single-source-version.rst:8 +msgid "2024-10-07" +msgstr "2024-10-07" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" +"许多 Python :term:`distribution packages ` 发布一个单一" +"的 Python :term:`import package ` ，在这种情况下，希望导入包" +"上的运行时 ``__version__`` 属性报告与 :func:`importlib.metadata.version` 为分" +"发包报告的相同版本说明符（如 :ref:`runtime-version-access` 中所述）。" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" +"此外，通常希望该版本信息是从版本控制系统的 *标签* （如 ``v1.2.3`` ）中派生" +"的，而不是手动在源代码中更新。" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" +"一些项目可能选择容忍数据输入的重复，并依赖自动化测试来确保不同的值不会出现偏" +"差。" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "另外，项目选择的构建系统可能提供一种方法来定义版本号的单一权威来源。" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "一般而言，选项包括：" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" +"如果代码位于版本控制系统 (VCS)（例如 Git）中，则可以从 VCS 中提取版本。" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" +"该版本可以硬编码到： :file:`pyproject.toml` 文件中——并且构建系统可以将其复制" +"到可能需要的其他位置。" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" +"版本字符串可以被硬编码到源代码中——可以是在一个特殊用途的文件中，例" +"如 :file:`_version.txt`（该文件必须作为项目源代码分发包的一部分进行发布），或" +"者作为特定模块中的一个属性，例如 :file:`__init__.py` 。构建系统随后可以在构建" +"时从运行时位置提取它。" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "请查阅您的构建系统文档以了解其推荐的方法。" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" +"当目标是让分发包及其关联的导入包共享相同的版本时，建议项目包括一个自动化测试" +"用例，确保 ``import_name.__version__`` 和 " +"``importlib.metadata.version(\"dist-name\")`` 报告相同的值（注意：对于许多项" +"目， ``import_name`` 和 ``dist-name`` 将是相同的名称）。" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "构建系统版本处理" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "以下是一些用于处理版本字符串的构建系统文档的链接。" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "`Flit 分发 `_" + +#: ../source/discussions/single-source-version.rst:56 +msgid "`Hatchling `_" +msgstr "`Hatchling 项目管理器 `_" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" +"`PDM `_" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" +"`Setuptools 工具 `_" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" +"`setuptools_scm 提取 Python 包版本 `_" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "SRC 布局与平面布局" + +#: ../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:`import packages ` 都在顶级目录中。" + +#: ../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:`import packages `) 移动至子目录" +"中。该子目录通常名为 ``src/``，因为其被称为“src 布局”。" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "以下详解 src 布局和平坦布局之间重要的行为差异：" + +#: ../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/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:`editable installation ` ，在" +"测试中使用常规安装）。" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "src布局可以帮助避免意外地使用开发中的代码副本。" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +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." +msgstr "" +"Python解释器将当前工作目录设为第一导入路径。这意味着如果在当前工作目录中存在" +"与安装的包同名的包时将会使用当前目录的包。这可能会导致项目打包工具被错误地配" +"置，进而导致文件不被包含在发行版本。" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" +"src布局有助于避免这种情况，它将导入包保存在与项目根目录不同的目录中，确保使用" +"已安装的副本。" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" +"`src` 布局有助于确保 :doc:`editable installation ` 仅能导入那些本应可导入的文件。" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" +"当可编辑安装使用 `路径配置文件 `_ 来实现并将目录添加到导入路径时，这一点尤为重要。" + +#: ../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/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "从源代码使用 `src` 布局中运行命令行界面" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" +"由于前述的 `src` 布局的特点，命令行界面不能直接从 :term:`source tree " +"` 运行，而需要将包安装为 :doc:`Development Mode " +"` 以便进行测试。由于在某些情况下这可能" +"不太实际，一个解决方法是在通过其 :file:`__main__.py` 文件调用时，将包文件夹添" +"加到 Python 的 :py:data:`sys.path` 中：" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +msgid "Versioning" +msgstr "版本" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "本讨论涵盖了 Python 包版本控制的所有方面。" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "有效的版本编号" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" +"不同的 Python 项目可能根据各自的需求使用不同的版本控制方案，但为了与" +"像 :ref:`pip` 这样的工具兼容，所有这些项目都需要遵循一个灵活的版本标识符格" +"式，权威参考是 :ref:`specification of version specifiers ` 。以下是一些版本号的示例 [#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``" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "alpha 版本： ``1.2.0a1``" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "测试版本： ``1.2.0b1``" + +#: ../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 "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "alpha 版本的后续发布（可能，但不鼓励）： ``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``" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +msgstr "带 epoch 的版本（不鼓励）：``1!1.0``" + +#: ../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 "" +"项目可以使用一系列的预发布版本，以便在最终发布之前支持用户进行测试。步骤顺序" +"为：alpha 版本、beta 版本、候选发布版本、最终发布版本。默认情况下，pip 和其他" +"现代 Python 包安装器在决定安装哪些依赖版本时，会忽略预发布版本，除非明确请求" +"（例如，使用 ``pip install pkg==1.1a3`` 或 ``pip install --pre pkg`` ）。" + +#: ../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/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 "" +"后发布版本用于修复最终版本中的轻微错误，这些错误不会影响分发的软件，例如修正" +"发布说明中的错误。它们不应用于修复 bug；这些应该通过发布新的最终版本来处理" +"（例如，在使用语义版本控制时，增加第三个版本号）。" + +#: ../source/discussions/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" +"最后，epoch 希望修复更改版本方案时的排列顺序。举例来说，如果一个项目曾使用日" +"历化版本控制，版本号为 ``23.12``，后来切换到语义化版本，版本号为 ``1.0``。那" +"么 ``1.0`` 和 ``23.12`` 之间的比较会出错。为了修复这一点，新的版本号会有显式 " +"epoch ，就像 ``1!1.0`` ，目的是为了使其被视作相较旧版本号更新的版本号。不过，" +"我们不鼓励这种做法，更好的做法是使用不可能造成用户困惑的更高版本号，比如 " +"``100.0``。" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "语义版本控制与日历版本控制" + +#: ../source/discussions/versioning.rst:62 +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:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" +"选择下一个版本号时有已知的例外情况。维护者可能会有意识地选择打破“最后一个版本" +"段只包含向后兼容的更改”这一假设。其中一个例子是当需要解决安全漏洞时。安全更新" +"通常以补丁版本发布，但不可避免地包含破坏性更改。" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "语义版本控制" + +#: ../source/discussions/versioning.rst:87 +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:90 +msgid "*major* when they make incompatible API changes," +msgstr "*重大(major)* 当他们进行不兼容的 API 更改时，" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "*轻微(minor)* 当他们以向后兼容的方式添加功能时，以及" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "*补丁(patch)*，当他们进行向后兼容的错误修复时。" + +#: ../source/discussions/versioning.rst:94 +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 项目使用类似于语义版本控制的版本方案。然而，大多数项目，尤其是" +"较大的项目，并不严格遵循语义版本控制，因为许多变化在技术上是破坏兼容性的，但" +"仅影响一小部分用户。这类项目倾向于在不兼容性较高时递增主版本号，或发出项目重" +"大变化的信号，而不是为了任何微小的不兼容性 [#semver-strictness]_ 。相反，主版" +"本号的跃升有时也用来暗示重要但向后兼容的新特性。" + +#: ../source/discussions/versioning.rst:104 +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:`compatible release version specifiers ` ，并使用 ``~=`` 运算符。例如， ``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:113 +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 规范 ` 的" +"第 1-8 条。" + +#: ../source/discussions/versioning.rst:116 +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 versioning policy ` ）。著名的 :doc:`NumPy ` 科学计算包明确使用“宽松”语义" +"版本控制，其中递增次要版本可能包含向后不兼容的 API 更改（ :doc:`NumPy " +"versioning policy ` ）。" + +#: ../source/discussions/versioning.rst:125 +msgid "Calendar versioning" +msgstr "日历化版本（Calendar versioning）" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" +"语义版本控制并不适用于所有项目，例如具有基于定期时间的发布节奏和弃用流程的项" +"目，这些弃用流程会在删除某个功能之前为多个版本提供警告。" + +#: ../source/discussions/versioning.rst:131 +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 "" +"基于日期的版本控制，或称为`calendar versioning `_ (CalVer) ，的一个" +"主要优势是，通过版本号就可以直接判断特定版本的基础功能集已经有多旧。" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" +"日历版本号通常采用 *year.month* 的形式（例如，2023 年 12 月为 23.12）。" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr ":doc:`Pip ` ，标准 Python 包安装程序，使用日历版本控制。" + +#: ../source/discussions/versioning.rst:143 +msgid "Other schemes" +msgstr "其他模式" + +#: ../source/discussions/versioning.rst:145 +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:151 +msgid "" +"Combinations of the above schemes are possible. For example, a project may " +"combine date-based versioning with serial versioning to create a " +"*year.serial* numbering scheme that readily conveys the approximate age of a " +"release, but doesn't otherwise commit to a particular release cadence within " +"the year." +msgstr "" +"上述版本控制方案可以组合使用。例如，一个项目可以将基于日期的版本控制与序列版" +"本控制结合，创建一个 *年.序列(year.serial)* 的编号方案，这样既能直观地传达一" +"个版本的发布大致年份，同时又不承诺在该年内的具体发布频率。" + +#: ../source/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:`local version identifier ` 的概念，可以用来标识不打算公开发布的本地开发构建，或由重新分发" +"者维护的已修改版本。" + +#: ../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+gd00980f.d20231217\" 的版本。" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "在运行时访问版本信息" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" +"可以在运行时使用标准库的 :func:`importlib.metadata.version` 函数 :: 获取当前" +"环境中本地可用的所有 :term:`distribution packages ` 的" +"版本信息：" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" +"许多项目还选择对其顶级 :term:`import packages ` 进行版本控" +"制，方法是提供包级别 ``__version__`` 属性::" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" +"对于希望确保版本查询调用（例如``pip -V``）尽快运行的 CLI 应用程序来说，此技术" +"特别有价值。" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" +"希望确保其报告的分发包和导入包版本彼此一致的包发布者可以查看 :ref:`single-" +"source-version` 讨论，了解可能的实现方法。" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../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 "" +"本文档旨在概述流程，用于发布/分发一个 :term:`distribution package " +"` 包到 `Python Package Index (PyPI)`_。它是为包发布者编" +"写的，这些人被假定为包的作者。" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "最后两个步骤通常由 :ref:`pip` 在终端用户运行 ``pip install`` 时执行。" + +#: ../source/flow.rst:50 +msgid "The steps above are described in more detail below." +msgstr "下面将更详细地描述上述步骤。" + +#: ../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 "" + +#: ../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 "" + +#: ../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`、" +"` trampolim`_ 和 `whey`_ 。每个工具的文档都会显示需要在 ``[build-system]`` 表" +"中放置的内容。" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../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 "包含已编译扩展的特定种类的 :term:`Built Distribution`。" + +#: ../source/glossary.rst:14 +msgid "Build Backend" +msgstr "" + +#: ../source/glossary.rst:17 +msgid "" +"A library that takes a :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../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 :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 "" +"一种 :term:`分发 ` 格式，包含只需移动到目标系统上正确位" +"置的文件和元数据，即可安装。:term:`Wheel` 是这样一种格式，而 :term:`源分发 " +"`不是，因为它需要一个构建步骤才能安装。 " +"这种格式并不意味着必须预编译 Python 文件（:term:`Wheel` 有意不包括编译好的 " +"Python 文件）。更多信息见 :ref:`package-formats`。" + +#: ../source/glossary.rst:56 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "发行版存档" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "发行版" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" +"版本化的压缩文件包含 Python :term:`packages `、:term:`modules ` 和其他用于分发 :term:`Release` 的资源文" +"件。这样的压缩文件是最终用户将从 Internet 下载并安装的文件。" + +#: ../source/glossary.rst:97 +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:`Import Package`（通常也被叫做“包‘）或另一种分发类型（如 " +"Linux 发行版或 Python 语言发行版）混淆，这两者常用单个术语“distribution”表" +"示。有关含义差别的详细解释，见 :ref:`distribution-package-vs-import-" +"package`。" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "Egg" + +#: ../source/glossary.rst:108 +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:`Built Distribution` 格式，由 :ref:`setuptools` 引入，已" +"被 :term:`Wheel` 替代。详见： :ref:`egg-format`." + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "扩展模块" + +#: ../source/glossary.rst:114 +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 "" +"用 Python 实现的低级语言编写的 :term:`Module` ：C/C++ for Python，Java for " +"Jython。通常包含在单个可动态加载的预编译文件中，例如 Unix 上 Python 扩展的共" +"享对象 (.so) 文件、Windows 上 Python 扩展的 DLL（给定 .pyd 扩展）或 Jython 扩" +"展的 Java 类文件。" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "导入包" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "一个Python模块，可以包含其他模块或递归地包含其他包。" + +#: ../source/glossary.rst:127 +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:`Distribution Package` 混淆。这两者间" +"的差异详见 :ref:`distribution-package-vs-import-package`。" + +#: ../source/glossary.rst:133 +msgid "Installed Project" +msgstr "已安装的项目" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "已知良好集 (KGS)" + +#: ../source/glossary.rst:143 +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 "" +"一组相互兼容的指定版本的发行版。 通常，将运行一个测试套件，该套件在一组特定的" +"包被声明为已知良好集之前通过所有测试。 该术语通常用于由多个单独发行版组成的框" +"架和工具包。" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "许可证分类器" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "许可证表达式" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "许可证标识符" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "模块" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "包索引" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" +"一个带有 Web 界面的发行版存储库，用于自动化 :term:`package ` 发现和消费。" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "每个项目索引（Per Project Index）" + +#: ../source/glossary.rst:198 +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:`Project` 标明的私有或其他非规范的 :term:`Package Index` ，作" +"为解决该项目依赖关系的首选或必需的索引。" + +#: ../source/glossary.rst:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "项目" + +#: ../source/glossary.rst:205 +msgid "" +"A library, framework, script, plugin, application, or collection of data or " +"other resources, or some combination thereof that is intended to be packaged " +"into a :term:`Distribution `." +msgstr "" +"计划打包进 :term:`Distribution ` 的库、框架、脚本、插" +"件、应用程序、或数据或其他资源的集合、或其中某些东西的组合。" + +#: ../source/glossary.rst:209 +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:`Distributions `，目前" +"定义项目的另一个实际办法是在项目源码目录下包" +"含 :term:`pyproject.toml`、 :term:`setup.py` 或 :term:`setup.cfg` 文件的东" +"西。" + +#: ../source/glossary.rst:215 +msgid "" +"Python projects must have unique names, which are registered on :term:`PyPI " +"`. Each project will then contain one or " +"more :term:`Releases `, and each release may comprise one or " +"more :term:`distributions `." +msgstr "" +"Python 项目必须具有独特且唯一的名称，这些名字可以在 :term:`PyPI ` 上注册。然后每个项目将包含一个或多个 :term:`Releases " +"` ，每个版本可能包括一个或多个 :term:`distributions ` 。" + +#: ../source/glossary.rst:220 +msgid "" +"Note that there is a strong convention to name a project after the name of " +"the package that is imported to run that project. However, this doesn't have " +"to hold true. It's possible to install a distribution from the project 'foo' " +"and have it provide a package importable only as 'bar'." +msgstr "" +"请注意，有一个强大的约定，即在为运行项目而导入的包的名称之后命名项目。然而，" +"这并不一定是真的。可以从项目“foo”安装一个发行版，并让它提供一个只能作" +"为“bar”导入的包。" + +#: ../source/glossary.rst:226 +msgid "Project Root Directory" +msgstr "项目的根目录" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "项目源码树" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "项目源元数据" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "纯模块 (Pure Module)" + +#: ../source/glossary.rst:257 +msgid "" +"A :term:`Module` written in Python and contained in a single ``.py`` file " +"(and possibly associated ``.pyc`` and/or ``.pyo`` files)." +msgstr "" +"一个 :term:`Module`，使用 Python 编写并包含在单个 ``.py`` 文件 中（可能还有相" +"关的 ``.pyc`` 和/或者 ``.pyo`` 文件）。" + +#: ../source/glossary.rst:260 +msgid "Pyproject Metadata" +msgstr "Pyproject 元数据" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +msgid "Pyproject Metadata Key" +msgstr "Pyproject 元数据密钥" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "Python 包装管理局 （PyPA）" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" +"PyPA 是一个工作组，维护 Python 打包的许多重要项目。他们维护 :doc:`pypa.io " +"` 站点，在`GitHub `_ 上托管项目，并在 " +"`distutils-sig 邮件列表 `_ 和 `Python Discourse 论坛 `__ 上讨论问题。" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "Python 包索引 (PyPI)" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "pypi.org" + +#: ../source/glossary.rst:304 +msgid "" +"`pypi.org `_ is the domain name for the :term:`Python " +"Package Index (PyPI)`. It replaced the legacy index domain name, " +"``pypi.python.org``, in 2017. It is powered by :ref:`warehouse`." +msgstr "" +"`pypi.org `_ 是 :term:`Python Package Index (PyPI)` 的域" +"名。它在2017年取代了旧的索引域名， ``pypi.python.org`` ，并" +"由 :ref:`warehouse` 提供支持。" + +#: ../source/glossary.rst:308 +msgid "pyproject.toml" +msgstr "pyproject.toml" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "发行版 （Release）" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "要求 (Requirement)" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "需求说明符" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "需求文件" + +#: ../source/glossary.rst:344 +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 "" +"一个包含 :term:`Requirements ` 列表的文件，这些 Requirments 可以" +"使用 :ref:`pip` 来安装。更多信息，请参阅 :ref:`pip` 文档" +"的 :ref:`pip:Requirements Files` 。" + +#: ../source/glossary.rst:348 +msgid "Root License Directory" +msgstr "根许可证目录" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "setup.py" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "setup.cfg" + +#: ../source/glossary.rst:369 +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:372 +msgid "Source Archive" +msgstr "源代码归档" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "源代码分发（或“sdist”）" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "系统包 (System Package)" + +#: ../source/glossary.rst:391 +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:394 +msgid "Version Specifier" +msgstr "版本说明符 (Version Specifier)" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "虚拟环境 (Virtual Environment)" + +#: ../source/glossary.rst:405 +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:`Creating and using Virtual Environments`." + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "Wheel" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +msgid "Wheel Project" +msgstr "Wheel 项目" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "工作集 (Working Set)" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "分析 PyPI 软件包的下载情况" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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上托管的软件包 " +"(packages) 的下载情况。例如，你可以用它来发现用于下载软件包的 Python 版本的分" +"布。" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "背景" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "由于一些原因，PyPI 不显示下载统计数据。[#]_" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "``pip`` 的下载缓存（降低下载次数）" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "内部或非官方的镜像（既可以提高也可以降低下载量）" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "未在 PyPI 上托管的软件包（为了比较）" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "非官方的脚本或令下载量膨胀的尝试（提高下载量）" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "已知的历史数据质量问题（降低了下载次数）" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "公共数据集" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +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 project `__ 将下载日志从 PyPI 整合到 `Google BigQuery`_ [#]_ ，在那里它们被" +"存储为一个公共数据集。" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "开始设置" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 项目上启用 BigQuery API 。无需信用卡，你可以 `使用无需信用卡的 " +"BigQuery 免费套餐 `__ 每月运行高达 " +"1TB 的查询" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "导航到 `BigQuery web UI`_ 。" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "创建一个新的项目。" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" +"启用`BigQuery API `__。" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" +"关于如何开始使用 BigQuery 的更多详细说明，请查看`BigQuery 快速入门指南 " +"`__ 。" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "数据框架" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "列" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "描述" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "例子" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "时间戳 (timestamp)" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "日期和时间 (Date and time)" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "``2020-03-09 00:33:03 UTC``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "file.project" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "项目名称" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "``pipenv``, ``nose``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "file.version" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "包版本" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "``0.1.6``, ``1.4.2``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "安装程序" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "pip, :ref:`bandersnatch`" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "details.python" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "Python 版本" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "``2.7.12``, ``3.6.4``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "有用的查询" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "在 `BigQuery网页用户界面`_ 中通过点击 \"Compose query \"按钮运行查询。" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "-计算软件包的下载量" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "下面的查询统计了 \"pytest \" 项目的总下载次数。" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "num_downloads" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "26190085" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "要只计算 pip 的下载次数，请过滤 ``details.installer.name`` 列。" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "24334215" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "一段时间内的包下载" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" +"要按月下载量分组，请使用 ``TIMESTAMP_TRUNC`` 函数。同时按这一栏过滤可以减少相" +"应的费用。" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "month" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "1956741" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "2018-01-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "2344692" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "2017-12-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "1730398" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "2017-11-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "2047310" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "2017-10-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "1744443" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "2017-09-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "1916952" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "2017-08-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +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/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "python" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "3.7" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "18051328726" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "3.6" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "9635067203" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "3.8" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "7781904681" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "2.7" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "6381252241" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "空" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "2026630299" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "3.5" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "1894153540" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "url" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "" +"https://files.pythonhosted.org/packages/eb/" +"45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" +"sampleproject-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "" +"https://files.pythonhosted.org/packages/56/0a/" +"178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" +"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +msgid "" +"https://files.pythonhosted.org/packages/" +"63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" +"sampleproject_nomura-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "注意事项" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "附加工具" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +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:273 +msgid "``google-cloud-bigquery``" +msgstr "``google-cloud-bigquery``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" +"你也可以通过 BigQuery API 和 BigQuery 的官方 Python 客户端库 `google-cloud-" +"bigquery`_ 项目，以编程方式访问公共 PyPI 下载统计数据集。" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "``pypinfo``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" +"`pypinfo`_ 是一个命令行工具，它提供对数据集的访问，并可以生成一些有用的查询。" +"例如，你可以用 ``pypinfo package_name`` 命令来查询某个软件包的总下载次数。" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "使用 pip 安装 `pypinfo`_ 。" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "使用方法：" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "``pandas-gbq``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "`pandas-gbq`_ 项目允许通过 `Pandas`_ 来访问查询结果。" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "参考" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" +"`PyPI 下载计数的废弃电子邮件 `__" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" +"`PyPI BigQuery 数据集公告邮件 `__" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "创建和发现插件" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "自动发现插件的方法主要有三种：" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "`使用命名惯例`_." + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" +"包可以拥有在 :ref:`entry-points` 中描述的插件元数据。通过指定这些元数据，包声" +"明它包含某种特定类型的插件。另一个支持这种插件的包可以使用这些元数据来发现该" +"插件。" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" +"例如，如果您有一个名为 ``myapp-plugin-a`` 的包，并且它的 ``pyproject.toml`` " +"中包含以下内容：" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +msgid "" +"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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" +"在这个例子中， ``discovered_plugins`` 将是一个类型" +"为 :class:`importlib.metadata.EntryPoint` 的集合:" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" +"现在可以通过执行 ``discovered_plugins['a'].load()`` 来导入您选择的模块。" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +msgid "" +"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 "" +"在 :file:`setup.py` 中的 ``entry_point`` 规范相当灵活，具有很多选项。建议仔细" +"阅读整个关于 :doc:`entry points ` 的章节。" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" +"由于此规范是 :doc:`standard library ` 的一" +"部分，因此除了 setuptools 之外，大多数打包工具都提供了定义 entry points 的支" +"持。" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "创建以及打包命令行工具" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" +"本指南将引导您创建和打包一个独立的命令行应用程序，该应用程序可以通" +"过 :ref:`pipx` 安装，pipx 是一个创建和管理 :term:`Python Virtual " +"Environments ` 的工具，并暴露包的可执行脚本（以及可用的" +"手册页）以供命令行使用。" + +#: ../source/guides/creating-command-line-tools.rst:12 +msgid "Creating the package" +msgstr "创建包" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" +"首先，创建一个源代码树用于该 :term:`project ` 。为了举例说明，我们将" +"构建一个简单的工具，根据命令行提供的参数输出对某个人的问候（一个字符串）。" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "待办" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "在另一个指南或讨论中对 Python 包的最佳结构提出建议，并在此处链接。" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +msgid "``pyproject.toml``" +msgstr "``pyproject.toml``" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +msgid "Installing the package with ``pipx``" +msgstr "用 ``pipx`` 安装包" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +msgid "Conclusion" +msgstr "完成" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +msgid "2023-12-14" +msgstr "2023-12-14" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" +"首先，确保你已经满足了 :ref:`requirements for installing packages " +"`。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "安装 \"twine\" [1]_:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"The most important file is :file:`setup.py` which exists at the root of your " +"project directory. For an example, see the `setup.py `_ " +"in the `PyPA sample project `_." +msgstr "" +"最重要的文件是 :file:`setup.py` ，它存在于你项目目录的根部。如果你想有一个例" +"子作为参考，请参阅 `PyPA 样本项目 `_ " +"的 `setup.py `_。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr ":file:`setup.py` 有主要有两个功能：" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" +":file:`setup.cfg` 是一个 ini 文件，包含 :file:`setup.py` 命令的默认。 例如，" +"参阅 `PyPA 样本项目 `_ 中的 " +"`setup.cfg `_ ." + +#: ../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 "" +"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 "" +"所有项目都应该包含一个涵盖项目目标的 readme 文件。最常见的格式是带有 \"rst " +"\" 扩展名的 `reStructuredText `_ ，" +"尽管这不是必须的；同时也支持 `Markdown `_ 的多种变体（请看 ``setup()`` " +"的 :ref:`long_description_content_type ` 参数）。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" +"有关示例，请参阅来自` PyPA 示例项目 `_ 的 `README.md `_ 。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "MANIFEST.in" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" +"然而，你可能不是必须要使用 :file:`MANIFEST.in`。举个例子，`PyPA 示例项目" +"`_ 已经删除了它的清单文件，因为所有必" +"要的文件已经被 :ref:`setuptools` 43.0.0 和更新的版本所包含。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr ":file:`MANIFEST.in` 不影响诸如 wheels 这样的二进制分发。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "LICENSE.txt" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" +"每个软件包都应该包括一个详细说明发行条款的许可证文件。在许多司法管辖区，没有" +"明确许可证的软件包不能被版权持有人以外的任何人合法使用或分发。如果你不确定选" +"择哪种许可证，你可以使用诸如 `GitHub 的选择许可证 `_ 等资源，或者咨询律师。" + +#: ../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/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" +"有关示例，请参阅 `PyPA 示例项目 `_ 中" +"包含的 `sample `_ 。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "setup() 参数" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" +"如上所述， :file:`setup.py` 的主要特点是它包含一个全局的 ``setup()`` 函数。 " +"这个函数的关键字参数规定了如何定义你项目的具体细节。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" +"所给出的大部分片段摘自 `PyPA 示例项目 `_ 中的 `setup.py `_ 。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" +"请参阅 :ref:`Choosing a versioning scheme` 了解更多如何使用版本向你的用户传达" +"兼容性信息的信息。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "``packages``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +msgstr "``py_modules``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:198 +msgid "" +"If your project contains any single-file Python modules that aren't part of " +"a package, set ``py_modules`` to a list of the names of the modules (minus " +"the ``.py`` extension) in order to make :ref:`setuptools` aware of them." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +#, fuzzy +msgid "``install_requires``" +msgstr "install_requires" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "``package_data``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "``data_files``" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "在 「开发模式」(development mode) 下工作" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "Wheels" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "将你的项目上传到 PyPI" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "创建一个账户" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" +"首先，你需要一个 :term:`PyPI ` 用户账户。你可以 " +"`使用 PyPI 网站上的表格创建一个账户 `_ 。" + +#: ../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 "现在你将创建一个PyPI `API 令牌`_ ，这样你就能安全地上传你的项目。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" +"到 https://pypi.org/manage/account/#api-tokens 上创建一个新的 `API token`_ ；" +"不要把其范围限制在一个特定的项目上，因为你正在创建一个新的项目。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "**在复制和保存令牌之前不要关闭页面──你不会再看到该令牌。**" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" +"为了避免每次上传时都要复制和粘贴令牌，你可以创建一个 :file:`$HOME/.pypirc` 文" +"件:" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" +"有关更多详细信息，请参见 :file:`.pypirc` 的 :ref:`specification `。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "上传你的发行版" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" +"一旦有了账户，你就可以使用 :ref:`twine` 将你的发行版上传到 :term:`PyPI " +"`。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" +"无论项目是否已经存在于 PyPI 上，上传发布版的过程都是一样的——如果它还不存在，" +"那么在上传第一个发布版时，它将被自动创建。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" +"对于第二个及以后的版本，PyPI 只要求新版本的版本号与以前的任何版本不同。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" +"你可以通过浏览 URL ``https://pypi.org/project/`` 来了解你的软" +"件包是否已经成功上传，其中 ``sampleproject`` 是你上传项目的名称。你的项目可能" +"需要一两分钟才能出现在网站上。" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" +"根据你的平台，这可能需要 root 或管理员权限。 :ref:`pip` 目前正在考虑通过`使用" +"户安装（user installs）成为默认行为 `_ 来改变这一点。" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "放弃对旧版 Python 的支持" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "要求" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "定义所需的 Python 版本" + +#: ../source/guides/dropping-older-python-versions.rst:48 +msgid "1. Install twine" +msgstr "1. 安装 twine" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "2. 指定支持的 Python 发行版的版本范围" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" +"你可以指定版本范围和排除规则（遵照 :ref:`version-specifiers` 规范） ，如至少 " +"Python 3.9。或至少 Python 3.7及以上版本，跳过 3.7.0 和 3.7.1 版本：" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "3. 发布前验证元数据（Metadata）" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "你可以看到生成文件的内容是这样的：" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "按 :ref:`Uploading your Project to PyPI` 中的建议继续。" + +#: ../source/guides/dropping-older-python-versions.rst:120 +msgid "Dropping a Python version" +msgstr "放弃一个 Python 版本" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "托管你自己的简单存储库" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr ":ref:`simpleindex`" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr ":ref:`pypiserver`" + +#: ../source/guides/hosting-your-own-index.rst:83 +msgid ":ref:`pypiprivate`" +msgstr ":ref:`pypiprivate`" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr ":ref:`pypicloud`" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr ":ref:`pywharf`" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr ":ref:`pulppython`" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +msgid ":ref:`pip2pi`" +msgstr ":ref:`pip2pi`" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr ":ref:`dumb-pypi`" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +msgid "`Apache `_" +msgstr "`Apache `_" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" +"简单存储库协议的完整文档，请查看 :ref:`simple repository API `。" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../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-08" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr ":ref:`bandersnatch`" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../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 "" + +#: ../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 "" +"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 "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "从源代码构建" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +msgstr "Linux 分发包" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "Windows 安装程序" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" +"这些安装程序中提供的扩展通常与 python.org 上发布的 CPython Windows 安装程序兼" +"容。" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +msgstr "macOS 安装程序和软件包管理器" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" +"macOS 用户还可以使用 Linux 发行版风格的软件包管理器，如 ``Homebrew`` 。SciPy " +"网站有更多关于使用 Homebrew 来 `在 macOS 上安装SciPy 的细节 `_ 。" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "SciPy 发行版" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" +"`Spack `_ 是一个灵活的软件包管理器，旨在支持" +"多个版本、配置、平台和编译器。它是为了支持大型超级计算中心和科学应用团队的需" +"要而建立的，因为他们必须经常以多种不同的方式构建软件。Spack 不限于 Python；它" +"可以安装 ``C`` 、 ``C++`` 、 ``Fortran`` 、 ``R`` 和其他语言的软件包。 它是非" +"破坏性的；安装一个包的新版本不会破坏现有的安装，因此许多配置可以在同一个系统" +"上共存。" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "conda 跨平台软件包管理器" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" +"Anaconda `Anaconda `_ 是 Anaconda 发布" +"的 Python 发行版。它是用于大数据和科学使用的开源包的稳定集合，以及管理 conda " +"环境图形界面工具的集合。" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "安装独立命令行工具" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" +"许多软件包提供命令行程序。这样的软件包的例子有`mypy `_, `flake8 `_, `black `_, 和 :ref:`pipenv`。" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" +":ref:`pipx` 解决这个问题的办法是为每个软件包创建一个虚拟环境，同时也确保其应" +"用程序可以通过你 `$PATH`` 上的目录访问。这允许每个软件包在升级或卸载时不会与" +"其他软件包产生冲突，并允许你在任何地方安全地运行程序。" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "pipx 只适用于 Python 3.6 以上版本。" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "pipx 是用 pip 安装的:" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" +"``ensurepath`` 确保程序目录在你的 ``$PATH``上。你可能需要重新启动你的终端以使" +"这个更新生效。" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" +"现在你可以用 ``pipx install`` 来安装软件包，并从任何地方运行软件包的程序。" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "例如：" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" +"要查看用 pipx 安装的软件包列表，以及哪些应用程序可用，请使用 ``pipx list`` ：" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "要升级或卸载软件包：" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "pipx 可通过 pip 进行升级或卸载：" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" +"pipx 还允许你在一个临时的、短暂的环境中安装和运行最新版本的程序。示例：" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "要查看 pipx提供的全部命令列表，请运行：" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +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 "用 Linux 软件包管理器安装 pip/setuptools/wheel" + +#: ../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 section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "Fedora" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "CentOS/RHEL" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "要为系统 Python 安装 pip 和 wheel，有两个选项：" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "要额外升级setuptools ，请运行：" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" +"关于 Redhat，请参阅此处：https://developers.redhat.com/products/" +"softwarecollections/overview" + +#: ../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 "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "Arch Linux" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +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/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../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 "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" +"要创建虚拟环境，转到项目目录并运行下列命令。这会在名为 ``.venv`` 的本地文件夹" +"中创建一个新的虚拟环境：" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" +"第二个参数是创建虚拟环境的位置。一般来说，你可以直接在你的项目中创建它，并称" +"之为 ``.venv`` 。" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "`venv`` 将在 `.venv`` 文件夹中创建一个虚拟的 Python 安装。" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" +"你应该使用 ``.gitignore`` 或类似的方法将你的虚拟环境目录从你的版本控制系统中" +"排除。" + +#: ../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 "" +"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 "" +"在你能开始在虚拟环境中安装或使用包之前，你需要 ``激活`` 它。激活虚拟环境将把" +"虚拟环境专用的 ``python`` 和 ``pip`` 可执行文件放入 shell 的 ``PATH`` 中 。" + +#: ../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 "要确认虚拟环境已激活，请检查 Python 解释器的位置：" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" +"当虚拟环境被激活时，pip 会将软件包安装到该特定环境中。这样，您就可以在 " +"Python 应用程序中导入和使用软件包。" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "停用虚拟环境" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "如果要切换项目或离开虚拟环境，请 ``停用`` 环境：" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "重新激活一个虚拟环境" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst: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/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "在此之后，最新版本的 pip 应该被安装在你的用户站点上：" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" +"Windows 的 Python 安装程序包括 pip。你可以运行下列命令确保 pip 为最新：" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst: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 安装软件包" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" +"虚拟环境被激活后，你可以安装软件包。使用 ``pip install`` 命令来安装软件包。" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +msgid "Install a package" +msgstr "安装一个软件包" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" +"比如，让我们从 :term:`Python Package Index (PyPI)` 安装 `Requests`_ 库：" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "pip应该下载 request 及其所有的依赖项并安装它们：" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +msgid "Install a specific package version" +msgstr "安装特定版本的软件包" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" +"pip 允许你使用 :term:`version specifiers ` 指定安装哪个版" +"本的软件包。例如，要安装一个特定版本的 ``requests``:" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "要安装最新的 ``2.x`` 版本的 requests：" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "要安装预发布（pre-release）版本的软件包，请使用 ``--pre`` 标志：" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +msgid "Install extras" +msgstr "安装附加功能" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" +"有些软件包有可选的 `extras`_ 。你可以在括号中指定额外的东西来告诉 pip 安装它" +"们：" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +msgid "Install a package from source" +msgstr "从源文件安装" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" +"pip 可以直接从源代码中安装软件包。例如，安装 ``google-auth`` 目录中的源代码：" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +msgid "" +"Additionally, pip can install packages from source in :doc:`development mode " +"`, meaning that changes to the source " +"directory will immediately affect the installed package without needing to " +"re-install:" +msgstr "" +"此外，pip 可以在 :doc:`development mode ` 下从源码安装软件包，这意味着源码目录的变化将立即影响已安装" +"的软件包，而不需要重新安装：" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" +"pip 可以直接从他们的版本控制系统中安装软件包。例如，你可以直接从 git 仓库中安" +"装：" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" +"关于支持的版本控制系统和语法的更多信息，请参见 pip 的文档：:ref:`VCS Support " +"` 。" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "从本地档案安装" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" +"如果你在一个连接性有限的系统上安装软件包，或者你想严格控制发行软件包的来源，" +"这很有用。" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +msgid "Install from other package indexes" +msgstr "从其他软件包索引中安装" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" +"如果你想从非 :term:`Python Package Index (PyPI)` 索引下载软件包，你可以使用 " +"``--index-url`` 标志：" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "升级软件包" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "使用一个 requirements 文件" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +msgstr "Pip 可以使用 ``freeze`` 命令来导出所有已安装软件包及其版本的列表：" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:495 +msgid "Which will output a list of package specifiers such as:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "用 virtualenv 安装软件包" + +#: ../source/guides/installing-using-virtualenv.rst:4 +msgid "" +"This guide discusses how to install packages using :ref:`pip` " +"and :ref:`virtualenv`, a tool to create isolated Python environments." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +msgid "Licensing Examples" +msgstr "许可示例" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "基础示例" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "高级示例" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "表达式示例" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../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 "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" +"Python 项目的 README 文件通常被命名为 ``README``, ``README.txt``, " +"``README.rst``, 或是 ``README.md``。" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" +"`reStructuredText `_ (没有 Sphinx " +"扩展)" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" +"Markdown（默认情况下 `GitHub 风格 Markdown `_ ，或`CommonMark `_ ）" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" +"通常将 README 文件保存在项目的根目录中，与 :file:`setup.py` 文件位于同一目录" +"中。" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "在软件包的元数据中包含你的 README" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:33 +msgid ":ref:`description-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:34 +msgid ":ref:`description-content-type-optional`" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" +"如果你使用 GitHub 风格的 Markdown 来写项目的描述，请确保你升级了以下工具：" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "``setuptools >= 38.6.0``" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +msgstr "" +"安装最新版本的 `twine `_ ；需要1.12.0版或更高" +"版本：" + +#: ../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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../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 "" +":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/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 "``pypi.org`` 是2016年9月起的默认上传平台。" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "``twine`` 1.8.0" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "``setuptools`` 27.0.0" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../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 "" +"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 (testpypi.python.org) 不再可用；请使用 `test.pypi.org " +"`_ 代替。如果你使用 TestPyPI ，你必须更新你" +"的 :file:`$HOME/.pypirc` 以处理 TestPyPI 的新位置，例如，用 ``https://" +"test.pypi.org/legacy/`` 替换 ``https://testpypi.python.org/pypi`` ：" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "注册新的用户账户" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" +"为了帮助减轻针对 PyPI 的垃圾邮件攻击，通过 ``pypi.python.org`` 的新用户注册已" +"于 *2018年2月20日* *关闭* 。在``pypi.org``的新用户注册是开放的。" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "浏览软件包" + +#: ../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." +msgstr "" +"虽然 ``pypi.python.org`` 仍可能用于其他 PyPA 文档的链接中使用，但浏览软件包的" +"默认界面是 ``pypi.org`` 。pypi.python.org 这个域名现在会重定向到 pypi.org ，" +"并可能在未来某个时候被禁用。" + +#: ../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 "``pypi.org`` 是下载软件包的默认主机。" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "管理已发布的软件包和版本" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" +"``pypi.org`` 为登录用户提供了一个全功能的界面来管理他们发布的软件包和版本。" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "从哪开始？" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr ":ref:`distributing-packages`" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../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/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +msgid ":ref:`pyproject-toml-spec`" +msgstr ":ref:`pyproject-toml-spec`" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "多版本安装" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../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" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "缺点" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "扩展模块生命周期" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "Linux 的二进制扩展" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "macOS 的二进制扩展" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "发布二进制扩展" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../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 "" +"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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" +"如果你没有 TestPyPI 账户，那么你就需要创建它。这和普通的 PyPI 账户不一样。" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "创建一个工作流定义" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" +"GitHub CI/CD工作流程是在 YAML 文件中声明的，它们存储在你仓库的 ``.github/" +"workflows/`` 目录下。" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "让我们创建一个 ``.github/workflows/publish-to-pypi.yml`` 文件。" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "用一个有意义的名字开始，并定义让 GitHub 运行这个工作流程的事件：" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" +"这将把您的版本库下载到 CI 运行程序中，然后安装并激活最新的 Python 3 版本。" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "定义一个工作流程的工作环境" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "将发行版发布到 PyPI" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "就这些了，伙计们!" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "构建和发布" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +msgid "Installation" +msgstr "安装" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" +"`Travis CI `_ 提供了一个 Linux 和一个 macOS 环境。" +"Linux 环境是 Ubuntu 12.04 LTS 服务器版 64 位，而在撰写本文时 macOS 的版本是 " +"10.9.2。" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" +"`Appveyor `_ 提供一个 Windows 环境（Windows " +"Server 2012）。" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" +"`Travis CI`_ 和 Appveyor_ 都需要一个 `YAML `_ 格式的文件作" +"为测试的说明规范。如果任何测试失败，可以检查该特定配置的输出日志。" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../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 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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "``DISTUTILS_USE_SDK``" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "``MSSdk``" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "``INCLUDE``" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +msgstr "``LIB``" + +#: ../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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "虚拟环境 (Virtual Environments)" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +msgid "Installing packages" +msgstr "安装软件包" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +msgid "Building distributions" +msgstr "构建发行版" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "上传到 PyPI" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr ":ref:`Flit`," + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr ":ref:`Hatch`," + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr ":ref:`PDM`," + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr ":ref:`Pipenv`," + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr ":ref:`Poetry`," + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "注册你的账户" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" +"你可以告诉 :ref:`pip` 从 TestPyPI，而非 PyPI 下载软件包，方法是指定 ``--" +"index-url`` 标记：" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "在 :file:`.pypirc` 中设置 TestPyPI" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "写入你的 ``pyproject.toml``" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "``name``" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" +"项目名称必须由 ASCII 字母、数字、下划线 \"``_``\"、连字符 \"``-``\" 和句号 " +"\"``.``\" 组成。名字开头结尾不能是下划线、连字符或句号。" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" +"项目名称的比较是不分大小写的，并将任意长的下划线、连字符和/或句号视为相等。例" +"如，如果你注册了一个名为 ``cool-stuff`` 的项目，用户可以使用以下任何一种拼写" +"方式下载它或声明对它的依赖:``Cool-Stuff``, ``cool.stuff``, ``COOL_STUFF``, " +"``CoOl__-.-__sTuFF``." + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +msgid "Put the version of your project." +msgstr "输入项目版本。" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "依赖项和要求" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "关于您的项目" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "``description``" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "``README.rst`` → `reStructuredText `_ (没有 Sphinx扩展）." + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "你也可以像这样明确指定格式：" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "``许可证`` 和 ``许可证文件``" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "hatchling" + +#: ../source/guides/writing-pyproject-toml.rst:313 +msgid "setuptools" +msgstr "setuptools" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "poetry-core" + +#: ../source/guides/writing-pyproject-toml.rst:317 +msgid "uv-build" +msgstr "uv-build" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "``license``" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "``license-files``" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "``keywords``" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "``classifiers``" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" +"应用到你的项目的 PyPI 分类器列表。查看 `full list of possibilities " +"`_ 。" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "完整示例" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +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 包装用户指南" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" +"本指南在 `GitHub`_ 上由 :doc:`Python Packaging Authority ` 维护。" +"我们很乐意接受任何 :doc:`contributions and feedback `。 😊" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "概览和流程" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" +":doc:`tutorial on installing packages ` 文档" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" +"要学习如何打包和分发你的项目，请参阅 :doc:`tutorial on packaging and " +"distributing `" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr ":doc:`discussions/deploying-python-applications`" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "参考" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" +"清单，由 Python 打包管理机构成员维护的 :doc:`other projects ` " +"组成。" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "项目摘要" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "PyPA 项目" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" + +#: ../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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "建造" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "cibuildwheel" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" +"`文档 `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "distlib" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +msgstr "distutils" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "flit" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" +"`Docs `__ | `Issues `__ | `PyPI `__" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "hatch" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`文档 `__ | `GitHub `__ | `PyPI `__" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "打包" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`文档 `__ | `问题 `__ | `GitHub `__ | `PyPI `__" + +#: ../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 软件包的工具，也是现代版本的 Python 所包含的工具。" + +#: ../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 "" +"它提供了从 PyPI 和其他 Python 包索引中查找、下载和安装包的基本核心功能，并且" +"可以通过其命令行界面 (CLI) 合并到广泛的开发工作流程中。" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "Pipenv" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +msgstr "" +":doc:`Docs ` | `源码 `__ | `问" +"题 `__ | `PyPI `__" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "Pipfile" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "`源码 `__" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "pipx" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" +"`文档 `__ | `GitHub `__ " +"| `PyPI `__" + +#: ../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/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "本指南！" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "readme_renderer" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" +"`GitHub 和文档 `__ | `PyPI " +"`__" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "Setuptools" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`文档 `__ | `Issues `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" +"`问题 `__ | `GitHub " +"`__ | `PyPI `__" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "twine" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`文档 `__ | `Issues `__ | `GitHub `__ | `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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "virtualenv" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`文档 `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "Warehouse" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" +"`文档 `__ | `Issues `__ | `GitHub `__" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "wheel" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`文档 `__ | `Issues `__ | `GitHub `__ | `PyPI `__" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "非 PyPA 项目" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "buildout" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" +"`文档 `__ | `Issues `__ | `PyPI `__ | `GitHub `__" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "conda" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" +"`文档 `__ | :gh:`Issues ` " +"| `PyPI `__" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" +"`GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "enscons" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "Hashdist" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" +"`文档 `__ | `GitHub `__" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" +"`文档 `__ | `GitHub `__" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "meson-python" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" +"`文档 `__ | `GitHub `__" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "multibuild" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "`GitHub `__" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`文档 `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`文档 `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "pip-tools" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`文档 `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +":gh:`GitHub ` | `PyPI `__" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "piwheels" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" +"`网站 `__ | :doc:`Docs ` | " +"`GitHub `__" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "poetry" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`文档 `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:644 +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." +msgstr "" +"poetry 是一个命令行工具，用于处理依赖安装和隔离，以及 Python 包的构建和打包。" +"它使用 ``pyproject.toml`` ，并且不依赖 :ref:`pip` 中的解析器功能，而是提供自" +"己的依赖解析器。它试图通过本地缓存的依赖关系元数据来加速用户安装和依赖关系解" +"决的体验。" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +":gh:`GitHub ` | `PyPI `__" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "Pulp-python" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" +"`文档 `__ | :gh:`GitHub ` | `PyPI `__" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" +"`文档 `__ | :gh:`GitHub ` | `PyPI `__" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "pypiprivate" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +":gh:`GitHub ` | `PyPI `__" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "pypiserver" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" +"`GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:711 +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." +msgstr "" +"pypiserver 是一个极简的应用程序，充当组织内的私有 Python :term:`package " +"index `（从一个本地目录），实现了一个简单的 API 和浏览器界面。" +"你可以使用标准的上传工具上传私有软件包，用户可以使用 :ref:`pip` 下载和安装它" +"们，而不用公开发布。使用 pypiserver 的组织通常既从 pypiserver 也从 PyPI 下载" +"软件包。" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`文档 `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +":gh:`GitHub ` | `PyPI `__" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "scikit-build" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`文档 `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "scikit-build-core" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" +"`文档 `__ | `GitHub " +"`__ | `PyPI `__" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "shiv" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`文档 `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" +":gh:`GitHub ` | `PyPI `__" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" +"Spack 不在 PyPI 中（目前），但它不需要安装，从 GitHub 克隆后可以立即使用。" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "zest.releaser" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" +"`文档 `__ | `GitHub `__ | `PyPI `__" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "ensurepip" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" +"`文档 `__ | `问题 `__" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "http.server" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" +":doc:`Docs ` | :gh:`Issues `" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "venv" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" +"`文档 `__ | `问题 `__" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "新闻" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../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 "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "2018年1月" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "添加了一个指向 PyPI 分类器列表的链接。(:pr:`425`)" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "更新了 README.rst 的解释。(:pr:`419`)" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "2017年12月" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +#, fuzzy +msgid "`Kivy `_" +msgstr "`Poetry `_" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "安全" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "详情" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "version" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "Wheel 不包含 setup.py 或 setup.cfg。" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "目录 .dist-info" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "Subdirectory name" +msgstr "子目录名称" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +msgid "``licenses``" +msgstr "``licenses``" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "``license_files``" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "``LICENSES``" +msgstr "``LICENSES``" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr ":file:`.dist-info/licenses/` 目录" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr ":file:`.dist-info/sboms/` 目录" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr ".data 目录" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "例子" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "技术参数" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*object*" +msgstr "*对象*" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Schema version." +msgstr "语义版本." + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "const" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "examples" +msgstr "例子" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bin/python" +msgstr "bin/python" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**version**" +msgstr "**版本**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "version\\_info" +msgstr "version\\_info" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "releaselevel" +msgstr "发行级别" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "serial" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*number*" +msgstr "*编号*" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "附加属性" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**implementation**" +msgstr "**实现**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "cpython" +msgstr "cpython" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**flags**" +msgstr "**标记**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extensions" +msgstr "扩展" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "libpython" +msgstr "libpython" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**headers**" +msgstr "**标头**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "名称" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "版本" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "例子::" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "总结" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "维护者" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "要求" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "reStructuredText 标记：https://docutils.sourceforge.io/" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "依赖群" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "依赖群包括" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +msgid "Package Building" +msgstr "软件包构建" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +msgid "Installing Dependency Groups & Extras" +msgstr "安装依赖群 & 附加内容" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +msgid "Reference Implementation" +msgstr "参考实现" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "名称" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "版本" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:248 +msgid "Python equivalent" +msgstr "Python 同等项" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "类型" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "``os_name``" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr ":py:data:`os.name`" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "``posix``, ``java``" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "``python_version``" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +msgid ":ref:`Version `" +msgstr ":ref:`Version `" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "``3.4``, ``2.7``" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "``python_full_version``" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "``3.4.0``, ``3.5.0b1``" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "``cpython``" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +msgid "``toml``" +msgstr "``toml``" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +msgid "``extras``" +msgstr "``extras``" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +msgid "``dependency_groups``" +msgstr "``dependency_groups``" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" + +#: ../source/specifications/direct-url.rst:52 +#, fuzzy +msgid "``pip install ./app``" +msgstr "``pipx`` 是用 ``pip`` 安装的：" + +#: ../source/specifications/direct-url.rst:53 +msgid "``pip install file:///home/user/app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +#, fuzzy +msgid "``pip install -e ./app``" +msgstr "``pipx`` 是用 ``pip`` 安装的：" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +#, fuzzy +msgid "``pip install app``" +msgstr "``pipx`` 是用 ``pip`` 安装的：" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "子目录中的项目" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "外部管理的环境" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "发行版" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +msgid "package" +msgstr "打包" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "Python 软件包管理器" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "发行版软件包管理器" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "给用户提供虚拟环境方面的指导" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +msgid "Implementation Notes" +msgstr "实现注意事项" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "``pip install``" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "``pip install --prefix=/some/path``" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "``pip install --user``" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +msgid "Installers" +msgstr "安装包" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +msgid "Reference implementation in Python" +msgstr "Python 语言的参考实现" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "建议" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +msgid "Names and normalization" +msgstr "名称和规范化" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +msgid "Name normalization" +msgstr "名称规范化" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "python 标签" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "Python 标签" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "jy: Jython" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "``manylinux``" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "``>=8.1.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "``>=19.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "``>=19.3``" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "``>=20.3``" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "``>=1.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "``>=2.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "``>=3.0.0``" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "``>=3.3.0`` [#]_" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +msgid "``musllinux``" +msgstr "``musllinux``" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "``intel``" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "``i386``, ``x86_64``" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "``i386``, ``ppc``" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "使用方法" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +msgid "Project Status Markers" +msgstr "项目状态标记" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +msgid "Installer semantics: none." +msgstr "安装包语义：无。" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "``已归档``" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +msgid "Installer semantics:" +msgstr "安装包语义：" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +msgid "``deprecated``" +msgstr "``已启用``" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +msgid "``pylock.toml`` Specification" +msgstr "``pylock.toml`` 规范" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "文件名称" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +msgid "``lock-version``" +msgstr "``lock-version``" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +msgid "**Required?**: yes" +msgstr "**必需吗？**: 是" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +msgid "``environments``" +msgstr "``environments``" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +msgid "``dependency-groups``" +msgstr "``dependency-groups``" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "**灵感**: :ref:`pyproject-tool-table`" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +msgid "``[[packages]]``" +msgstr "``[[packages]]``" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "``packages.name``" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +msgid "``packages.version``" +msgstr "``packages.version``" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +msgid "The version of the package." +msgstr "包版本。" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "``packages.marker``" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "``packages.requires-python``" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +msgid "``[[packages.dependencies]]``" +msgstr "``[[packages.dependencies]]``" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "``[packages.vcs]``" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "``packages.vcs.type``" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "所用的版本控制系统类型。" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "``packages.vcs.url``" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "``packages.vcs.path``" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "``packages.vcs.commit-id``" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "``[packages.directory]``" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "``packages.directory.path``" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "``[packages.archive]``" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "``packages.archive.url``" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "``packages.archive.path``" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "``packages.archive.size``" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +msgid "The time the file was uploaded." +msgstr "文件上传时间。" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +msgid "``packages.index``" +msgstr "``packages.index``" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "``[packages.sdist]``" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "``packages.sdist.name``" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "``packages.sdist.upload-time``" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "``packages.sdist.url``" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "``packages.sdist.path``" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "``packages.sdist.size``" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "``packages.sdist.hashes``" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "``[[packages.wheels]]``" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "``packages.wheels.name``" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "``packages.wheels.url``" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "``packages.wheels.path``" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "``packages.wheels.size``" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "``packages.wheels.hashes``" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "**灵感**: :ref:`provenance-object`" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "``[packages.tool]``" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "``pyproject.toml`` 规格" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "``authors``" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "``dependencies``" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "``entry-points``" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "``gui-scripts``" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +msgid "``import-names``" +msgstr "``import-names``" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +msgid "``maintainers``" +msgstr "``maintainers``" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +msgid "Legacy specification" +msgstr "旧规范" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +msgid "Examples:" +msgstr "例子:" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +msgid "Example:" +msgstr "例子：" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr ":file:`sboms/` 子目录" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +msgid "PyPA schemas" +msgstr "PyPA 框架" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "软件包安装元数据" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +msgid "Python Description Formats" +msgstr "Python 描述格式" + +#: ../source/specifications/section-reproducible-environments.rst:3 +msgid "Reproducible Environments" +msgstr "可重复的环境" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +msgid "Normalized Names" +msgstr "规范化的名称" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +msgid "Clients" +msgstr "客户端" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +msgid "HTML Serialization" +msgstr "HTML 序列化" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +msgid "Project List" +msgstr "项目清单" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +msgid "Project Detail" +msgstr "项目详情" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +msgid "JSON Serialization" +msgstr "JSON 序列化" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "示例：" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +msgid "Content-Types" +msgstr "内容类型" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +msgid "Version + Format Selection" +msgstr "版本+格式选择" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "``$type/$subtype``" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "``$type/*``" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "``*/*``" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "源分发归档特性" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +msgid "Definitions" +msgstr "定义" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +msgid "Version scheme" +msgstr "版本格式" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "公开版本识别符" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "本地版本标签必须以 ASCII 字母或数字开头和结尾。" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +msgid "Pre-releases" +msgstr "发布前" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "发布后" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +msgid "Version epochs" +msgstr "重要版本" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +msgid "Normalization" +msgstr "规范化" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +msgid "Integer Normalization" +msgstr "整数规范化" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "本地版本部分" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "版本匹配" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +msgid "Version exclusion" +msgstr "版本排除" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "远程 URL 示例::" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "Python 虚拟环境" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "虚拟环境的 Runtime 检测" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +msgid "Well-known Project URLs in Metadata" +msgstr "元数据中知名项目 URL" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +msgid "Label normalization" +msgstr "标签规范化" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +msgid "Normalized" +msgstr "已规范化" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "``documentation`` （文档）" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "项目的线上文档" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "``docs``" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "资金信息" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "示例行为" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "如何获得支持" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"For something more general, or when you're just not sure, please `open an " +"issue `_ on the `packaging-problems `_ repository on GitHub." +msgstr "" +"如果你想了解更多的情况，或者只是不确定，请在 GitHub 上的 `packaging-problems " +"`_ 存储库中 `开一个新的 issue " +"`_ 。" + +#: ../source/tutorials/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "创建文档" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "" + +#: ../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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "从其他来源安装" + +#: ../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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +msgid "Installing \"Extras\"" +msgstr "安装\"附加功能\"" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "管理应用程序的依赖性" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "确保你安装了最新版本的 PyPA 的 :ref:`build`：" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" +"如果你在安装这些东西时遇到困难，请查看 :doc:`installing-packages` 教程。" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "最后，是时候把你的软件包上传到 Python Package Index 了！" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"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/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "安装后，运行 Twine 上传 :file:`dist`下的所有档案：" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "命令完成后，你应该会看到类似这样的输出：" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"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/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "安装你新上传的软件包" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "请确保在软件包名称中指定你的用户名!" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "pip应该会安装 TestPyPI 的软件包，输出结果应该是这样的：" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "并导入该软件包：" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:498 +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 "" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" + +#~ msgid "" +#~ "Refer to the `pkg_resources documentation `__ for more details." +#~ msgstr "" +#~ "有关更多详细信息，请参阅 `pkg_resources 文档 `__ 。" + +#~ msgid "See" +#~ msgstr "见" + +#~ msgid "" +#~ "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" +#~ "serialization-01" +#~ msgstr "" +#~ "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" +#~ "serialization-01" + +#~ msgid "" +#~ "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" +#~ msgstr "" +#~ "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" + +#~ msgid "**Inspiration**: :ref:` pyproject-tool-table`" +#~ msgstr "**灵感**: :ref:` pyproject-tool-table`" + +#~ msgid "Signing the distribution packages" +#~ msgstr "签署分发包" + +#~ msgid "Additional file information" +#~ msgstr "附加的文件信息" + +#~ msgid "This workflow requires that:" +#~ msgstr "这个工作流程要求：" + +#~ msgid "The latest version of :ref:`twine` is used to upload the package," +#~ msgstr ":ref:`twine`的最新版本被用来上传软件包，" + +#~ msgid "1. Download the newest version of Setuptools" +#~ msgstr "1.下载最新版本的 Setuptools" + +#~ msgid "" +#~ "Ensure that before you generate source distributions or binary " +#~ "distributions, you update Setuptools and install twine." +#~ msgstr "" +#~ "确保在生成源码发行版或二进制发行版之前，更新 Setuptools 并安装 twine。" + +#~ msgid "Steps:" +#~ msgstr "步骤：" + +#~ msgid "``setuptools`` version should be above 24.0.0." +#~ msgstr "``setuptools``版本应该在 24.0.0 以上。" + +#~ msgid "4. Using Twine to publish" +#~ msgstr "4. 使用 Twine 来发布" + +#~ msgid "Make sure you are using the newest version of Twine, at least 1.9." +#~ msgstr "确保你正在使用最新的 Twine 版本，至少为1.9。" + +#~ msgid "" +#~ "For example, you published the Requires-Python: \">=2.7\" as version " +#~ "1.0.0 of your package." +#~ msgstr "" +#~ "例如，你发布了 Requires-Python: \">=2.7\" 作为你软件包的 1.0.0 版本。" + +#~ 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 "" +#~ ":term:`Wheel` is currently considered the standard for :term:`built " +#~ "` and :term:`binary ` packaging " +#~ "for Python." +#~ msgstr "" +#~ ":term:`Wheel`目前被认为是 :term:`built `" +#~ "和 :term:`binary `打包 Python 的标准。" + +#~ msgid "" +#~ "A :term:`Built Distribution` format introduced by :ref:`setuptools`, " +#~ "which is being replaced by :term:`Wheel`. For details, see :doc:`The " +#~ "Internal Structure of Python Eggs ` " +#~ "and `Python Eggs `_" +#~ msgstr "" +#~ ":term:`Built Distribution`格式由 :ref:`setuptools`引入，并正" +#~ "被 :term:`Wheel`取代。 详见 :doc:`Python Eggs 的内部结构" +#~ "` 和 `Python Eggs `_" + +#~ 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 "" +#~ "由官方 :doc:`标准规范 ` 引入" +#~ "的 :term:`Built Distribution` 格式，旨在取代 :term:`Egg` 格式。 Wheel 目前" +#~ "由 :ref:`pip` 支持。" + +#~ msgid "" +#~ "``pip`` and other modern Python package installers ignore pre-releases by " +#~ "default when deciding which versions of dependencies to install." +#~ msgstr "" +#~ "``pip`` 和其他现代的 Python 软件包安装程序在决定安装哪些版本的依赖项时，默" +#~ "认会忽略预发布版本（pre-releases）。" + +#~ msgid "pip provides local caching options," +#~ msgstr "pip 提供本地缓存选项，" + +#~ msgid "" +#~ "devpi provides higher-level caching option, potentially shared amongst " +#~ "many users or machines, and" +#~ msgstr "devpi 提供更高级别的缓存选项，可能在许多用户或机器之间共享，并且" + +#~ msgid "Caching with devpi" +#~ msgstr "使用 devpi 进行缓存" + +#~ msgid "`OpenShift `_" +#~ msgstr "`OpenShift `_" + +#~ msgid "" +#~ "This is the name of your project, determining how your project is listed " +#~ "on :term:`PyPI `. Per :pep:`508`, valid " +#~ "project names must:" +#~ msgstr "" +#~ "这是你的项目名称，这决定了你的项目如何在 :term:`PyPI ` 中列出。 根据 :pep:`508`，有效的项目名称必须是：" + +#~ msgid "Start & end with an ASCII letter or digit." +#~ msgstr "以一个 ASCII 字母或数字开始和结束。" + +#~ msgid "" +#~ "This is the current version of your project, allowing your users to " +#~ "determine whether or not they have the latest version, and to indicate " +#~ "which specific versions they've tested their own software against." +#~ msgstr "" +#~ "这是你的项目的当前版本，允许你的用户确定他们是否有最新的版本，并指出他们对" +#~ "自己的软件进行过哪些具体的测试。" + +#~ msgid "" +#~ "Versions are displayed on :term:`PyPI ` for " +#~ "each release if you publish your project." +#~ msgstr "" +#~ "如果你发布了你的项目，每个版本都会显示在 :term:`PyPI `上。" + +#~ msgid "Give a short and long description for your project." +#~ msgstr "为你的项目提供一个简短和长的描述。" + +#~ msgid "" +#~ "These values will be displayed on :term:`PyPI ` if you publish your project. On ``pypi.org``, the user interface " +#~ "displays ``description`` in the grey banner and ``long_description`` in " +#~ "the section named \"Project Description\"." +#~ msgstr "" +#~ "如果你发布你的项目，这些值将显示在 :term:`PyPI `。在``pypi.org``上，用户界面会在灰色横幅上显示``description``，在" +#~ "名为 \"项目描述 \" 的部分显示 ``long_description``。" + +#~ msgid "" +#~ "``description`` is also displayed in lists of projects. For example, it's " +#~ "visible in the search results pages such as https://pypi.org/search/?" +#~ "q=jupyter, the front-page lists of trending projects and new releases, " +#~ "and the list of projects you maintain within your account profile (such " +#~ "as https://pypi.org/user/jaraco/)." +#~ msgstr "" +#~ "``description``也会显示在项目列表中。例如，它在搜索结果页面（如 https://" +#~ "pypi.org/search/?q=jupyter）、热门项目和新版本的头版列表，以及你在账户资料" +#~ "中维护的项目列表（如 https://pypi.org/user/jaraco/）中可见。" + +#~ msgid "``url``" +#~ msgstr "``url``" + +#~ msgid "Give a homepage URL for your project." +#~ msgstr "为你的项目提供一个主页 URL 。" + +#, fuzzy +#~ msgid "``author``" +#~ msgstr "作者 (author)" + +#~ msgid "Provide details about the author." +#~ msgstr "提供关于作者的详细信息。" + +#~ msgid "" +#~ "Provide a list of classifiers that categorize your project. For a full " +#~ "listing, see https://pypi.org/classifiers/." +#~ msgstr "" +#~ "提供对你的项目进行分类的分类器列表。有关完整列表，请参阅 https://pypi.org/" +#~ "classifiers/ 。" + +#~ msgid "List keywords that describe your project." +#~ msgstr "列出描述你的项目的关键词。" + +#, fuzzy +#~ msgid "``project_urls``" +#~ msgstr "project_urls" + +#~ msgid "And so on." +#~ msgstr "以此类推。" + +#~ msgid "``entry_points``" +#~ msgstr "``entry_points``" + +#~ msgid "" +#~ "The most commonly used entry point is \"console_scripts\" (see below)." +#~ msgstr "最常用的入口点是 \"console_scripts\"（见下文）。" + +#~ msgid "Comparison to .egg" +#~ msgstr "与 .egg 的比较" + +#~ msgid "You can learn more about pipx at https://pypa.github.io/pipx/." +#~ msgstr "要了解 pipx 的更多信息，可以访问 https://pypa.github.io/pipx/。" + +#~ msgid "" +#~ "`Docs `__ | `GitHub `__ | `PyPI `__" +#~ msgstr "" +#~ "`文档< `__ | `GitHub `__ | `PyPI `__" + +#~ msgid "Read about :doc:`/guides/packaging-binary-extensions`." +#~ msgstr "阅读关于 :doc:`/guides/packaging-binary-extensions` 。" + +#, fuzzy +#~ msgid "Current recommendation" +#~ msgstr "创建文档" + +#~ msgid ":file:`README`" +#~ msgstr ":file:`README`" + +#~ msgid "Command" +#~ msgstr "命令" + +#~ msgid ":samp:`include {pat1} {pat2} ...`" +#~ msgstr ":samp:`include {pat1} {pat2} ...`" + +#~ msgid "You can make sure that pip is up-to-date by running:" +#~ msgstr "您可以通过运行以下命令来确保 pip 是最新的：" + +#~ msgid "Installing pip" +#~ msgstr "安装 pip" + +#~ msgid "Installing virtualenv" +#~ msgstr "安装 virtualenv" + +#~ msgid "It should be in the ``env`` directory:" +#~ msgstr "它应该在 ``env`` 目录中：" + +#~ msgid "Leaving the virtual environment" +#~ msgstr "离开虚拟环境" + +#~ msgid "pip can install a package directly from source, for example:" +#~ msgstr "pip 可以直接从源代码安装一个软件包，例如：" + +#~ msgid "Miscellaneous:" +#~ msgstr "杂项：" + +#~ msgid "" +#~ "For interim guidance on this topic, see the discussion in :issue:`this " +#~ "issue <284>`." +#~ msgstr "关于这个主题的临时指南，请参见 :issue:`这个问题 <284>` 中的讨论。" + +#~ msgid "" +#~ "Essential tools and concepts for working within the Python development " +#~ "ecosystem are covered in our :doc:`tutorials/index` section:" +#~ msgstr "" +#~ "我们的 :doc:`tutorials/index` 部分介绍了在 Python 开发生态系统中工作的基本" +#~ "工具和概念：" + +#~ msgid "" +#~ "To get an overview of packaging options for Python libraries and " +#~ "applications, see the :doc:`Overview of Python Packaging `" +#~ msgstr "" +#~ "要获得对 Python 库和应用程序打包选项的概述，请参阅 :doc:`Python 打包概述 " +#~ "`" + +#~ msgid "Learn more" +#~ msgstr "了解更多" + +#~ msgid "" +#~ "Beyond our :doc:`tutorials/index`, this guide has several other resources:" +#~ msgstr "除了我们的 :doc:`tutorials/index` ，本指南还有其他一些资源：" + +#~ msgid "" +#~ "The :doc:`guides/index` section for walk throughs, such as :doc:`guides/" +#~ "installing-using-linux-tools` or :doc:`guides/packaging-binary-" +#~ "extensions`." +#~ msgstr "" +#~ ":doc:`guides/index ` 部分用于排练，例如 :doc:`guides/installing-using-" +#~ "linux-tools ` 或 :doc:`guides/packaging-binary-extensions`。" + +#~ msgid "" +#~ "`Docs `__ | `Issues " +#~ "`__" +#~ msgstr "" +#~ "`文档 `__ | `问题 " +#~ "`__" + +#~ msgid "" +#~ "Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +#~ "token`_. If you have the project on PyPI already, limit the token scope " +#~ "to just that project. You can call it something like ``GitHub Actions CI/" +#~ "CD — project-org/project-repo`` in order for it to be easily " +#~ "distinguishable in the token list. **Don't close the page just yet — you " +#~ "won't see that token again.**" +#~ msgstr "" +#~ "进入 https://pypi.org/manage/account/#api-tokens ，创建一个新的 `API " +#~ "token`_ 。如果你在 PyPI 上已经有了项目，那么请将令牌的范围限制在该项目上。" +#~ "你可以把它叫做 ``GitHub Actions CI/CD — project-org/project-repo``，以便" +#~ "在 token 列表中容易区分。**先不要关闭页面—你不会再次看到该标记。**" + +#~ msgid "" +#~ "In a separate browser tab or window, go to the ``Settings`` tab of your " +#~ "target repository and then click on `Secrets`_ in the left sidebar." +#~ msgstr "" +#~ "在一个单独的浏览器标签或窗口中，进入你的目标存储库的 ``Settings`` 标签，然" +#~ "后点击左侧边栏的 `Secrets`_ 。" + +#~ msgid "" +#~ "Create a new secret called ``PYPI_API_TOKEN`` and copy-paste the token " +#~ "from the first step." +#~ msgstr "" +#~ "创建一个名为 ``PYPI_API_TOKEN`` 的新 secret ，并复制粘贴第一步中的令牌。" + +#~ msgid "" +#~ "Now, let's add initial setup for our job. 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:" +#~ msgstr "" +#~ "现在，让我们为我们的工作添加初始设置。这是一个将执行我们以后定义的命令的过" +#~ "程。在本指南中，我们将使用 GitHub Actions 提供的最新的稳定 Ubuntu LTS 版" +#~ "本:" + +#~ msgid "Then, add the following under the ``build-n-publish`` section:" +#~ msgstr "然后，在 ``build-n-publish`` 部分添加以下内容：" + +#~ msgid "So add this to the steps list:" +#~ msgstr "因此，将此加入到步骤列表中：" + +#~ msgid "" +#~ "`Docs `__ | `GitHub `__ | " +#~ "`PyPI `__" +#~ msgstr "" +#~ "`文档 `__ | `GitHub `__ | " +#~ "`PyPI `__" + +#~ msgid "" +#~ "It may also be known that project A follows semantic versioning, and that " +#~ "v2 of 'A' will indicate a break in compatibility, so it makes sense to " +#~ "not allow v2:" +#~ msgstr "" +#~ "也可能知道项目 A 遵循语义上的版本管理，而 'A' 的 v2 版将表明兼容性的中断，" +#~ "所以不允许v2版是有意义的：" + +#~ msgid ":term:`Wheel` has an :pep:`official PEP <427>`. :term:`Egg` did not." +#~ msgstr "" +#~ ":term:`Wheel` 有一个 :pep:`official PEP <427>` 。 :term:`Egg` 没有。" + +#~ msgid "" +#~ "Circumstantially, in some cases, wheels can be used as an importable " +#~ "runtime format, although :pep:`this is not officially supported at this " +#~ "time <427#is-it-possible-to-import-python-code-directly-from-a-wheel-" +#~ "file>`." +#~ msgstr "" +#~ "在某些情况下，控制盘可以用作可导入的运行时格式，尽管：pep:`目前还没有正式" +#~ "支持这一格式 <427#is-it-mable-to-import-python-code-directly-from-a-wheel-" +#~ "file>`。" + +#~ msgid "" +#~ "Note that the rows are stored in a partitioned, which helps limit the " +#~ "cost of queries. These example queries analyze downloads from recent " +#~ "history by filtering on the ``timestamp`` column." +#~ msgstr "" +#~ "请注意，行存储在分区中，这有助于限制查询的成本。这些示例查询通过过滤" +#~ "``timestamp``列来分析最近历史记录中的下载。" + +#~ msgid "" +#~ "To only count downloads from pip, filter on the " +#~ "``details.installer.name`` column." +#~ msgstr "" +#~ "要想只计算来自 pip 的下载量，可以在 ``details.installer.name`` 列上过滤。" + +#~ msgid "For CentOS, see here: https://www.softwarecollections.org/en/" +#~ msgstr "对于 CentOS，请参阅此处： https://www.softwarecollections.org/en/" + +#~ msgid "Debian/Ubuntu" +#~ msgstr "Debian/Ubuntu" + +#~ msgid "" +#~ "This will download your repository into the CI runner and then install " +#~ "and activate Python 3.10." +#~ msgstr "这将把你的仓库下载到 CI runner 中，然后安装并激活 Python 3.10。" + +#~ msgid "" +#~ "A :term:`Built Distribution` format introduced by :ref:`setuptools`, " +#~ "which is being replaced by :term:`Wheel`. For details, see ` :doc:`The " +#~ "Internal Structure of Python Eggs ` " +#~ "and `Python Eggs `_" +#~ msgstr "" +#~ ":term:`Built Distribution`格式由 :ref:`setuptools`引入，并正" +#~ "被 :term:`Wheel`取代。 详见`:doc:`Python Eggs 的内部结构" +#~ "` 和 `Python Eggs `_" + +#~ msgid "" +#~ "To build the guide, run the following bash command in the source folder:" +#~ msgstr "要构建指南，在 source 文件夹中运行以下 bash 命令：" + +#~ msgid "" +#~ "`GitHub and Docs `__ | `PyPI " +#~ "`__" +#~ msgstr "" +#~ "`GitHub 和文档 `__ | `PyPI " +#~ "`__" + +#~ 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 the up to " +#~ "1TB of queries per month `using the BigQuery free tier without a credit " +#~ "card `__" +#~ msgstr "" +#~ "为了使用 `Google BigQuery`_ 来查询 `公共PyPI下载统计数据集 `_ ，你需要一个 Google 账户，并在 Google " +#~ "Cloud Platform 上启用 BigQuery API 。你可以每月运行高达 1TB 的查询 `使用 " +#~ "BigQuery 免费套餐，无需信用卡`__" + +#~ msgid "" +#~ ":doc:`Docs ` | `Issues `__ | `Bitbucket `__ | `PyPI `__" +#~ msgstr "" +#~ ":doc:`文档 ` | `Issues `__ | `Bitbucket `__ | `PyPI `__" + +#~ msgid "" +#~ "Consider alternatives to :ref:`setuptools` such " +#~ "as :ref:`flit`, :ref:`hatch`, and :ref:`poetry`." +#~ msgstr "" +#~ "考虑 :ref:`setuptools` 的替代方案，如 :ref:`flit`, :ref:`hatch`, " +#~ "和 :ref:`poetry`。" + +#~ msgid "`pip-tools `_" +#~ msgstr "`pip-tools `_" + +#, fuzzy +#~ msgid "" +#~ "https://self-issued.info/docs/draft-ietf-jose-json-web-signature.html" +#~ msgstr "" +#~ "http://self-issued.info/docs/draft-ietf-jose-json-web-signature.html" + +#, fuzzy +#~ msgid "https://self-issued.info/docs/draft-ietf-jose-json-web-key.html" +#~ msgstr "http://self-issued.info/docs/draft-ietf-jose-json-web-key.html" + +#~ msgid "" +#~ "`Docs `__ | `Issues `__ | `PyPI `__" +#~ msgstr "" +#~ "`文档`__ | `Issues `__ | `PyPI `__" + +#~ msgid "2014-11-11" +#~ msgstr "2014-11-11" + +#~ msgid "" +#~ "For an example, see the `MANIFEST.in `_ from the `PyPA sample project " +#~ "`_." +#~ msgstr "" +#~ "例如，请参阅 `PyPA 样本项目`_ 中的 " +#~ "`MANIFEST.in `_ 。" + +#~ msgid "description" +#~ msgstr "description" + +#~ msgid "license" +#~ msgstr "license" + +#~ msgid "keywords" +#~ msgstr "keywords" + +#~ msgid "Assuming you're in the root of your project directory, then run:" +#~ msgstr "假设您现在在您的项目目录的根部，然后运行：" + +#~ msgid "2015-09-17" +#~ msgstr "2015-09-17" + +#~ msgid "Fedora 21:" +#~ msgstr "Fedora 21:" + +#~ msgid "Python 3: ``sudo yum install python3 python3-wheel``" +#~ msgstr "Python 3: ``sudo yum install python3 python3-wheel``" + +#~ msgid "Fedora 22:" +#~ msgstr "Fedora 22:" + +#~ msgid "Python 3: ``sudo dnf install python3 python3-wheel``" +#~ msgstr "Python 3: ``sudo dnf install python3 python3-wheel``" + +#~ msgid "For Python 2.7" +#~ msgstr "适用于 Python 2.7" + +#~ msgid "" +#~ "Install \"Visual C++ Compiler Package for Python 2.7\", which is " +#~ "available from `Microsoft's website `__." +#~ msgstr "" +#~ "安装 \"Visual C++ Compiler Package for Python 2.7\"，它可以从 `微软的网站 " +#~ "`__ 获得。" + +#~ msgid "" +#~ "Use (a recent version of) setuptools in your setup.py (pip will do this " +#~ "for you, in any case)." +#~ msgstr "" +#~ "在您的 setup.py 中使用（最新版本的）setuptools（无论如何，pip 会帮你做这" +#~ "个）。" + +#~ msgid "Done." +#~ msgstr "完成了。" + +#~ msgid "For Python 3.4" +#~ msgstr "适用于Python 3.4" + +#~ msgid "" +#~ "Install \"Windows SDK for Windows 7 and .NET Framework 4\" (v7.1), which " +#~ "is available from `Microsoft's website `__." +#~ msgstr "" +#~ "安装 \"Windows SDK for Windows 7 and .NET Framework 4\"（v7.1），可从`微软" +#~ "网站`__ 获" +#~ "得。" + +#~ msgid "Set DISTUTILS_USE_SDK=1" +#~ msgstr "Set DISTUTILS_USE_SDK=1" + +#~ msgid "For Python 3.5" +#~ msgstr "适用于 Python 3.5" + +#~ msgid "" +#~ "Install `Visual Studio 2015 Community Edition `__ " +#~ "(or any later version, when these are released)." +#~ msgstr "" +#~ "安装`Visual Studio 2015 社区版 `__ （或任何后来的版本，当这些版" +#~ "本发布时）。" + +#~ msgid "bento" +#~ msgstr "bento" + +#~ msgid "" +#~ "`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +#~ msgstr "" +#~ "`文档 `__ | `Issues `__ | `GitHub `__ | `PyPI `__" + +#~ msgid "`Docs `__" +#~ msgstr "`文档 `__" diff --git a/locales/zh_Hant/LC_MESSAGES/messages.po b/locales/zh_Hant/LC_MESSAGES/messages.po new file mode 100644 index 000000000..dbd224879 --- /dev/null +++ b/locales/zh_Hant/LC_MESSAGES/messages.po @@ -0,0 +1,27058 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2013–2020, PyPA +# This file is distributed under the same license as the Python Packaging User Guide package. +# meowmeowmeowcat , 2021, 2022. +# 吳侑恩 , 2021. +# tommyliu313 , 2022. +# Wei-Hsiang (Matt) Wang , 2022. +# Elvir Kadic , 2022. +# hugoalh , 2024. +# Ricky From Hong Kong , 2024. +# nonepork <59335048+nonepork@users.noreply.github.com>, 2025. +# toto6038 , 2025. +msgid "" +msgstr "" +"Project-Id-Version: Python Packaging User Guide\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2026-03-05 06:32+0000\n" +"PO-Revision-Date: 2025-02-24 15:37+0000\n" +"Last-Translator: toto6038 \n" +"Language-Team: Chinese (Traditional Han script) \n" +"Language: zh_Hant\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=1; plural=0;\n" +"X-Generator: Weblate 5.10.1-dev\n" + +#: ../source/contribute.rst:5 +msgid "Contribute to this guide" +msgstr "為本指南做出貢獻" + +#: ../source/contribute.rst:7 +msgid "" +"The |PyPUG| welcomes contributors! There are lots of ways to help out, " +"including:" +msgstr "|PyPUG| 歡迎貢獻者！有很多方法可以提供幫助，包括：" + +#: ../source/contribute.rst:10 +msgid "Reading the guide and giving feedback" +msgstr "閱讀本指南並提供反饋" + +#: ../source/contribute.rst:11 +msgid "Reviewing new contributions" +msgstr "審查新的貢獻" + +#: ../source/contribute.rst:12 +msgid "Revising existing content" +msgstr "修改現有內容" + +#: ../source/contribute.rst:13 +msgid "Writing new content" +msgstr "編寫新內容" + +#: ../source/contribute.rst:14 +#, fuzzy +#| msgid "Translate the guide" +msgid "Translating the guide" +msgstr "翻譯本指南" + +#: ../source/contribute.rst:16 +msgid "" +"Most of the work on the |PyPUG| takes place on the `project's GitHub " +"repository`__. To get started, check out the list of `open issues`__ and " +"`pull requests`__. If you're planning to write or edit the guide, please " +"read the :ref:`style guide `." +msgstr "" +"大部分關於 |PyPUG| 的工作都是在 `項目的 GitHub 倉庫 ` 進行的。要開始工作，請查看 `open issues`__ 和 `pull requests`__ " +"的列表。如果你打算編寫或編輯指南，請閱讀 :ref:`風格指南 " +"`。" + +#: ../source/contribute.rst:25 +msgid "" +"By contributing to the |PyPUG|, you're expected to follow the PSF's `Code of " +"Conduct`__." +msgstr "" +"如果你打算為 |PyPUG| 作出貢獻，你就應該遵守 PSF 的 `行為守則 `__。" + +#: ../source/contribute.rst:32 +msgid "Documentation types" +msgstr "文件類型" + +#: ../source/contribute.rst:34 +#, fuzzy +#| msgid "" +#| "This project consists of four distinct documentation types with specific " +#| "purposes. When proposing new additions to the project please pick the " +#| "appropriate documentation type." +msgid "" +"This project consists of four distinct documentation types with specific " +"purposes. The project aspires to follow the `Diátaxis process`_ for creating " +"quality documentation. When proposing new additions to the project please " +"pick the appropriate documentation type." +msgstr "" +"這指南蘊含四個不同均有特別用途的文件類別。請確保在提出加入新內容之前選取相關" +"文件類別。" + +#: ../source/contribute.rst:42 ../source/index.rst:55 +#: ../source/tutorials/index.rst:2 +msgid "Tutorials" +msgstr "教學" + +#: ../source/contribute.rst:44 +#, fuzzy +msgid "" +"Tutorials are focused on teaching the reader new concepts by accomplishing a " +"goal. They are opinionated step-by-step guides. They do not include " +"extraneous warnings or information. `example tutorial-style document`_." +msgstr "" +"`導師教學只注重於教導閱讀者透過完成目標去學習新的概念。他們只執著於一對一的教" +"學。他們沒有含蘊無關的資訊警告。 `_." + +#: ../source/contribute.rst:51 ../source/guides/index.rst:2 +#: ../source/index.rst:69 +msgid "Guides" +msgstr "指南" + +#: ../source/contribute.rst:53 +msgid "" +"Guides are focused on accomplishing a specific task and can assume some " +"level of pre-requisite knowledge. These are similar to tutorials, but have a " +"narrow and clear focus and can provide lots of caveats and additional " +"information as needed. They may also discuss multiple approaches to " +"accomplishing the task. :doc:`example guide-style document `." +msgstr "" + +#: ../source/contribute.rst:60 ../source/discussions/index.rst:2 +msgid "Discussions" +msgstr "討論" + +#: ../source/contribute.rst:62 +msgid "" +"Discussions are focused on understanding and information. These explore a " +"specific topic without a specific goal in mind. :doc:`example discussion-" +"style document `." +msgstr "" + +#: ../source/contribute.rst:67 +msgid "Specifications" +msgstr "規格" + +#: ../source/contribute.rst:69 +msgid "" +"Specifications are reference documentation focused on comprehensively " +"documenting an agreed-upon interface for interoperability between packaging " +"tools. :doc:`example specification-style document `." +msgstr "" + +#: ../source/contribute.rst:75 +msgid "Translations" +msgstr "翻譯" + +#: ../source/contribute.rst:77 +msgid "" +"We use `Weblate`_ to manage translations of this project. Please visit the " +"`packaging.python.org`_ project on Weblate to contribute." +msgstr "" +"我們使用了 `Weblate`_ 平台來管理專案的翻譯。請在 Weblate 瀏覽 " +"`packaging.python.org`_ 來貢獻翻譯。" + +#: ../source/contribute.rst:80 +msgid "" +"If you are experiencing issues while you are working on translations, please " +"open an issue on `GitHub`_." +msgstr "如果你在翻譯上遇到了問題，請在`Github`_ 上建立一項 Issue。" + +#: ../source/contribute.rst:85 +msgid "" +"Any translations of this project should follow `reStructuredText syntax`_." +msgstr "所有關於此專案的翻譯應該遵守 `reStructuredText syntax`_ 。" + +#: ../source/contribute.rst:93 +msgid "Adding a language" +msgstr "新增一個語言" + +#: ../source/contribute.rst:95 +msgid "" +"If your language is not listed on `packaging.python.org`_, click the " +"button :guilabel:`Start new translation` at the bottom of the language list " +"and add the language you want to translate." +msgstr "" + +#: ../source/contribute.rst:100 +msgid "Following reStructuredText syntax" +msgstr "" + +#: ../source/contribute.rst:102 +msgid "" +"If you are not familiar with reStructuredText (RST) syntax, please read " +"`this guide`_ before translating on Weblate." +msgstr "" + +#: ../source/contribute.rst:118 +msgid "**Do not translate the text in reference directly**" +msgstr "**請勿直接在參照裡翻譯文字**" + +#: ../source/contribute.rst:106 +msgid "" +"When translating the text in reference, please do not translate them " +"directly." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Translate the following text directly:" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "" +"Right: Translate the following text with your own language and add the " +"original reference:" +msgstr "" + +#: ../source/contribute.rst:123 +msgid "Building the guide locally" +msgstr "在本地構建指南" + +#: ../source/contribute.rst:125 +msgid "" +"Though not required to contribute, it may be useful to build this guide " +"locally in order to test your changes. In order to build this guide locally, " +"you'll need:" +msgstr "" + +#: ../source/contribute.rst:129 +msgid ":doc:`Nox `. You can install or upgrade nox using ``pip``:" +msgstr ":doc:`Nox `。您可以使用 ``pip`` 來安裝或升級 nox：" + +#: ../source/contribute.rst:136 +#, fuzzy +msgid "" +"Python 3.11. Our build scripts are usually tested with Python 3.11 only. See " +"the :doc:`Hitchhiker's Guide to Python installation instructions ` to install Python 3.11 on your operating " +"system." +msgstr "" +"Python 3.6。我們的構建腳本只為 Python 3.6 而設計。請參閱 `Hitchhiker's Guide " +"to Python installation instructions`_ 以在您的操作系統上安裝Python 3.6。" + +#: ../source/contribute.rst:140 +#, fuzzy +msgid "" +"To build the guide, run the following shell command in the project's root " +"folder:" +msgstr "要構建指南，請在 source 資料夾中運行以下 bash 命令：" + +#: ../source/contribute.rst:146 +msgid "" +"After the process has completed you can find the HTML output in the ``./" +"build/html`` directory. You can open the ``index.html`` file to view the " +"guide in web browser, but it's recommended to serve the guide using an HTTP " +"server." +msgstr "" + +#: ../source/contribute.rst:151 +msgid "" +"You can build the guide and serve it via an HTTP server using the following " +"command:" +msgstr "" + +#: ../source/contribute.rst:158 +msgid "The guide will be browsable via http://localhost:8000." +msgstr "該指南將可通過 http://localhost:8000 進行瀏覽。" + +#: ../source/contribute.rst:162 +msgid "Where the guide is deployed" +msgstr "" + +#: ../source/contribute.rst:164 +msgid "" +"The guide is deployed via ReadTheDocs and the configuration lives at https://" +"readthedocs.org/projects/python-packaging-user-guide/. It's served from a " +"custom domain and fronted by Fast.ly." +msgstr "" + +#: ../source/contribute.rst:170 +msgid "Style guide" +msgstr "風格指南" + +#: ../source/contribute.rst:172 +msgid "" +"This style guide has recommendations for how you should write the |PyPUG|. " +"Before you start writing, please review it. By following the style guide, " +"your contributions will help add to a cohesive whole and make it easier for " +"your contributions to be accepted into the project." +msgstr "" + +#: ../source/contribute.rst:179 +msgid "Purpose" +msgstr "目的" + +#: ../source/contribute.rst:181 +msgid "" +"The purpose of the |PyPUG| is to be the authoritative resource on how to " +"package, publish, and install Python projects using current tools." +msgstr "" + +#: ../source/contribute.rst:186 +msgid "Scope" +msgstr "範圍" + +#: ../source/contribute.rst:188 +msgid "" +"The guide is meant to answer questions and solve problems with accurate and " +"focused recommendations." +msgstr "該指南旨在通過準確和有針對性的建議回答問題和解決問題。" + +#: ../source/contribute.rst:191 +msgid "" +"The guide isn't meant to be comprehensive and it's not meant to replace " +"individual projects' documentation. For example, pip has dozens of commands, " +"options, and settings. The pip documentation describes each of them in " +"detail, while this guide describes only the parts of pip that are needed to " +"complete the specific tasks described in this guide." +msgstr "" + +#: ../source/contribute.rst:199 +msgid "Audience" +msgstr "觀眾" + +#: ../source/contribute.rst:201 +msgid "The audience of this guide is anyone who uses Python with packages." +msgstr "本指南的受眾是任何使用 Python 包的人。" + +#: ../source/contribute.rst:203 +msgid "" +"Don't forget that the Python community is big and welcoming. Readers may not " +"share your age, gender, education, culture, and more, but they deserve to " +"learn about packaging just as much as you do." +msgstr "" + +#: ../source/contribute.rst:207 +msgid "" +"In particular, keep in mind that not all people who use Python see " +"themselves as programmers. The audience of this guide includes astronomers " +"or painters or students as well as professional software developers." +msgstr "" + +#: ../source/contribute.rst:213 +msgid "Voice and tone" +msgstr "" + +#: ../source/contribute.rst:215 +msgid "" +"When writing this guide, strive to write with a voice that's approachable " +"and humble, even if you have all the answers." +msgstr "" + +#: ../source/contribute.rst:218 +msgid "" +"Imagine you're working on a Python project with someone you know to be smart " +"and skilled. You like working with them and they like working with you. That " +"person has asked you a question and you know the answer. How do you respond? " +"*That* is how you should write this guide." +msgstr "" + +#: ../source/contribute.rst:223 +msgid "" +"Here's a quick check: try reading aloud to get a sense for your writing's " +"voice and tone. Does it sound like something you would say or does it sound " +"like you're acting out a part or giving a speech? Feel free to use " +"contractions and don't worry about sticking to fussy grammar rules. You are " +"hereby granted permission to end a sentence in a preposition, if that's what " +"you want to end it with." +msgstr "" + +#: ../source/contribute.rst:230 +msgid "" +"When writing the guide, adjust your tone for the seriousness and difficulty " +"of the topic. If you're writing an introductory tutorial, it's OK to make a " +"joke, but if you're covering a sensitive security recommendation, you might " +"want to avoid jokes altogether." +msgstr "" + +#: ../source/contribute.rst:237 +msgid "Conventions and mechanics" +msgstr "" + +#: ../source/contribute.rst:245 +msgid "**Write to the reader**" +msgstr "" + +#: ../source/contribute.rst:240 +msgid "" +"When giving recommendations or steps to take, address the reader as *you* or " +"use the imperative mood." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: To install it, the user runs…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: You can install it by running…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: To install it, run…" +msgstr "" + +#: ../source/contribute.rst:251 +msgid "**State assumptions**" +msgstr "" + +#: ../source/contribute.rst:248 +msgid "" +"Avoid making unstated assumptions. Reading on the web means that any page of " +"the guide may be the first page of the guide that the reader ever sees. If " +"you're going to make assumptions, then say what assumptions that you're " +"going to make." +msgstr "" + +#: ../source/contribute.rst:256 +msgid "**Cross-reference generously**" +msgstr "" + +#: ../source/contribute.rst:254 +msgid "" +"The first time you mention a tool or practice, link to the part of the guide " +"that covers it, or link to a relevant document elsewhere. Save the reader a " +"search." +msgstr "" + +#: ../source/contribute.rst:266 +msgid "**Respect naming practices**" +msgstr "" + +#: ../source/contribute.rst:259 +msgid "" +"When naming tools, sites, people, and other proper nouns, use their " +"preferred capitalization." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: pip uses…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: …hosted on github." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: …hosted on GitHub." +msgstr "" + +#: ../source/contribute.rst:275 +msgid "**Use a gender-neutral style**" +msgstr "" + +#: ../source/contribute.rst:269 +msgid "" +"Often, you'll address the reader directly with *you*, *your* and *yours*. " +"Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or " +"avoid pronouns entirely." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: A maintainer uploads the file. Then he…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then they…" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: A maintainer uploads the file. Then the maintainer…" +msgstr "" + +#: ../source/contribute.rst:287 +msgid "**Headings**" +msgstr "**標題**" + +#: ../source/contribute.rst:278 +msgid "" +"Write headings that use words the reader is searching for. A good way to do " +"this is to have your heading complete an implied question. For example, a " +"reader might want to know *How do I install MyLibrary?* so a good heading " +"might be *Install MyLibrary*." +msgstr "" + +#: ../source/contribute.rst:283 +msgid "" +"In section headings, use sentence case. In other words, write headings as " +"you would write a typical sentence." +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Wrong: Things You Should Know About Python" +msgstr "" + +#: ../source/contribute.rst:0 +msgid "Right: Things you should know about Python" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "**Numbers**" +msgstr "" + +#: ../source/contribute.rst:290 +msgid "" +"In body text, write numbers one through nine as words. For other numbers or " +"numbers in tables, use numerals." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:4 +msgid "Deploying Python applications" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/migrating-to-pypi-org.rst:0 +#: ../source/guides/multi-version-installs.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Page Status" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:6 +#: ../source/guides/index-mirrors-and-caches.rst:7 +#: ../source/guides/installing-using-linux-tools.rst:7 +#: ../source/guides/packaging-binary-extensions.rst:7 +msgid "Incomplete" +msgstr "不完整" + +#: ../source/discussions/deploying-python-applications.rst:0 +#: ../source/discussions/downstream-packaging.rst:0 +#: ../source/discussions/single-source-version.rst:0 +#: ../source/guides/distributing-packages-using-setuptools.rst:0 +#: ../source/guides/index-mirrors-and-caches.rst:0 +#: ../source/guides/installing-using-linux-tools.rst:0 +#: ../source/guides/packaging-binary-extensions.rst:0 +#: ../source/guides/supporting-multiple-python-versions.rst:0 +#: ../source/guides/supporting-windows-using-appveyor.rst:0 +msgid "Last Reviewed" +msgstr "上次審核" + +#: ../source/discussions/deploying-python-applications.rst:7 +msgid "2021-8-24" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:11 +#: ../source/specifications/externally-managed-environments.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:14 +msgid "Overview" +msgstr "概述" + +#: ../source/discussions/deploying-python-applications.rst:15 +msgid "Supporting multiple hardware platforms" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:37 +msgid "OS packaging & installers" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:49 +#: ../source/discussions/deploying-python-applications.rst:86 +msgid "Windows" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:58 +msgid "Pynsist" +msgstr "Pynsist" + +#: ../source/discussions/deploying-python-applications.rst:60 +msgid "" +"`Pynsist `__ is a tool that bundles Python " +"programs together with the Python-interpreter into a single installer based " +"on NSIS. In most cases, packaging only requires the user to choose a version " +"of the Python-interpreter and declare the dependencies of the program. The " +"tool downloads the specified Python-interpreter for Windows and packages it " +"with all the dependencies in a single Windows-executable installer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:67 +msgid "" +"The installed program can be started from a shortcut that the installer adds " +"to the start-menu. It uses a Python interpreter installed within its " +"application directory, independent of any other Python installation on the " +"computer." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:71 +msgid "" +"A big advantage of Pynsist is that the Windows packages can be built on " +"Linux. There are several examples for different kinds of programs (console, " +"GUI) in the :any:`documentation `. The tool is released under " +"the MIT-licence." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:77 +msgid "Application bundles" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:89 +msgid "py2exe" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:91 +msgid "" +"`py2exe `__ is a distutils extension which " +"allows to build standalone Windows executable programs (32-bit and 64-bit) " +"from Python scripts. Python versions included in the official development " +"cycle are supported (refers to `Status of Python branches`__). py2exe can " +"build console executables and windows (GUI) executables. Building windows " +"services, and DLL/EXE COM servers might work but it is not actively " +"supported. The distutils extension is released under the MIT-licence and " +"Mozilla Public License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:103 +#: ../source/specifications/platform-compatibility-tags.rst:200 +msgid "macOS" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:106 +msgid "py2app" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:108 +msgid "" +"`py2app `__ is a Python setuptools command " +"which will allow you to make standalone macOS application bundles and " +"plugins from Python scripts. Note that py2app MUST be used on macOS to build " +"applications, it cannot create Mac applications on other platforms. py2app " +"is released under the MIT-license." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:115 +msgid "Unix (including Linux and macOS)" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:118 +#: ../source/key_projects.rst:576 +msgid "pex" +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:120 +msgid "" +"`pex `__ is a library for generating .pex " +"(Python EXecutable) files which are executable Python environments in the " +"spirit of virtualenvs. pex is an expansion upon the ideas outlined " +"in :pep:`441` and makes the deployment of Python applications as simple as " +"cp. pex files may even include multiple platform-specific Python " +"distributions, meaning that a single pex file can be portable across Linux " +"and macOS. pex is released under the Apache License 2.0." +msgstr "" + +#: ../source/discussions/deploying-python-applications.rst:129 +msgid "Configuration management" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:5 +msgid "Distribution package vs. import package" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:7 +msgid "" +"A number of different concepts are commonly referred to by the word " +"\"package\". This page clarifies the differences between two distinct but " +"related meanings in Python packaging, \"distribution package\" and \"import " +"package\"." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:13 +msgid "What's a distribution package?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:15 +msgid "" +"A distribution package is a piece of software that you can install. Most of " +"the time, this is synonymous with \"project\". When you type ``pip install " +"pkg``, or when you write ``dependencies = [\"pkg\"]`` in your " +"``pyproject.toml``, ``pkg`` is the name of a distribution package. When you " +"search or browse the PyPI_, the most widely known centralized source for " +"installing Python libraries and tools, what you see is a list of " +"distribution packages. Alternatively, the term \"distribution package\" can " +"be used to refer to a specific file that contains a certain version of a " +"project." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:24 +msgid "" +"Note that in the Linux world, a \"distribution package\", most commonly " +"abbreviated as \"distro package\" or just \"package\", is something provided " +"by the system package manager of the `Linux distribution `_, which " +"is a different meaning." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:31 +msgid "What's an import package?" +msgstr "甚麼是匯入套件？" + +#: ../source/discussions/distribution-package-vs-import-package.rst:33 +msgid "" +"An import package is a Python module. Thus, when you write ``import pkg`` or " +"``from pkg import func`` in your Python code, ``pkg`` is the name of an " +"import package. More precisely, import packages are special Python modules " +"that can contain submodules. For example, the ``numpy`` package contains " +"modules like ``numpy.linalg`` and ``numpy.fft``. Usually, an import package " +"is a directory on the file system, containing modules as ``.py`` files and " +"subpackages as subdirectories." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:42 +msgid "" +"You can use an import package as soon as you have installed a distribution " +"package that provides it." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:47 +msgid "What are the links between distribution packages and import packages?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:49 +msgid "" +"Most of the time, a distribution package provides one single import package " +"(or non-package module), with a matching name. For example, ``pip install " +"numpy`` lets you ``import numpy``." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:53 +msgid "" +"However, this is only a convention. PyPI and other package indices *do not " +"enforce any relationship* between the name of a distribution package and the " +"import packages it provides. (A consequence of this is that you cannot " +"blindly install the PyPI package ``foo`` if you see ``import foo``; this may " +"install an unintended, and potentially even malicious package.)" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:59 +msgid "" +"A distribution package could provide an import package with a different " +"name. An example of this is the popular Pillow_ library for image " +"processing. Its distribution package name is ``Pillow``, but it provides the " +"import package ``PIL``. This is for historical reasons: Pillow started as a " +"fork of the PIL library, thus it kept the import name ``PIL`` so that " +"existing PIL users could switch to Pillow with little effort. More " +"generally, a fork of an existing library is a common reason for differing " +"names between the distribution package and the import package." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:69 +msgid "" +"On a given package index (like PyPI), distribution package names must be " +"unique. On the other hand, import packages have no such requirement. Import " +"packages with the same name can be provided by several distribution " +"packages. Again, forks are a common reason for this." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:74 +msgid "" +"Conversely, a distribution package can provide several import packages, " +"although this is less common. An example is the attrs_ distribution package, " +"which provides both an ``attrs`` import package with a newer API, and an " +"``attr`` import package with an older but supported API." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:81 +msgid "How do distribution package names and import package names compare?" +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:83 +msgid "" +"Import packages should have valid Python identifiers as their name " +"(the :ref:`exact rules ` are found in the Python " +"documentation) [#non-identifier-mod-name]_. In particular, they use " +"underscores ``_`` as word separator and they are case-sensitive." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:88 +msgid "" +"On the other hand, distribution packages can use hyphens ``-`` or " +"underscores ``_``. They can also contain dots ``.``, which is sometimes used " +"for packaging a subpackage of a :ref:`namespace package `. For most purposes, they are insensitive to case and to ``-`` " +"vs. ``_`` differences, e.g., ``pip install Awesome_Package`` is the same as " +"``pip install awesome-package`` (the precise rules are given in " +"the :ref:`name normalization specification `)." +msgstr "" + +#: ../source/discussions/distribution-package-vs-import-package.rst:101 +msgid "" +"Although it is technically possible to import packages/modules that do not " +"have a valid Python identifier as their name, using :doc:`importlib " +"`, this is vanishingly rare and strongly " +"discouraged." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:5 +msgid "Supporting downstream packaging" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:7 +msgid "Draft" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:8 +msgid "2025-?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:10 +msgid "" +"While PyPI and the Python packaging tools such as :ref:`pip` are the primary " +"means of distributing Python packages, they are also often made available as " +"part of other packaging ecosystems. These repackaging efforts are " +"collectively called *downstream* packaging (your own efforts are called " +"*upstream* packaging), and include such projects as Linux distributions, " +"Conda, Homebrew and MacPorts. They generally aim to provide improved support " +"for use cases that cannot be handled via Python packaging tools alone, such " +"as native integration with a specific operating system, or assured " +"compatibility with specific versions of non-Python software." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:19 +msgid "" +"This discussion attempts to explain how downstream packaging is usually " +"done, and what additional challenges downstream packagers typically face. It " +"aims to provide some optional guidelines that project maintainers may choose " +"to follow which help make downstream packaging *significantly* easier " +"(without imposing any major maintenance hassles on the upstream project). " +"Note that this is not an all-or-nothing proposal — anything that upstream " +"maintainers can do is useful, even if it's only a small part. Downstream " +"maintainers are also willing to prepare patches to resolve these issues. " +"Having these patches merged can be very helpful, since it removes the need " +"for different downstreams to carry and keep rebasing the same patches, and " +"the risk of applying inconsistent solutions to the same problem." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:31 +msgid "" +"Establishing a good relationship between software maintainers and downstream " +"packagers can bring mutual benefits. Downstreams are often willing to share " +"their experience, time and hardware to improve your package. They are " +"sometimes in a better position to see how your package is used in practice, " +"and to provide information about its relationships with other packages that " +"would otherwise require significant effort to obtain. Packagers can often " +"find bugs before your users hit them in production, provide bug reports of " +"good quality, and supply patches whenever they can. For example, they are " +"regularly active in ensuring the packages they redistribute are updated for " +"any compatibility issues that arise when a new Python version is released." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:43 +msgid "" +"Please note that downstream builds include not only binary redistribution, " +"but also source builds done on user systems (in source-first distributions " +"such as Gentoo Linux, for example)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:51 +msgid "Provide complete source distributions" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:54 +#: ../source/discussions/downstream-packaging.rst:150 +#: ../source/discussions/downstream-packaging.rst:213 +#: ../source/discussions/downstream-packaging.rst:303 +#: ../source/discussions/downstream-packaging.rst:412 +msgid "Why?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:56 +msgid "" +"The vast majority of downstream packagers prefer to build packages from " +"source, rather than use the upstream-provided binary packages. In some " +"cases, using sources is actually required for the package to be included in " +"the distribution. This is also true of pure Python packages that provide " +"universal wheels. The reasons for using source distributions may include:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:62 +msgid "Being able to audit the source code of all packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:64 +msgid "Being able to run the test suite and build documentation." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:66 +msgid "" +"Being able to easily apply patches, including backporting commits from the " +"project's repository and sending patches back to the project." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:69 +msgid "" +"Being able to build on a specific platform that is not covered by upstream " +"builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:72 +msgid "Being able to build against specific versions of system libraries." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:74 +msgid "Having a consistent build process across all Python packages." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:76 +msgid "" +"While it is usually possible to build packages from a Git repository, there " +"are a few important reasons to provide a static archive file instead:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:79 +msgid "" +"Fetching a single file is often more efficient, more reliable and better " +"supported than e.g. using a Git clone. This can help users with poor " +"Internet connectivity." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:83 +msgid "" +"Downstreams often use hashes to verify the authenticity of source files on " +"subsequent builds, which require that they remain bitwise identical over " +"time. For example, automatically generated Git archives do not guarantee " +"this, as the compressed data may change if gzip is upgraded on the server." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:88 +msgid "" +"Archive files can be mirrored, reducing both upstream and downstream " +"bandwidth use. The actual builds can afterwards be performed in firewalled " +"or offline environments, that can only access source files provided by the " +"local mirror or redistributed earlier." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:93 +msgid "" +"Explicitly publishing archive files can ensure that any dependencies on " +"version control system metadata are resolved when creating the source " +"archive. For example, automatically generated Git archives omit all of the " +"commit tag information, potentially resulting in incorrect version details " +"in the resulting builds." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:99 +#: ../source/discussions/downstream-packaging.rst:179 +#: ../source/discussions/downstream-packaging.rst:277 +#: ../source/discussions/downstream-packaging.rst:337 +#: ../source/discussions/downstream-packaging.rst:441 +msgid "How?" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:101 +msgid "" +"Ideally, **a source distribution archive published on PyPI should include " +"all the files from the package's Git repository** that are necessary to " +"build the package itself, run its test suite, build and install its " +"documentation, and any other files that may be useful to end users, such as " +"shell completions, editor support files, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:107 +msgid "" +"This point applies only to the files belonging to the package itself. The " +"downstream packaging process, much like Python package managers, will " +"provision the necessary Python dependencies, system tools and external " +"libraries that are needed by your package and its build scripts. However, " +"the files listing these dependencies (for example, ``requirements*.txt`` " +"files) should also be included, to help downstreams determine the needed " +"dependencies, and check for changes in them." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:115 +msgid "" +"Some projects have concerns related to Python package managers using source " +"distributions from PyPI. They do not wish to increase their size with files " +"that are not used by these tools, or they do not wish to publish source " +"distributions at all, as they enable a problematic or outright nonfunctional " +"fallback to building the particular project from source. In these cases, a " +"good compromise may be to publish a separate source archive for downstream " +"use elsewhere, for example by attaching it to a GitHub release. " +"Alternatively, large files, such as test data, can be split into separate " +"archives." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:124 +msgid "" +"On the other hand, some projects (NumPy_, for instance) decide to include " +"tests in their installed packages. This has the added advantage of " +"permitting users to run tests after installing them, for example to check " +"for regressions after upgrading a dependency. Yet another approach is to " +"split tests or test data into a separate Python package. Such an approach " +"was taken by the cryptography_ project, with the large test vectors being " +"split to cryptography-vectors_ package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:132 +msgid "" +"A good idea is to use your source distribution in the release workflow. For " +"example, the :ref:`build` tool does exactly that — it first builds a source " +"distribution, and then uses it to build a wheel. This ensures that the " +"source distribution actually works, and that it won't accidentally install " +"fewer files than the official wheels." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:138 +msgid "" +"Ideally, also use the source distribution to run tests, build documentation, " +"and so on, or add specific tests to make sure that all necessary files were " +"actually included. Understandably, this requires more effort, so it's fine " +"not do that — downstream packagers will report any missing files promptly." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:147 +msgid "Do not use the Internet during the build process" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:152 +msgid "" +"Downstream builds are frequently done in sandboxed environments that cannot " +"access the Internet. The package sources are unpacked into this environment, " +"and all the necessary dependencies are installed." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:156 +msgid "" +"Even if this is not the case, and assuming that you took sufficient care to " +"properly authenticate downloads, using the Internet is discouraged for a " +"number of reasons:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:160 +msgid "" +"The Internet connection may be unstable (e.g. due to poor reception) or " +"suffer from temporary problems that could cause the process to fail or hang." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:164 +msgid "" +"The remote resources may become temporarily or even permanently unavailable, " +"making the build no longer possible. This is especially problematic when " +"someone needs to build an old package version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:168 +msgid "The remote resources may change, making the build not reproducible." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:170 +msgid "" +"Accessing remote servers poses a privacy issue and a potential security " +"issue, as it exposes information about the system building the package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:174 +msgid "" +"The user may be using a service with a limited data plan, in which " +"uncontrolled Internet access may result in additional charges or other " +"inconveniences." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:181 +msgid "" +"If the package is implementing any custom build *backend* actions that use " +"the Internet, for example by automatically downloading vendored dependencies " +"or fetching Git submodules, its source distribution should either include " +"all of these files or allow provisioning them externally, and the Internet " +"must not be used if the files are already present." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:187 +msgid "" +"Note that this point does not apply to Python dependencies that are " +"specified in the package metadata, and are fetched during the build and " +"installation process by *frontends* (such as :ref:`build` or :ref:`pip`). " +"Downstreams use frontends that use local provisioning for Python " +"dependencies." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:192 +msgid "" +"Ideally, custom build scripts should not even attempt to access the Internet " +"at all, unless explicitly requested to. If any resources are missing and " +"need to be fetched, they should ask the user for permission first. If that " +"is not feasible, the next best thing is to provide an opt-out switch to " +"disable all Internet access. This could be done e.g. by checking whether a " +"``NO_NETWORK`` environment variable is set to a non-empty value." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:199 +msgid "" +"Since downstreams frequently also run tests and build documentation, the " +"above should ideally extend to these processes as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:202 +msgid "" +"Please also remember that if you are fetching remote resources, you " +"absolutely must *verify their authenticity* (usually against a hash), to " +"protect against the file being substituted by a malicious party." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:210 +msgid "Support building against system dependencies" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:215 +msgid "" +"Some Python projects have non-Python dependencies, such as libraries written " +"in C or C++. Trying to use the system versions of these dependencies in " +"upstream packaging may cause a number of problems for end users:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:219 +msgid "" +"The published wheels require a binary-compatible version of the used library " +"to be present on the user's system. If the library is missing or an " +"incompatible version is installed, the Python package may fail with errors " +"that are not clear to inexperienced users, or even misbehave at runtime." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:224 +msgid "" +"Building from a source distribution requires a source-compatible version of " +"the dependency to be present, along with its development headers and other " +"auxiliary files that some systems package separately from the library itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:229 +msgid "" +"Even for an experienced user, installing a compatible dependency version may " +"be very hard. For example, the used Linux distribution may not provide the " +"required version, or some other package may require an incompatible version." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:234 +msgid "" +"The linkage between the Python package and its system dependency is not " +"recorded by the packaging system. The next system update may upgrade the " +"library to a newer version that breaks binary compatibility with the Python " +"package, and requires user intervention to fix." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:239 +msgid "" +"For these reasons, you may reasonably decide to either statically link your " +"dependencies, or to provide local copies in the installed package. You may " +"also vendor the dependency in your source distribution. Sometimes these " +"dependencies are also repackaged on PyPI, and can be declared as project " +"dependencies like any other Python package." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:245 +msgid "" +"However, none of these issues apply to downstream packaging, and downstreams " +"have good reasons to prefer dynamically linking to system dependencies. In " +"particular:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:249 +msgid "" +"In many cases, reliably sharing dynamic dependencies between components is a " +"large part of the *purpose* of a downstream packaging ecosystem. Helping to " +"support that makes it easier for users of those systems to access upstream " +"projects in their preferred format." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:253 +msgid "" +"Static linking and vendoring obscures the use of external dependencies, " +"making source auditing harder." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:256 +msgid "" +"Dynamic linking makes it possible to quickly and systematically replace the " +"used libraries across an entire downstream packaging ecosystem, which can be " +"particularly important when they turn out to contain a security " +"vulnerability or critical bug." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:260 +msgid "" +"Using system dependencies makes the package benefit from downstream " +"customization that can improve the user experience on a particular platform, " +"without the downstream maintainers having to consistently patch the " +"dependencies vendored in different packages. This can include compatibility " +"improvements and security hardening." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:266 +msgid "" +"Static linking and vendoring can result in multiple different versions of " +"the same library being loaded in the same process (for example, attempting " +"to import two Python packages that link to different versions of the same " +"library). This sometimes works without incident, but it can also lead to " +"anything from library loading errors, to subtle runtime bugs, to " +"catastrophic failures (like suddenly crashing and losing data)." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:273 +msgid "" +"Last but not least, static linking and vendoring results in duplication, and " +"may increase the use of both disk space and memory." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:279 +msgid "" +"A good compromise between the needs of both parties is to provide a switch " +"between using vendored and system dependencies. Ideally, if the package has " +"multiple vendored dependencies, it should provide both individual switches " +"for each dependency, and a general switch to control the default for them, " +"e.g. via a ``USE_SYSTEM_DEPS`` environment variable." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:285 +msgid "" +"If the user requests using system dependencies, and a particular dependency " +"is either missing or incompatible, the build should fail with an explanatory " +"message rather than fall back to a vendored version. This gives the packager " +"the opportunity to notice their mistake and a chance to consciously decide " +"how to solve it." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:291 +msgid "" +"It is reasonable for upstream projects to leave *testing* of building with " +"system dependencies to their downstream repackagers. The goal of these " +"guidelines is to facilitate more effective collaboration between upstream " +"projects and downstream repackagers, not to suggest upstream projects take " +"on tasks that downstream repackagers are better equipped to handle." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:300 +msgid "Support downstream testing" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:305 +msgid "" +"A variety of downstream projects run some degree of testing on the packaged " +"Python projects. Depending on the particular case, this can range from " +"minimal smoke testing to comprehensive runs of the complete test suite. " +"There can be various reasons for doing this, for example:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:310 +msgid "Verifying that the downstream packaging did not introduce any bugs." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:312 +msgid "" +"Testing on additional platforms that are not covered by upstream testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:314 +msgid "" +"Finding subtle bugs that can only be reproduced with particular hardware, " +"system package versions, and so on." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:317 +msgid "" +"Testing the released package against newer (or older) dependency versions " +"than the ones present during upstream release testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:320 +msgid "" +"Testing the package in an environment closely resembling the production " +"setup. This can detect issues caused by non-trivial interactions between " +"different installed packages, including packages that are not dependencies " +"of your package, but nevertheless can cause issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:325 +msgid "" +"Testing the released package against newer Python versions (including newer " +"point releases), or less tested Python implementations such as PyPy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:328 +msgid "" +"Admittedly, sometimes downstream testing may yield false positives or bug " +"reports about scenarios the upstream project is not interested in " +"supporting. However, perhaps even more often it does provide early notice of " +"problems, or find non-trivial bugs that would otherwise cause issues for the " +"upstream project's users. While mistakes do happen, the majority of " +"downstream packagers are doing their best to double-check their results, and " +"help upstream maintainers triage and fix the bugs that they reported." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:339 +msgid "" +"There are a number of things that upstream projects can do to help " +"downstream repackagers test their packages efficiently and effectively, " +"including some of the suggestions already mentioned above. These are " +"typically improvements that make the test suite more reliable and easier to " +"use for everyone, not just downstream packagers. Some specific suggestions " +"are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:345 +msgid "" +"Include the test files and fixtures in the source distribution, or make it " +"possible to easily download them separately." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:348 +msgid "" +"Do not write to the package directories during testing. Downstream test " +"setups sometimes run tests on top of the installed package, and " +"modifications performed during testing and temporary test files may end up " +"being part of the installed package!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:353 +msgid "" +"Make the test suite work offline. Mock network interactions, using packages " +"such as responses_ or vcrpy_. If that is not possible, make it possible to " +"easily disable the tests using Internet access, e.g. via a pytest_ marker. " +"Use pytest-socket_ to verify that your tests work offline. This often makes " +"your own test workflows faster and more reliable as well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:359 +msgid "" +"Make your tests work without a specialized setup, or perform the necessary " +"setup as part of test fixtures. Do not ever assume that you can connect to " +"system services such as databases — in an extreme case, you could crash a " +"production service!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:364 +msgid "" +"If your package has optional dependencies, make their tests optional as " +"well. Either skip them if the needed packages are not installed, or add " +"markers to make deselecting easy." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:368 +msgid "" +"More generally, add markers to tests with special requirements. These can " +"include e.g. significant space usage, significant memory usage, long " +"runtime, incompatibility with parallel testing." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:372 +msgid "" +"Do not assume that the test suite will be run with ``-Werror``. Downstreams " +"often need to disable that, as it causes false positives, e.g. due to newer " +"dependency versions. Assert for warnings using ``pytest.warns()`` rather " +"than ``pytest.raises()``!" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:377 +msgid "" +"Aim to make your test suite reliable and reproducible. Avoid flaky tests. " +"Avoid depending on specific platform details, don't rely on exact results of " +"floating-point computation, or timing of operations, and so on. Fuzzing has " +"its advantages, but you want to have static test cases for completeness as " +"well." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:383 +msgid "" +"Split tests by their purpose, and make it easy to skip categories that are " +"irrelevant or problematic. Since the primary purpose of downstream testing " +"is to ensure that the package itself works, downstreams are not generally " +"interested in tasks such as checking code coverage, code formatting, " +"typechecking or running benchmarks. These tests can fail as dependencies are " +"upgraded or the system is under load, without actually affecting the package " +"itself." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:390 +msgid "" +"If your test suite takes significant time to run, support testing in " +"parallel. Downstreams often maintain a large number of packages, and testing " +"them all takes a lot of time. Using pytest-xdist_ can help them avoid " +"bottlenecks." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:395 +msgid "" +"Ideally, support running your test suite via ``pytest``. pytest_ has many " +"command-line arguments that are truly helpful to downstreams, such as the " +"ability to conveniently deselect tests, rerun flaky tests (via pytest-" +"rerunfailures_), add a timeout to prevent tests from hanging (via pytest-" +"timeout_) or run tests in parallel (via pytest-xdist_). Note that test " +"suites don't need to be *written* with ``pytest`` to be *executed* with " +"``pytest``: ``pytest`` is able to find and execute almost all test cases " +"that are compatible with the standard library's ``unittest`` test discovery." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:409 +msgid "Aim for stable releases" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:414 +msgid "" +"Many downstreams provide stable release channels in addition to the main " +"package streams. The goal of these channels is to provide more conservative " +"upgrades to users with higher stability needs. These users often prefer to " +"trade having the newest features available for lower risk of issues." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:419 +msgid "" +"While the exact policies differ, an important criterion for including a new " +"package version in a stable release channel is for it to be available in " +"testing for some time already, and have no known major regressions. For " +"example, in Gentoo Linux a package is usually marked stable after being " +"available in testing for a month, and being tested against the versions of " +"its dependencies that are marked stable at the time." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:426 +msgid "" +"However, there are circumstances which demand more prompt action. For " +"example, if a security vulnerability or a major bug is found in the version " +"that is currently available in the stable channel, the downstream is facing " +"a need to resolve it. In this case, they need to consider various options, " +"such as:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:431 +msgid "putting a new version in the stable channel early," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:433 +msgid "adding patches to the version currently published," +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:435 +msgid "or even downgrading the stable channel to an earlier release." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:437 +msgid "" +"Each of these options involves certain risks and a certain amount of work, " +"and packagers needs to weigh them to determine the course of action." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:443 +msgid "" +"There are some things that upstreams can do to tailor their workflow to " +"stable release channels. These actions often are beneficial to the package's " +"users as well. Some specific suggestions are:" +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:447 +msgid "" +"Adjust the release frequency to the rate of code changes. Packages that are " +"released rarely often bring significant changes with every release, and a " +"higher risk of accidental regressions." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:451 +msgid "" +"Avoid mixing bug fixes and new features, if possible. In particular, if " +"there are known bug fixes merged already, consider making a new release " +"before merging feature branches." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:455 +msgid "" +"Consider making prereleases after major changes, to provide more testing " +"opportunities for users and downstreams willing to opt-in." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:458 +msgid "" +"If your project is subject to very intense development, consider splitting " +"one or more branches that include a more conservative subset of commits, and " +"are released separately. For example, Django_ currently maintains three " +"release branches in addition to main." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:463 +msgid "" +"Even if you don't wish to maintain additional branches permanently, consider " +"making additional patch releases with minimal changes to the previous " +"version, especially when a security vulnerability is discovered." +msgstr "" + +#: ../source/discussions/downstream-packaging.rst:467 +msgid "" +"Split your changes into focused commits that address one problem at a time, " +"to make it easier to cherry-pick changes to earlier releases when necessary." +msgstr "" + +#: ../source/discussions/index.rst:4 +msgid "" +"**Discussions** are focused on providing comprehensive information about a " +"specific topic. If you're just trying to get stuff done, see :doc:`/guides/" +"index`." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:5 +msgid "install_requires vs requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:9 +msgid "install_requires" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:11 +msgid "" +"``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that " +"should be used to specify what a project **minimally** needs to run " +"correctly. When the project is installed by :ref:`pip`, this is the " +"specification that is used to install its dependencies." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:16 +msgid "" +"For example, if the project requires A and B, your ``install_requires`` " +"would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:26 +msgid "" +"Additionally, it's best practice to indicate any known lower or upper bounds." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:28 +msgid "" +"For example, it may be known, that your project requires at least v1 of 'A', " +"and v2 of 'B', so it would be like so:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:38 +msgid "" +"It may also be known that project 'A' introduced a change in its v2 that " +"breaks the compatibility of your project with v2 of 'A' and later, so it " +"makes sense to not allow v2:" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:49 +msgid "" +"It is not considered best practice to use ``install_requires`` to pin " +"dependencies to specific versions, or to specify sub-dependencies (i.e. " +"dependencies of your dependencies). This is overly-restrictive, and " +"prevents the user from gaining the benefit of dependency upgrades." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:54 +msgid "" +"Lastly, it's important to understand that ``install_requires`` is a listing " +"of \"Abstract\" requirements, i.e just names and version restrictions that " +"don't determine where the dependencies will be fulfilled from (i.e. from " +"what index or source). The where (i.e. how they are to be made " +"\"Concrete\") is to be determined at install time using :ref:`pip` options. " +"[1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:62 +#: ../source/tutorials/installing-packages.rst:464 +msgid "Requirements files" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:64 +msgid "" +":ref:`Requirements Files ` described most simply, " +"are just a list of :ref:`pip:pip install` arguments placed into a file." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:67 +msgid "" +"Whereas ``install_requires`` defines the dependencies for a single " +"project, :ref:`Requirements Files ` are often used " +"to define the requirements for a complete Python environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:71 +msgid "" +"Whereas ``install_requires`` requirements are minimal, requirements files " +"often contain an exhaustive listing of pinned versions for the purpose of " +"achieving :ref:`repeatable installations ` of a complete " +"environment." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:76 +msgid "" +"Whereas ``install_requires`` requirements are \"Abstract\", i.e. not " +"associated with any particular index, requirements files often contain pip " +"options like ``--index-url`` or ``--find-links`` to make requirements " +"\"Concrete\", i.e. associated with a particular index or directory of " +"packages. [1]_" +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:82 +msgid "" +"Whereas ``install_requires`` metadata is automatically analyzed by pip " +"during an install, requirements files are not, and only are used when a user " +"specifically installs them using ``python -m pip install -r``." +msgstr "" + +#: ../source/discussions/install-requires-vs-requirements.rst:88 +msgid "" +"For more on \"Abstract\" vs \"Concrete\" requirements, see https://" +"caremad.io/posts/2013/07/setup-vs-requirement/." +msgstr "" + +#: ../source/discussions/package-formats.rst:5 +#, fuzzy +#| msgid "Package Index" +msgid "Package Formats" +msgstr "套件索引" + +#: ../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 +msgid "What is a source distribution?" +msgstr "" + +#: ../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 +msgid "What about eggs?" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:14 +msgid "" +":ref:`pip` came later in 2008, as an 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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**pip**" +msgstr "**pip**" + +#: ../source/discussions/pip-vs-easy-install.rst:25 +msgid "**easy_install**" +msgstr "**easy_install**" + +#: ../source/discussions/pip-vs-easy-install.rst:27 +msgid "Installs from :term:`Wheels `" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:38 +msgid ":pep:`438` Support" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:41 +msgid "Encapsulated Egg format" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:44 +msgid "sys.path modification" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:48 +msgid "Installs from :term:`Eggs `" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "`pylauncher support`_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:51 +msgid "Yes [1]_" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:54 +msgid ":ref:`Multi-version Installs`" +msgstr "" + +#: ../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 "" + +#: ../source/discussions/pip-vs-easy-install.rst:60 +msgid "Yes, via setup.cfg" +msgstr "" + +#: ../source/discussions/pip-vs-easy-install.rst:68 +msgid "" +"https://setuptools.readthedocs.io/en/latest/deprecated/" +"easy_install.html#natural-script-launcher" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:6 +msgid "Is ``setup.py`` deprecated?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:8 +msgid "No, :term:`setup.py` and :ref:`setuptools` are not deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:10 +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`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:18 +msgid "" +"However, ``python setup.py`` and the use of :file:`setup.py` as a command " +"line tool are deprecated." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:21 +msgid "" +"This means that commands such as the following **MUST NOT** be run anymore:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:23 +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python setup.py install``" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 +#, fuzzy +#| msgid "Documentation types" +msgid "Recommendation" +msgstr "文件類型" + +#: ../source/discussions/setup-py-deprecated.rst:35 +#: ../source/guides/modernize-setup-py-project.rst:32 +msgid "``python -m pip install .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:37 +#: ../source/guides/modernize-setup-py-project.rst:34 +msgid "``python -m pip install --editable .``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:39 +msgid "``python -m build`` [#needs-build]_" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:45 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:52 +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``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:65 +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 .``." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:70 +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." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:80 +msgid "" +"The command ``python setup.py install`` was deprecated in setuptools version " +"*58.3.0*." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:85 +msgid "What about other commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:87 +msgid "What are some replacements for the other ``python setup.py`` commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:91 +msgid "``python setup.py test``" +msgstr "``python setup.py test``" + +#: ../source/discussions/setup-py-deprecated.rst:93 +msgid "The recommendation is to use a test runner such as pytest_." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:99 +msgid "" +"``python setup.py check``, ``python setup.py register``, and ``python " +"setup.py upload``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:101 +msgid "A trusted replacement is :ref:`twine`:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:103 +msgid "``python -m twine check --strict dist/*``" +msgstr "``python -m twine check --strict dist/*``" + +#: ../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/setup-py-deprecated.rst:105 +msgid "``python -m twine upload dist/*``" +msgstr "``python -m twine upload dist/*``" + +#: ../source/discussions/setup-py-deprecated.rst:107 +msgid "" +"Not necessary, nor supported on :term:`PyPI `. " +"But might be necessary on other :term:`package indexes ` (for " +"example :ref:`devpi`)." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:112 +msgid "``python setup.py --version``" +msgstr "``python setup.py --version``" + +#: ../source/discussions/setup-py-deprecated.rst:114 +msgid "" +"A possible replacement solution (among others) is to rely on setuptools-scm_:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:116 +msgid "``python -m setuptools_scm``" +msgstr "``python -m setuptools_scm``" + +#: ../source/discussions/setup-py-deprecated.rst:122 +msgid "Remaining commands" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:124 +msgid "" +"This guide does not make suggestions of replacement solutions for those " +"commands:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:129 +msgid "``alias``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:130 +msgid "``bdist``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:131 +msgid "``bdist_dumb``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:132 +msgid "``bdist_egg``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:133 +msgid "``bdist_rpm``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:134 +msgid "``build``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:135 +msgid "``build_clib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:136 +msgid "``build_ext``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:137 +msgid "``build_py``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:138 +msgid "``build_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:139 +msgid "``clean``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:140 +msgid "``dist_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:141 +#, fuzzy +#| msgid "**easy_install**" +msgid "``easy_install``" +msgstr "**easy_install**" + +#: ../source/discussions/setup-py-deprecated.rst:142 +msgid "``editable_wheel``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:143 +msgid "``egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:144 +msgid "``install_data``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:145 +msgid "``install_egg_info``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:146 +#, fuzzy +msgid "``install_headers``" +msgstr "維護者" + +#: ../source/discussions/setup-py-deprecated.rst:147 +msgid "``install_lib``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:148 +msgid "``install_scripts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:149 +msgid "``rotate``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:150 +msgid "``saveopts``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:151 +msgid "``setopt``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:152 +msgid "``upload_docs``" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:156 +msgid "What about custom commands?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:158 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:166 +msgid "What about custom build steps?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:168 +msgid "" +"Custom build steps that for example either overwrite existing steps such as " +"``build_py``, ``build_ext``, and ``bdist_wheel`` or add new build steps are " +"not deprecated. Those will be automatically called as expected." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:175 +#: ../source/guides/modernize-setup-py-project.rst:21 +msgid "Should ``setup.py`` be deleted?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:177 +msgid "" +"Although the usage of :file:`setup.py` as an executable script is " +"deprecated, its usage as a configuration file for setuptools is absolutely " +"fine. There is likely no modification needed in :file:`setup.py`." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:183 +msgid "Is ``pyproject.toml`` mandatory?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:185 +msgid "" +"While it is not technically necessary yet, it is **STRONGLY RECOMMENDED** " +"for a project to have a :file:`pyproject.toml` file at the root of its " +"source tree with a content like this:" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:196 +msgid "" +"The guide :ref:`modernize-setup-py-project` has more details about this." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:198 +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 "" + +#: ../source/discussions/setup-py-deprecated.rst:204 +msgid "Why? What does it all mean?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:206 +msgid "" +"One way to look at it is that the scope of setuptools has now been reduced " +"to the role of a build backend." +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:211 +#: ../source/guides/modernize-setup-py-project.rst:244 +msgid "Where to read more about this?" +msgstr "" + +#: ../source/discussions/setup-py-deprecated.rst:213 +#, fuzzy +#| msgid "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" +msgid "" +"`Why you shouldn't invoke setup.py directly `__ by Paul Ganssle" +msgstr "https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html" + +#: ../source/discussions/setup-py-deprecated.rst:215 +msgid ":doc:`setuptools:deprecated/commands`" +msgstr "" + +#: ../source/discussions/single-source-version.rst:5 +msgid "Single-sourcing the Project Version" +msgstr "" + +#: ../source/discussions/single-source-version.rst:7 +#, fuzzy +#| msgid "Incomplete" +msgid "Complete" +msgstr "不完整" + +#: ../source/discussions/single-source-version.rst:8 +#, fuzzy +#| msgid "2017-08-01" +msgid "2024-10-07" +msgstr "2017-08-01" + +#: ../source/discussions/single-source-version.rst:10 +msgid "" +"Many Python :term:`distribution packages ` publish a " +"single Python :term:`import package ` where it is desired " +"that the runtime ``__version__`` attribute on the import package report the " +"same version specifier as :func:`importlib.metadata.version` reports for the " +"distribution package (as described in :ref:`runtime-version-access`)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:16 +msgid "" +"It is also frequently desired that this version information be derived from " +"a version control system *tag* (such as ``v1.2.3``) rather than being " +"manually updated in the source code." +msgstr "" + +#: ../source/discussions/single-source-version.rst:20 +msgid "" +"Some projects may choose to simply live with the data entry duplication, and " +"rely on automated testing to ensure the different values do not diverge." +msgstr "" + +#: ../source/discussions/single-source-version.rst:23 +msgid "" +"Alternatively, a project's chosen build system may offer a way to define a " +"single source of truth for the version number." +msgstr "" + +#: ../source/discussions/single-source-version.rst:26 +msgid "In general, the options are:" +msgstr "" + +#: ../source/discussions/single-source-version.rst:28 +msgid "" +"If the code is in a version control system (VCS), such as Git, then the " +"version can be extracted from the VCS." +msgstr "" + +#: ../source/discussions/single-source-version.rst:30 +msgid "" +"The version can be hard-coded into the :file:`pyproject.toml` file -- and " +"the build system can copy it into other locations it may be required." +msgstr "" + +#: ../source/discussions/single-source-version.rst:33 +msgid "" +"The version string can be hard-coded into the source code -- either in a " +"special purpose file, such as :file:`_version.txt` (which must then be " +"shipped as part of the project's source distribution package), or as an " +"attribute in a particular module, such as :file:`__init__.py`. The build " +"system can then extract it from the runtime location at build time." +msgstr "" + +#: ../source/discussions/single-source-version.rst:38 +msgid "Consult your build system's documentation for their recommended method." +msgstr "" + +#: ../source/discussions/single-source-version.rst:40 +msgid "" +"When the intention is that a distribution package and its associated import " +"package share the same version, it is recommended that the project include " +"an automated test case that ensures ``import_name.__version__`` and " +"``importlib.metadata.version(\"dist-name\")`` report the same value (note: " +"for many projects, ``import_name`` and ``dist-name`` will be the same name)." +msgstr "" + +#: ../source/discussions/single-source-version.rst:50 +msgid "Build System Version Handling" +msgstr "" + +#: ../source/discussions/single-source-version.rst:52 +msgid "" +"The following are links to some build system's documentation for handling " +"version strings." +msgstr "" + +#: ../source/discussions/single-source-version.rst:54 +msgid "`Flit `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:56 +#, fuzzy +#| msgid "`Poetry `_" +msgid "`Hatchling `_" +msgstr "`Poetry `_" + +#: ../source/discussions/single-source-version.rst:58 +msgid "" +"`PDM `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:60 +msgid "" +"`Setuptools `_" +msgstr "" + +#: ../source/discussions/single-source-version.rst:62 +msgid "`setuptools_scm `_" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:5 +msgid "src layout vs flat layout" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:45 +msgid "" +"Here's a breakdown of the important behaviour differences between the src " +"layout and the flat layout:" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:48 +msgid "" +"The src layout requires installation of the project to be able to run its " +"code, and the flat layout does not." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:51 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:56 +msgid "" +"The src layout helps prevent accidental usage of the in-development copy of " +"the code." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:59 +msgid "" +"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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:66 +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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.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." +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:74 +msgid "" +"This is especially relevant when the editable installation is implemented " +"using a `path configuration file `_ that adds the directory to the import path." +msgstr "" + +#: ../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 "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:86 +msgid "Running a command-line interface from source with src-layout" +msgstr "" + +#: ../source/discussions/src-layout-vs-flat-layout.rst:88 +msgid "" +"Due to the firstly mentioned specialty of the src layout, a command-line " +"interface can not be run directly from the :term:`source tree `, but requires installation of the package in :doc:`Development " +"Mode ` for testing purposes. Since " +"this can be unpractical in some situations, a workaround could be to prepend " +"the package folder to Python's :py:data:`sys.path` when called via " +"its :file:`__main__.py` file:" +msgstr "" + +#: ../source/discussions/versioning.rst:6 +#: ../source/specifications/simple-repository-api.rst:349 +#, fuzzy +msgid "Versioning" +msgstr "翻譯" + +#: ../source/discussions/versioning.rst:8 +msgid "This discussion covers all aspects of versioning Python packages." +msgstr "" + +#: ../source/discussions/versioning.rst:12 +msgid "Valid version numbers" +msgstr "" + +#: ../source/discussions/versioning.rst:14 +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]_:" +msgstr "" + +#: ../source/discussions/versioning.rst:21 +msgid "A simple version (final release): ``1.2.0``" +msgstr "" + +#: ../source/discussions/versioning.rst:22 +msgid "A development release: ``1.2.0.dev1``" +msgstr "" + +#: ../source/discussions/versioning.rst:23 +msgid "An alpha release: ``1.2.0a1``" +msgstr "" + +#: ../source/discussions/versioning.rst:24 +msgid "A beta release: ``1.2.0b1``" +msgstr "" + +#: ../source/discussions/versioning.rst:25 +msgid "A release candidate: ``1.2.0rc1``" +msgstr "" + +#: ../source/discussions/versioning.rst:26 +msgid "A post-release: ``1.2.0.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:27 +msgid "" +"A post-release of an alpha release (possible, but discouraged): " +"``1.2.0a1.post1``" +msgstr "" + +#: ../source/discussions/versioning.rst:28 +msgid "A simple version with only two components: ``23.12``" +msgstr "" + +#: ../source/discussions/versioning.rst:29 +msgid "A simple version with just one component: ``42``" +msgstr "" + +#: ../source/discussions/versioning.rst:30 +msgid "A version with an epoch (discouraged): ``1!1.0``" +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 "" + +#: ../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 "" + +#: ../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/versioning.rst:49 +msgid "" +"Finally, epochs were intended to fix the sorting order when changing the " +"versioning scheme. For example, if a project was using calendar versioning, " +"with versions like ``23.12``, and switched to semantic versioning, with " +"versions like ``1.0``, the comparison between ``1.0`` and ``23.12`` would go " +"the wrong way. To correct this, the new version numbers would have an " +"explicit epoch, as in ``1!1.0``, in order to be treated as more recent than " +"the old version numbers. However, this is discouraged, and it is preferable " +"to use a higher version number that is unlikely to cause user confusion, " +"such as ``100.0``." +msgstr "" + +#: ../source/discussions/versioning.rst:60 +msgid "Semantic versioning vs. calendar versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:62 +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 "" + +#: ../source/discussions/versioning.rst:69 +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:75 +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 a security vulnerability needs to be addressed. Security releases often " +"come in patch versions but contain breaking changes inevitably." +msgstr "" + +#: ../source/discussions/versioning.rst:85 +#: ../source/specifications/version-specifiers.rst:741 +msgid "Semantic versioning" +msgstr "" + +#: ../source/discussions/versioning.rst:87 +msgid "" +"The idea of *semantic versioning* (or SemVer) is to use 3-part version " +"numbers, *major.minor.patch*, where the project author increments:" +msgstr "" + +#: ../source/discussions/versioning.rst:90 +msgid "*major* when they make incompatible API changes," +msgstr "" + +#: ../source/discussions/versioning.rst:91 +msgid "" +"*minor* when they add functionality in a backwards-compatible manner, and" +msgstr "" + +#: ../source/discussions/versioning.rst:92 +msgid "*patch*, when they make backwards-compatible bug fixes." +msgstr "" + +#: ../source/discussions/versioning.rst:94 +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 "" + +#: ../source/discussions/versioning.rst:104 +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 "" + +#: ../source/discussions/versioning.rst:113 +msgid "" +"Python projects adopting semantic versioning should abide by clauses 1-8 of " +"the `Semantic Versioning 2.0.0 specification `_." +msgstr "" + +#: ../source/discussions/versioning.rst:116 +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 "" + +#: ../source/discussions/versioning.rst:125 +#, fuzzy +msgid "Calendar versioning" +msgstr "翻譯" + +#: ../source/discussions/versioning.rst:127 +msgid "" +"Semantic versioning is not a suitable choice for all projects, such as those " +"with a regular time-based release cadence and a deprecation process that " +"provides warnings for a number of releases prior to removal of a feature." +msgstr "" + +#: ../source/discussions/versioning.rst:131 +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 "" + +#: ../source/discussions/versioning.rst:135 +msgid "" +"Calendar version numbers typically take the form *year.month* (for example, " +"23.12 for December 2023)." +msgstr "" + +#: ../source/discussions/versioning.rst:138 +msgid "" +":doc:`Pip `, the standard Python package installer, uses calendar " +"versioning." +msgstr "" + +#: ../source/discussions/versioning.rst:143 +#, fuzzy +msgid "Other schemes" +msgstr "翻譯" + +#: ../source/discussions/versioning.rst:145 +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 "" + +#: ../source/discussions/versioning.rst:151 +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/discussions/versioning.rst:178 +msgid "Accessing version information at runtime" +msgstr "" + +#: ../source/discussions/versioning.rst:180 +msgid "" +"Version information for all :term:`distribution packages ` that are locally available in the current environment can be " +"obtained at runtime using the standard " +"library's :func:`importlib.metadata.version` function::" +msgstr "" + +#: ../source/discussions/versioning.rst:187 +msgid "" +"Many projects also choose to version their top level :term:`import packages " +"` by providing a package level ``__version__`` attribute::" +msgstr "" + +#: ../source/discussions/versioning.rst:195 +msgid "" +"This technique can be particularly valuable for CLI applications which want " +"to ensure that version query invocations (such as ``pip -V``) run as quickly " +"as possible." +msgstr "" + +#: ../source/discussions/versioning.rst:199 +msgid "" +"Package publishers wishing to ensure their reported distribution package and " +"import package versions are consistent with each other can review " +"the :ref:`single-source-version` discussion for potential approaches to " +"doing so." +msgstr "" + +#: ../source/discussions/versioning.rst:203 +msgid "" +"As import packages and modules are not *required* to publish runtime version " +"information in this way (see the withdrawn proposal in :pep:`PEP 396 " +"<396>`), the ``__version__`` attribute should either only be queried with " +"interfaces that are known to provide it (such as a project querying its own " +"version or the version of one of its direct dependencies), or else the " +"querying code should be designed to handle the case where the attribute is " +"missing [#fallback-to-dist-version]_." +msgstr "" + +#: ../source/discussions/versioning.rst:211 +msgid "" +"Some projects may need to publish version information for external APIs that " +"aren't the version of the module itself. Such projects should define their " +"own project-specific ways of obtaining the relevant information at runtime. " +"For example, the standard library's :mod:`ssl` module offers multiple ways " +"to access the underlying OpenSSL library version::" +msgstr "" + +#: ../source/discussions/versioning.rst:226 +msgid "" +"Some more examples of unusual version numbers are given in a `blog post " +"`_ by Seth Larson." +msgstr "" + +#: ../source/discussions/versioning.rst:229 +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 "" + +#: ../source/discussions/versioning.rst:235 +msgid "" +"A full list mapping the top level names available for import to the " +"distribution packages that provide those import packages and modules may be " +"obtained through the standard " +"library's :func:`importlib.metadata.packages_distributions` function. This " +"means that even code that is attempting to infer a version to report for all " +"importable top-level names has a means to fall back to reporting the " +"distribution version information if no ``__version__`` attribute is defined. " +"Only standard library modules, and modules added via means other than Python " +"package installation would fail to have version information reported in that " +"case." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:19 +msgid "" +"Have a source tree containing the package. This is typically a checkout from " +"a version control system (VCS)." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:47 +msgid "" +"These last 2 steps are typically performed by :ref:`pip` when an end user " +"runs ``pip install``." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:77 +msgid "For example, here is a table for using :ref:`hatch`:" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:97 +msgid "" +"a ``[project]`` table containing project :doc:`Core Metadata ` (name, version, author and so forth)," +msgstr "" + +#: ../source/flow.rst:101 +msgid "a ``[tool]`` table containing tool-specific configuration options." +msgstr "" + +#: ../source/flow.rst:103 +msgid "" +"Refer to the :ref:`pyproject.toml guide ` for a " +"complete guide to ``pyproject.toml`` configuration." +msgstr "" + +#: ../source/flow.rst:108 +msgid "Build artifacts" +msgstr "" + +#: ../source/flow.rst:111 +msgid "The source distribution (sdist)" +msgstr "" + +#: ../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 "" + +#: ../source/flow.rst:119 ../source/flow.rst:143 +msgid "" +"The :ref:`build` package knows how to invoke your build tool to create one " +"of these:" +msgstr "" + +#: ../source/flow.rst:126 +msgid "" +"Or, your build tool may provide its own interface for creating an sdist." +msgstr "" + +#: ../source/flow.rst:130 +msgid "The built distributions (wheels)" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/flow.rst:150 +msgid "Or, your build tool may provide its own interface for creating a wheel." +msgstr "" + +#: ../source/flow.rst:154 +msgid "" +"The default behaviour of :ref:`build` is to make both an sdist and a wheel " +"from the source in the current directory; the above examples are " +"deliberately specific." +msgstr "" + +#: ../source/flow.rst: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 "" + +#: ../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 "" + +#: ../source/flow.rst:181 +msgid "" +"End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, " +"or :ref:`pdm`." +msgstr "" + +#: ../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 :term:`source tree ` and builds " +"a :term:`source distribution ` " +"or :term:`built distribution ` from it. The build is " +"delegated to the backend by a :term:`frontend `. All " +"backends offer a standardized interface." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/glossary.rst:42 +msgid "Examples of build frontends are :ref:`pip` and :ref:`build`." +msgstr "" + +#: ../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 :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 +msgid "Built Metadata" +msgstr "" + +#: ../source/glossary.rst:59 +msgid "" +"The concrete form :term:`Core Metadata` takes when included inside an " +"installed :term:`Project` (``METADATA`` file) or a :term:`Distribution " +"Archive` (``PKG-INFO`` in a :term:`Sdist ` and ``METADATA`` in a :term:`Wheel`)." +msgstr "" + +#: ../source/glossary.rst:66 +msgid "Core Metadata" +msgstr "" + +#: ../source/glossary.rst:69 +msgid "" +"The :ref:`specification ` and the set of :term:`Core Metadata " +"Field`\\s it defines that describe key static attributes of " +"a :term:`Distribution Package` or :term:`Installed Project`." +msgstr "" + +#: ../source/glossary.rst:74 +msgid "Core Metadata Field" +msgstr "" + +#: ../source/glossary.rst:77 +msgid "" +"A single key-value pair (or sequence of such with the same name, for " +"multiple-use fields) defined in the :term:`Core Metadata` spec and stored in " +"the :term:`Built Metadata`. Notably, distinct from a :term:`Pyproject " +"Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:83 +msgid "Distribution Archive" +msgstr "" + +#: ../source/glossary.rst:86 +msgid "" +"The physical distribution artifact (i.e. a file on disk) for " +"a :term:`Distribution Package`." +msgstr "" + +#: ../source/glossary.rst:89 +msgid "Distribution Package" +msgstr "" + +#: ../source/glossary.rst:92 +msgid "" +"A versioned archive file that contains Python :term:`packages `, :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 "" + +#: ../source/glossary.rst:97 +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 "" + +#: ../source/glossary.rst:105 +msgid "Egg" +msgstr "" + +#: ../source/glossary.rst:108 +msgid "" +"A :term:`Built Distribution` format introduced by :ref:`setuptools`, which " +"has been replaced by :term:`Wheel`. For details, see :ref:`egg-format`." +msgstr "" + +#: ../source/glossary.rst:111 +msgid "Extension Module" +msgstr "" + +#: ../source/glossary.rst:114 +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 "" + +#: ../source/glossary.rst:121 +msgid "Import Package" +msgstr "" + +#: ../source/glossary.rst:124 +msgid "" +"A Python module which can contain other modules or recursively, other " +"packages." +msgstr "" + +#: ../source/glossary.rst:127 +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 "" + +#: ../source/glossary.rst:133 +#, fuzzy +msgid "Installed Project" +msgstr "安裝軟體套件" + +#: ../source/glossary.rst:136 +msgid "" +"A :term:`Project` that is installed for use with a Python interpreter " +"or :term:`Virtual Environment`, as described in the " +"specification :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/glossary.rst:140 +msgid "Known Good Set (KGS)" +msgstr "" + +#: ../source/glossary.rst:143 +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 "" + +#: ../source/glossary.rst:149 +msgid "License Classifier" +msgstr "" + +#: ../source/glossary.rst:152 +msgid "" +"A PyPI Trove classifier (as :ref:`described ` in " +"the :term:`Core Metadata` specification) which begins with ``License ::``." +msgstr "" + +#: ../source/glossary.rst:157 ../source/specifications/license-expression.rst:3 +msgid "License Expression" +msgstr "" + +#: ../source/glossary.rst:158 +msgid "SPDX Expression" +msgstr "" + +#: ../source/glossary.rst:161 +msgid "" +"A string with valid SPDX license expression syntax, including one or more " +"SPDX :term:`License Identifier`\\(s), which describes a :term:`Distribution " +"Archive`'s license(s) and how they inter-relate. Examples: ``GPL-3.0-or-" +"later``, ``MIT AND (Apache-2.0 OR BSD-2-Clause)``" +msgstr "" + +#: ../source/glossary.rst:169 +msgid "License Identifier" +msgstr "" + +#: ../source/glossary.rst:170 +msgid "SPDX Identifier" +msgstr "" + +#: ../source/glossary.rst:173 +msgid "" +"A valid SPDX short-form license identifier, originally specified " +"in :pep:`639`. This includes all valid SPDX identifiers and the custom " +"``LicenseRef-[idstring]`` strings conforming to the SPDX specification. " +"Examples: ``MIT``, ``GPL-3.0-only``, ``LicenseRef-My-Custom-License``" +msgstr "" + +#: ../source/glossary.rst:183 +msgid "Module" +msgstr "模組" + +#: ../source/glossary.rst:186 +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:189 +msgid "Package Index" +msgstr "套件索引" + +#: ../source/glossary.rst:192 +msgid "" +"A repository of distributions with a web interface to " +"automate :term:`package ` discovery and consumption." +msgstr "" + +#: ../source/glossary.rst:195 +msgid "Per Project Index" +msgstr "" + +#: ../source/glossary.rst:198 +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:202 ../source/guides/hosting-your-own-index.rst:62 +#: ../source/guides/index-mirrors-and-caches.rst:52 +msgid "Project" +msgstr "專案" + +#: ../source/glossary.rst:205 +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:209 +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 "" + +#: ../source/glossary.rst:215 +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 "" + +#: ../source/glossary.rst:220 +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:226 +#, fuzzy +#| msgid "Project name" +msgid "Project Root Directory" +msgstr "專案名稱" + +#: ../source/glossary.rst:229 +msgid "" +"The filesystem directory in which a :term:`Project`'s :term:`source tree " +"` is located." +msgstr "" + +#: ../source/glossary.rst:232 +msgid "Project Source Tree" +msgstr "" + +#: ../source/glossary.rst:235 +msgid "" +"The on-disk format of a :term:`Project` used for development, containing its " +"raw source code before being packaged into a :term:`Source Distribution " +"` or :term:`Built Distribution`." +msgstr "" + +#: ../source/glossary.rst:241 +msgid "Project Source Metadata" +msgstr "" + +#: ../source/glossary.rst:244 +msgid "" +"Metadata defined by the package author in a :term:`Project`'s :term:`source " +"tree `, to be transformed into :term:`Core Metadata " +"field`\\s in the :term:`Built Metadata` by the project's :term:`build " +"backend `. Can be written as :term:`Pyproject Metadata`, or " +"in a tool-specific format (under the ``[tool]`` table in ``pyproject.toml``, " +"or in a tool's own configuration file)." +msgstr "" + +#: ../source/glossary.rst:254 +msgid "Pure Module" +msgstr "" + +#: ../source/glossary.rst:257 +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:260 +#, fuzzy +#| msgid "Project name" +msgid "Pyproject Metadata" +msgstr "專案名稱" + +#: ../source/glossary.rst:263 +msgid "" +"The :term:`Project Source Metadata` format defined by the :ref:`declaring-" +"project-metadata` specification and originally introduced in :pep:`621`, " +"stored as :term:`Pyproject Metadata Key`\\s under the ``[project]`` table of " +"a :term:`pyproject.toml` file. Notably, *not* a tool-specific source " +"metadata format under the ``[tool]`` table in ``pyproject.toml``." +msgstr "" + +#: ../source/glossary.rst:271 +#, fuzzy +#| msgid "Project name" +msgid "Pyproject Metadata Key" +msgstr "專案名稱" + +#: ../source/glossary.rst:274 +msgid "" +"A top-level TOML key in the ``[project]`` table in ``pyproject.toml``; part " +"of the :term:`Pyproject Metadata`. Notably, distinct from a :term:`Core " +"Metadata Field`." +msgstr "" + +#: ../source/glossary.rst:278 +msgid "Pyproject Metadata Subkey" +msgstr "" + +#: ../source/glossary.rst:281 +msgid "" +"A second-level TOML key under a table-valued :term:`Pyproject Metadata Key`." +msgstr "" + +#: ../source/glossary.rst:284 +msgid "Python Packaging Authority (PyPA)" +msgstr "" + +#: ../source/glossary.rst:287 +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 discuss issues on the " +"`distutils-sig mailing list `_ and `the Python Discourse forum `__." +msgstr "" + +#: ../source/glossary.rst:295 +msgid "Python Package Index (PyPI)" +msgstr "" + +#: ../source/glossary.rst:298 +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:301 +msgid "pypi.org" +msgstr "pypi.org" + +#: ../source/glossary.rst:304 +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:308 +msgid "pyproject.toml" +msgstr "pyproject.toml" + +#: ../source/glossary.rst:311 +msgid "" +"The tool-agnostic :term:`Project` specification file. Defined in :pep:`518`." +msgstr "" + +#: ../source/glossary.rst:313 +msgid "Release" +msgstr "發行版本" + +#: ../source/glossary.rst:316 +msgid "" +"A snapshot of a :term:`Project` at a particular point in time, denoted by a " +"version identifier." +msgstr "" + +#: ../source/glossary.rst:319 +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 "" + +#: ../source/glossary.rst:324 +msgid "Requirement" +msgstr "要求" + +#: ../source/glossary.rst:327 +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 "" + +#: ../source/glossary.rst:333 +msgid "Requirement Specifier" +msgstr "" + +#: ../source/glossary.rst:336 +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 "" + +#: ../source/glossary.rst:341 +msgid "Requirements File" +msgstr "" + +#: ../source/glossary.rst:344 +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:348 +#, fuzzy +#| msgid "Project name" +msgid "Root License Directory" +msgstr "專案名稱" + +#: ../source/glossary.rst:349 +msgid "License Directory" +msgstr "" + +#: ../source/glossary.rst:352 +msgid "" +"The directory under which license files are stored in a :term:`Project " +"Source Tree`, :term:`Distribution Archive` or :term:`Installed Project`. For " +"a :term:`Project Source Tree` or :term:`Source Distribution (or \"sdist\")`, " +"this is the :term:`Project Root Directory`. For a :term:`Built Distribution` " +"or :term:`Installed Project`, this is the :file:`.dist-info/licenses/` " +"directory of the wheel archive or project folder respectively. Also, the " +"root directory that paths recorded in the ``License-File`` :term:`Core " +"Metadata Field` are relative to." +msgstr "" + +#: ../source/glossary.rst:365 +#: ../source/guides/distributing-packages-using-setuptools.rst:59 +msgid "setup.py" +msgstr "setup.py" + +#: ../source/glossary.rst:366 +#: ../source/guides/distributing-packages-using-setuptools.rst:80 +msgid "setup.cfg" +msgstr "setup.cfg" + +#: ../source/glossary.rst:369 +msgid "" +"The project specification files for :ref:`distutils` and :ref:`setuptools`. " +"See also :term:`pyproject.toml`." +msgstr "" + +#: ../source/glossary.rst:372 +msgid "Source Archive" +msgstr "" + +#: ../source/glossary.rst:375 +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:379 +msgid "Source Distribution (or \"sdist\")" +msgstr "" + +#: ../source/glossary.rst:382 +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." +msgstr "" + +#: ../source/glossary.rst:388 +msgid "System Package" +msgstr "" + +#: ../source/glossary.rst:391 +msgid "" +"A package provided in a format native to the operating system, e.g. an rpm " +"or dpkg file." +msgstr "" + +#: ../source/glossary.rst:394 +msgid "Version Specifier" +msgstr "" + +#: ../source/glossary.rst:397 +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 "" + +#: ../source/glossary.rst:402 +msgid "Virtual Environment" +msgstr "" + +#: ../source/glossary.rst:405 +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 "" + +#: ../source/glossary.rst:410 +msgid "Wheel Format" +msgstr "" + +#: ../source/glossary.rst:411 +msgid "Wheel" +msgstr "" + +#: ../source/glossary.rst:414 +msgid "" +"The standard :term:`Built Distribution` format originally introduced " +"in :pep:`427` and defined by the :ref:`binary-distribution-format` " +"specification. See :ref:`package-formats` for more information. Not to be " +"confused with its reference implementation, the :term:`Wheel Project`." +msgstr "" + +#: ../source/glossary.rst:421 +msgid "Wheel Project" +msgstr "" + +#: ../source/glossary.rst:424 +msgid "" +"The PyPA reference implementation of the :term:`Wheel Format`; " +"see :ref:`wheel`." +msgstr "" + +#: ../source/glossary.rst:426 +msgid "Working Set" +msgstr "" + +#: ../source/glossary.rst:429 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:5 +msgid "Analyzing PyPI package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:7 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:14 +#: ../source/guides/supporting-windows-using-appveyor.rst:17 +msgid "Background" +msgstr "背景" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:16 +msgid "PyPI does not display download statistics for a number of reasons: [#]_" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:18 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:23 +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:26 +msgid "``pip``'s download cache (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:27 +msgid "" +"Internal or unofficial mirrors (can both raise or lower download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:28 +msgid "Packages not hosted on PyPI (for comparisons sake)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:29 +msgid "" +"Unofficial scripts or attempts at download count inflation (raises download " +"counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:31 +msgid "Known historical data quality issues (lowers download counts)" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:33 +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:37 +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:42 +msgid "Public dataset" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:44 +msgid "" +"As an alternative, the `Linehaul project `__ streams download logs from PyPI to `Google BigQuery`_ " +"[#]_, where they are stored as a public dataset." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:49 +msgid "Getting set up" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:51 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:57 +msgid "Navigate to the `BigQuery web UI`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:58 +msgid "Create a new project." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:59 +msgid "" +"Enable the `BigQuery API `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:62 +msgid "" +"For more detailed instructions on how to get started with BigQuery, check " +"out the `BigQuery quickstart guide `__." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:68 +msgid "Data schema" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:70 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +msgid "Column" +msgstr "欄" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/core-metadata.rst:206 +#: ../source/specifications/well-known-project-urls.rst:106 +msgid "Description" +msgstr "描述" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:77 +#: ../source/specifications/dependency-groups.rst:23 +#: ../source/specifications/dependency-specifiers.rst:29 +#: ../source/specifications/direct-url-data-structure.rst:242 +#: ../source/specifications/version-specifiers.rst:1088 +msgid "Examples" +msgstr "例子" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "timestamp" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "Date and time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:79 +msgid "``2020-03-09 00:33:03 UTC``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "file.project" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "Project name" +msgstr "專案名稱" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:81 +msgid "``pipenv``, ``nose``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "file.version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "Package version" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:83 +msgid "``0.1.6``, ``1.4.2``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "details.installer.name" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "Installer" +msgstr "安裝程式" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:85 +msgid "pip, :ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "details.python" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "Python version" +msgstr "Python 版本" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:87 +msgid "``2.7.12``, ``3.6.4``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:92 +msgid "Useful queries" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:94 +msgid "" +"Run queries in the `BigQuery web UI`_ by clicking the \"Compose query\" " +"button." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:96 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:101 +msgid "Counting package downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:103 +msgid "" +"The following query counts the total number of downloads for the project " +"\"pytest\"." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:118 +#: ../source/guides/analyzing-pypi-package-downloads.rst:139 +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "num_downloads" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:120 +msgid "26190085" +msgstr "26190085" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:123 +msgid "" +"To count downloads from pip only, filter on the ``details.installer.name`` " +"column." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:141 +msgid "24334215" +msgstr "24334215" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:145 +msgid "Package downloads over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:147 +msgid "" +"To group by monthly downloads, use the ``TIMESTAMP_TRUNC`` function. Also " +"filtering by this column reduces corresponding costs." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:167 +msgid "month" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "1956741" +msgstr "1956741" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:169 +msgid "2018-01-01" +msgstr "2018-01-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2344692" +msgstr "2344692" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:171 +msgid "2017-12-01" +msgstr "2017-12-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "1730398" +msgstr "1730398" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:173 +msgid "2017-11-01" +msgstr "2017-11-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2047310" +msgstr "2047310" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:175 +msgid "2017-10-01" +msgstr "2017-10-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "1744443" +msgstr "1744443" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:177 +msgid "2017-09-01" +msgstr "2017-09-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "1916952" +msgstr "1916952" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:179 +msgid "2017-08-01" +msgstr "2017-08-01" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:183 +msgid "Python versions over time" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:185 +msgid "" +"Extract the Python version from the ``details.python`` column. Warning: This " +"query processes over 500 GB of data." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:204 +msgid "python" +msgstr "python" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "3.7" +msgstr "3.7" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:206 +msgid "18051328726" +msgstr "18051328726" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "3.6" +msgstr "3.6" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:208 +msgid "9635067203" +msgstr "9635067203" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "3.8" +msgstr "3.8" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:210 +msgid "7781904681" +msgstr "7781904681" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "2.7" +msgstr "2.7" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:212 +msgid "6381252241" +msgstr "6381252241" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "null" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:214 +msgid "2026630299" +msgstr "2026630299" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "3.5" +msgstr "3.5" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:216 +msgid "1894153540" +msgstr "1894153540" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:221 +msgid "Getting absolute links to artifacts" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:223 +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 "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:229 +msgid "" +"The URL generated here is not guaranteed to be stable, but currently aligns " +"with the URL where PyPI artifacts are hosted." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:242 +msgid "url" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:244 +msgid "" +"https://files.pythonhosted.org/packages/eb/" +"45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/" +"sampleproject-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:246 +msgid "" +"https://files.pythonhosted.org/packages/56/0a/" +"178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/" +"sampleproject_nomura-1.2.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:248 +msgid "" +"https://files.pythonhosted.org/packages/" +"63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/" +"sampleproject_nomura-1.2.0.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:250 +msgid "" +"https://files.pythonhosted.org/packages/21/" +"e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/" +"sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:252 +msgid "" +"https://files.pythonhosted.org/packages/6f/5b/" +"2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/" +"sampleproject-1.3.1.tar.gz" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:257 +msgid "Caveats" +msgstr "注意事項" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:259 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:267 +msgid "Additional tools" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:269 +msgid "" +"Besides using the BigQuery console, there are some additional tools which " +"may be useful when analyzing download statistics." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:273 +msgid "``google-cloud-bigquery``" +msgstr "``google-cloud-bigquery``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:275 +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." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:303 +msgid "``pypinfo``" +msgstr "``pypinfo``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:305 +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``." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:309 +msgid "Install `pypinfo`_ using pip." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:315 +msgid "Usage:" +msgstr "用法：" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:331 +msgid "``pandas-gbq``" +msgstr "``pandas-gbq``" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:333 +msgid "" +"The `pandas-gbq`_ project allows for accessing query results via `Pandas`_." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:337 +msgid "``ClickPy``" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:339 +msgid "" +"The `ClickPy`_ project provides a public application to visualize download " +"statistics, with free direct SQL access to the underlying open-source " +"`ClickHouse`_ database, updated daily." +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:345 +#: ../source/specifications/dependency-specifiers.rst:537 +msgid "References" +msgstr "參考" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:347 +msgid "" +"`PyPI Download Counts deprecation email `__" +msgstr "" + +#: ../source/guides/analyzing-pypi-package-downloads.rst:348 +msgid "" +"`PyPI BigQuery dataset announcement email `__" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:3 +msgid "Creating and discovering plugins" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:5 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:10 +msgid "There are three major approaches to doing automatic plugin discovery:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:12 +msgid "`Using naming convention`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:13 +msgid "`Using namespace packages`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:14 +msgid "`Using package metadata`_." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:18 +msgid "Using naming convention" +msgstr "" + +#: ../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/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 "" + +#: ../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 "" + +#: ../source/guides/creating-and-discovering-plugins.rst:58 +msgid "Using namespace packages" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:60 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:88 +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:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:100 +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`." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:114 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:122 +msgid "Using package metadata" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:124 +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." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:128 +msgid "" +"For example if you have a package named ``myapp-plugin-a`` and it includes " +"the following in its ``pyproject.toml``:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:136 +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):" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:151 +msgid "" +"In this example, ``discovered_plugins`` would be a collection of " +"type :class:`importlib.metadata.EntryPoint`:" +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:160 +msgid "" +"Now the module of your choice can be imported by executing " +"``discovered_plugins['a'].load()``." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:163 +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 ` ." +msgstr "" + +#: ../source/guides/creating-and-discovering-plugins.rst:167 +msgid "" +"Since this specification is part of the :doc:`standard library " +"`, most packaging tools other than " +"setuptools provide support for defining entry points." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:5 +msgid "Creating and packaging command-line tools" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:7 +msgid "" +"This guide will walk you through creating and packaging a standalone command-" +"line application that can be installed with :ref:`pipx`, a tool for creating " +"and managing :term:`Python Virtual Environments ` and " +"exposing the executable scripts of packages (and available manual pages) for " +"use on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:12 +#, fuzzy +#| msgid "and import the package:" +msgid "Creating the package" +msgstr "然後載入那個套件:" + +#: ../source/guides/creating-command-line-tools.rst:14 +msgid "" +"First of all, create a source tree for the :term:`project `. For " +"the sake of an example, we'll build a simple tool outputting a greeting (a " +"string) for a person based on arguments given on the command-line." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +#: ../source/guides/tool-recommendations.rst:45 +msgid "Todo" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:17 +msgid "" +"Advise on the optimal structure of a Python package in another guide or " +"discussion and link to it here." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:19 +msgid "" +"This project will adhere to :ref:`src-layout ` " +"and in the end be alike this file tree, with the top-level folder and " +"package name ``greetings``:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:33 +msgid "" +"The actual code responsible for the tool's functionality will be stored in " +"the file :file:`greet.py`, named after the main module:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:62 +msgid "" +"The above function receives several keyword arguments that determine how the " +"greeting to output is constructed. Now, construct the command-line interface " +"to provision it with the same, which is done in :file:`cli.py`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:80 +msgid "" +"The command-line interface is built with typer_, an easy-to-use CLI parser " +"based on Python type hints. It provides auto-completion and nicely styled " +"command-line help out of the box. Another option would " +"be :py:mod:`argparse`, a command-line parser which is included in Python's " +"standard library. It is sufficient for most needs, but requires a lot of " +"code, usually in ``cli.py``, to function properly. Alternatively, docopt_ " +"makes it possible to create CLI interfaces based solely on docstrings; " +"advanced users are encouraged to make use of click_ (on which ``typer`` is " +"based)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:86 +msgid "" +"Now, add an empty :file:`__init__.py` file, to define the project as a " +"regular :term:`import package `." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:88 +msgid "" +"The file :file:`__main__.py` marks the main entry point for the application " +"when running it via :mod:`runpy` (i.e. ``python -m greetings``, which works " +"immediately with flat layout, but requires installation of the package with " +"src layout), so initialize the command-line interface here:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:100 +msgid "" +"In order to enable calling the command-line interface directly from " +"the :term:`source tree `, i.e. as ``python src/" +"greetings``, a certain hack could be placed in this file; read more " +"at :ref:`running-cli-from-source-src-layout`." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:106 +#, fuzzy +#| msgid "pyproject.toml" +msgid "``pyproject.toml``" +msgstr "pyproject.toml" + +#: ../source/guides/creating-command-line-tools.rst:108 +msgid "" +"The project's :term:`metadata ` is placed " +"in :term:`pyproject.toml`. The :term:`pyproject metadata keys ` and the ``[build-system]`` table may be filled in as " +"described in :ref:`writing-pyproject-toml`, adding a dependency on ``typer`` " +"(this tutorial uses version *0.12.3*)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:111 +msgid "" +"For the project to be recognised as a command-line tool, additionally a " +"``console_scripts`` :ref:`entry point ` " +"(see :ref:`console_scripts`) needs to be added as a :term:`subkey `:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:118 +msgid "" +"Now, the project's source tree is ready to be transformed into " +"a :term:`distribution package `, which makes it " +"installable." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:123 +#, fuzzy +#| msgid "Install packages using pip" +msgid "Installing the package with ``pipx``" +msgstr "使用 pip 安裝程式包" + +#: ../source/guides/creating-command-line-tools.rst:125 +msgid "" +"After installing ``pipx`` as described in :ref:`installing-stand-alone-" +"command-line-tools`, install your project:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:132 +msgid "" +"This will expose the executable script we defined as an entry point and make " +"the command ``greet`` available. Let's test it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:146 +msgid "" +"Since this example uses ``typer``, you could now also get an overview of the " +"program's usage by calling it with the ``--help`` option, or configure " +"completions via the ``--install-completion`` option." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:149 +msgid "" +"To just run the program without installing it permanently, use ``pipx run``, " +"which will create a temporary (but cached) virtual environment for it:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:156 +msgid "" +"This syntax is a bit impractical, however; as the name of the entry point we " +"defined above does not match the package name, we need to state explicitly " +"which executable script to run (even though there is only one in existence)." +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:159 +msgid "" +"There is, however, a more practical solution to this problem, in the form of " +"an entry point specific to ``pipx run``. The same can be defined as follows " +"in :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:168 +msgid "" +"Thanks to this entry point (which *must* match the package name), ``pipx`` " +"will pick up the executable script as the default one and run it, which " +"makes this command possible:" +msgstr "" + +#: ../source/guides/creating-command-line-tools.rst:176 +#, fuzzy +msgid "Conclusion" +msgstr "翻譯" + +#: ../source/guides/creating-command-line-tools.rst:178 +msgid "" +"You know by now how to package a command-line application written in Python. " +"A further step could be to distribute your package, meaning uploading it to " +"a :term:`package index `, most commonly :term:`PyPI `. To do that, follow the instructions " +"at :ref:`Packaging your project`. And once you're done, don't forget " +"to :ref:`do some research ` on how your " +"package is received!" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:5 +msgid "Packaging and distributing projects" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:7 +msgid "Outdated" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:8 +#, fuzzy +#| msgid "2017-12-01" +msgid "2023-12-14" +msgstr "2017-12-01" + +#: ../source/guides/distributing-packages-using-setuptools.rst:10 +msgid "" +"This section covers some additional details on configuring, packaging and " +"distributing Python projects with ``setuptools`` that aren't covered by the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:16 +msgid "" +"The section does *not* aim to cover best practices for Python project " +"development as a whole. For example, it does not provide guidance or tool " +"recommendations for version control, documentation, or testing." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:20 +msgid "" +"For more reference material, see :std:doc:`Building and Distributing " +"Packages ` in the :ref:`setuptools` docs, but " +"note that some advisory content there may be outdated. In the event of " +"conflicts, prefer the advice in the Python Packaging User Guide." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:28 +msgid "Requirements for packaging and distributing" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:29 +msgid "" +"First, make sure you have already fulfilled the :ref:`requirements for " +"installing packages `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:32 +msgid "Install \"twine\" [1]_:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:46 +msgid "" +"You'll need this to upload your project :term:`distributions ` to :term:`PyPI ` (see :ref:`below " +"`)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:66 +msgid ":file:`setup.py` serves two primary functions:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:68 +msgid "" +"It's the file where various aspects of your project are configured. The " +"primary feature of :file:`setup.py` is that it contains a global ``setup()`` " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:74 +msgid "" +"It's the command line interface for running various commands that relate to " +"packaging tasks. To get a listing of available commands, run ``python3 " +"setup.py --help-commands``." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:82 +msgid "" +":file:`setup.cfg` is an ini file that contains option defaults " +"for :file:`setup.py` commands. For an example, see the `setup.cfg `_ in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:89 +msgid "README.rst / README.md" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:91 +msgid "" +"All projects should contain a readme file that covers the goal of the " +"project. The most common format is `reStructuredText `_ 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:98 +msgid "" +"For an example, see `README.md `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:102 +msgid "" +"Projects using :ref:`setuptools` 0.6.27+ have standard readme files " +"(:file:`README.rst`, :file:`README.txt`, or :file:`README`) included in " +"source 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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:111 +msgid "MANIFEST.in" +msgstr "MANIFEST.in" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:118 +msgid "" +"However, you may not have to use a :file:`MANIFEST.in`. For an example, the " +"`PyPA sample project `_ has removed " +"its manifest file, since all the necessary files have been included " +"by :ref:`setuptools` 43.0.0 and newer." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:123 +msgid "" +":file:`MANIFEST.in` does not affect binary distributions such as wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:126 +msgid "LICENSE.txt" +msgstr "LICENSE.txt" + +#: ../source/guides/distributing-packages-using-setuptools.rst:128 +msgid "" +"Every package should include a license file detailing the terms of " +"distribution. In many jurisdictions, packages without an explicit license " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:134 +msgid "" +"For an example, see the `LICENSE.txt `_ from the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:139 +msgid "" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:141 +msgid "" +"Although it's not required, the most common practice is to include your " +"Python modules and packages under a single top-level package that has the " +"same :ref:`name ` as your project, or something very close." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:145 +msgid "" +"For an example, see the `sample `_ package that's included in the `PyPA sample project " +"`_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:153 +msgid "setup() args" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:155 +msgid "" +"As mentioned above, the primary feature of :file:`setup.py` is that it " +"contains a global ``setup()`` function. The keyword arguments to this " +"function are how specific details of your project are defined." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:159 +msgid "" +"Some are temporarily explained below until their information is moved " +"elsewhere. The full list can be found :doc:`in the setuptools documentation " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:163 +msgid "" +"Most of the snippets given are taken from the `setup.py `_ " +"contained in the `PyPA sample project `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:170 +msgid "" +"See :ref:`Choosing a versioning scheme` for more information on ways to use " +"versions to convey compatibility information to your users." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:177 +msgid "``packages``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:183 +msgid "" +"Set ``packages`` to a list of all :term:`packages ` in your " +"project, including their subpackages, sub-subpackages, etc. Although the " +"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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:192 +msgid "``py_modules``" +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:204 +msgid "``install_requires``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:210 +msgid "" +"\"install_requires\" should be used to specify what dependencies a project " +"minimally needs to run. When the project is installed by :ref:`pip`, this is " +"the specification that is used to install its dependencies." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:214 +msgid "" +"For more on using \"install_requires\" see :ref:`install_requires vs " +"Requirements files`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:221 +msgid "``package_data``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:230 +msgid "" +"Often, additional files need to be installed into a :term:`package `. These files are often data that’s closely related to the " +"package’s implementation, or text files containing documentation that might " +"be of interest to programmers using the package. These files are called " +"\"package data\"." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:235 +msgid "" +"The value must be a mapping from package name to a list of relative path " +"names that should be copied into the package. The paths are interpreted as " +"relative to the directory containing the package." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:239 +msgid "" +"For more information, see :std:doc:`Including Data Files " +"` from the :std:doc:`setuptools docs " +"`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:247 +msgid "``data_files``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:253 +msgid "" +"Although configuring :ref:`Package Data` is sufficient for most needs, in " +"some cases you may need to place data files *outside* of " +"your :term:`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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:269 +msgid "" +"For more information see the distutils section on :ref:`Installing " +"Additional Files `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst: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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:281 +#: ../source/specifications/pyproject-toml.rst:151 +msgid "``scripts``" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:283 +msgid "" +"Although ``setup()`` supports a :ref:`scripts ` keyword for pointing to pre-made scripts to install, " +"the recommended approach to achieve cross-platform compatibility is to " +"use :ref:`console_scripts` entry points (see below)." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:291 +msgid "Choosing a versioning scheme" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:298 +msgid "Working in \"development mode\"" +msgstr "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:306 +msgid "" +"To install a Python package in \"editable\"/\"development\" mode Change " +"directory to the root of the project directory and run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:314 +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." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:338 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:342 +msgid "" +"Lastly, if you don't want to install any dependencies at all, you can run:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:349 +msgid "" +"For more information, see the :doc:`Development Mode ` section of the :ref:`setuptools` docs." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:356 +msgid "Packaging your project" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:358 +msgid "" +"To have your project installable from a :term:`Package Index` " +"like :term:`PyPI `, you'll need to create " +"a :term:`Distribution ` (aka \":term:`Package " +"`\") for your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:363 +msgid "" +"Before you can build wheels and sdists for your project, you'll need to " +"install the ``build`` package:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:380 +msgid "Source distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:382 +msgid "" +"Minimally, you should create a :term:`Source Distribution `:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:398 +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`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:406 +msgid "Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:408 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:413 +msgid "" +"If your project is pure Python then you'll be creating a :ref:`\"Pure Python " +"Wheel\" (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:416 +msgid "" +"If your project contains compiled extensions, then you'll be creating what's " +"called a :ref:`*Platform Wheel* (see section below) `." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:419 +msgid "" +"If your project also supports Python 2 *and* contains no C extensions, then " +"you should create what's called a *Universal Wheel* by adding the following " +"to your :file:`setup.cfg` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:428 +msgid "" +"Only use this setting if your project does not have any C extensions *and* " +"supports Python 2 and 3." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:435 +msgid "Pure Python Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:437 +msgid "" +"*Pure Python Wheels* contain no compiled extensions, and therefore only " +"require a single Python wheel." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:440 +#: ../source/guides/distributing-packages-using-setuptools.rst:469 +msgid "To build the wheel:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:454 +msgid "" +"The ``wheel`` package will detect that the code is pure Python, and build a " +"wheel that's named such that it's usable on any Python 3 installation. For " +"details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:458 +msgid "" +"If you run ``build`` without ``--wheel`` or ``--sdist``, it will build both " +"files for you; this is useful when you don't need multiple wheels." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:464 +msgid "Platform Wheels" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:466 +msgid "" +"*Platform Wheels* are wheels that are specific to a certain platform like " +"Linux, macOS, or Windows, usually due to containing compiled extensions." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:484 +msgid "" +"The ``wheel`` package will detect that the code is not pure Python, and " +"build a wheel that's named such that it's only usable on the platform that " +"it was built on. For details on the naming of wheel files, see :pep:`425`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:490 +msgid "" +":term:`PyPI ` currently supports uploads of " +"platform wheels for Windows, macOS, and the multi-distro ``manylinux*`` ABI. " +"Details of the latter are defined in :pep:`513`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:498 +msgid "Uploading your Project to PyPI" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:500 +msgid "" +"When you ran the command to create your distribution, a new directory ``dist/" +"`` was created under your project's root directory. That's where you'll find " +"your distribution file(s) to upload." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:504 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:509 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:514 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:520 +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:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:533 +msgid "Create an account" +msgstr "建立帳戶" + +#: ../source/guides/distributing-packages-using-setuptools.rst:535 +msgid "" +"First, you need a :term:`PyPI ` user account. " +"You can create an account `using the form on the PyPI website `_." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:539 +msgid "" +"Now you'll create a PyPI `API token`_ so you will be able to securely upload " +"your project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:542 +msgid "" +"Go to https://pypi.org/manage/account/#api-tokens and create a new `API " +"token`_; don't limit its scope to a particular project, since you are " +"creating a new project." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:546 +msgid "" +"**Don't close the page until you have copied and saved the token — you won't " +"see that token again.**" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:549 +msgid "" +"To avoid having to copy and paste the token every time you upload, you can " +"create a :file:`$HOME/.pypirc` file:" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:558 +msgid "**Be aware that this stores your token in plaintext.**" +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 +msgid "" +"For more details, see the :ref:`specification ` for :file:`.pypirc`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:566 +msgid "Upload your distributions" +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:568 +msgid "" +"Once you have an account you can upload your distributions to :term:`PyPI " +"` using :ref:`twine`." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:571 +msgid "" +"The process for uploading a release is the same regardless of whether or not " +"the project already exists on PyPI - if it doesn't exist yet, it will be " +"automatically created when the first release is uploaded." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:575 +msgid "" +"For the second and subsequent releases, PyPI only requires that the version " +"number of the new release differ from any previous releases." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:582 +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." +msgstr "" + +#: ../source/guides/distributing-packages-using-setuptools.rst:589 +#: ../source/tutorials/installing-packages.rst:670 +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 `_." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:5 +msgid "Dropping support for older Python versions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:7 +msgid "" +"The ability to drop support for older Python versions is enabled by the " +"standard :ref:`core-metadata` 1.2 specification via the :ref:`\"Requires-" +"Python\" ` attribute." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:9 +msgid "" +"Metadata 1.2+ installers, such as Pip, 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 "" + +#: ../source/guides/dropping-older-python-versions.rst:12 +msgid "" +"This mechanism can be used to drop support for older Python versions, by " +"amending the ``Requires-Python`` attribute in the package metadata." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:15 +msgid "Requirements" +msgstr "要求" + +#: ../source/guides/dropping-older-python-versions.rst:17 +msgid "" +"This workflow requires that the user installing the package uses Pip [#]_, " +"or another installer that supports the Metadata 1.2 specification." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:20 +msgid "Dealing with the universal wheels" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:22 +msgid "" +"Traditionally, :ref:`setuptools` 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``." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:29 +msgid "" +"If you use this method, either remove this option or section, or explicitly " +"set ``universal`` to ``0``:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:41 +msgid "" +"Regarding :ref:`deprecated ` direct ``setup.py`` " +"invocations, passing the ``--universal`` flag on the command line could " +"override this setting." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:45 +msgid "Defining the Python version required" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:48 +#, fuzzy +#| msgid "Translations" +msgid "1. Install twine" +msgstr "翻譯" + +#: ../source/guides/dropping-older-python-versions.rst:50 +msgid "Ensure that you have twine available at its latest version. Steps:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:66 +msgid "2. Specify the version ranges for supported Python distributions" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:68 +msgid "" +"Set the version ranges declaring which Python distributions are supported " +"within your project's :file:`pyproject.toml`. The :ref:`requires-python` " +"configuration field corresponds to the :ref:`Requires-Python ` core metadata field:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:80 +msgid "" +"You can specify version ranges and exclusion rules (complying with " +"the :ref:`version-specifiers` specification), such as at least Python 3.9. " +"Or, at least Python 3.7 and beyond, skipping the 3.7.0 and 3.7.1 point " +"releases:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:89 +msgid "" +"If using the :ref:`setuptools` build backend, consult the `dependency-" +"management`_ documentation for more options." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:92 +msgid "" +"Avoid adding upper bounds to the version ranges, e. g. ``\">= 3.8, < " +"3.10\"``. Doing so can cause different errors and version conflicts. See the " +"`discourse-discussion`_ for more information." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:96 +msgid "3. Validating the Metadata before publishing" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:98 +msgid "" +"Within a Python source package (the zip or the tar-gz file you download) is " +"a text file called PKG-INFO." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:100 +msgid "" +"This file is generated by the :term:`build backend ` when it " +"generates the source package. The file contains a set of keys and values, " +"the list of keys is part of the PyPA standard metadata format." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:103 +msgid "You can see the contents of the generated file like this:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:109 +msgid "Validate that the following is in place, before publishing the package:" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:111 +msgid "" +"If you have upgraded correctly, the ``Metadata-Version`` value should be 1.2 " +"or higher." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:112 +msgid "" +"The ``Requires-Python`` field is set and matches your specification in the " +"configuration file." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:115 +msgid "4. Publishing the package" +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:117 +msgid "Proceed as suggested in :ref:`Uploading your Project to PyPI`." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:120 +#, fuzzy +#| msgid "Python version" +msgid "Dropping a Python version" +msgstr "Python 版本" + +#: ../source/guides/dropping-older-python-versions.rst:122 +msgid "" +"In principle, at least metadata support for Python versions should be kept " +"as long as possible, because once that has been dropped, people still " +"depending on a version will be forced to downgrade. If however supporting a " +"specific version becomes a blocker for a new feature or other issues occur, " +"the metadata ``Requires-Python`` should be amended. Of course this also " +"depends on whether the project needs to be stable and well-covered for a " +"wider range of users." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:128 +msgid "Each version compatibility change should have its own release." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:132 +msgid "" +"When dropping a Python version, it might also be rewarding to upgrade the " +"project's code syntax generally, apart from updating the versions used in " +"visible places (like the testing environment). Tools like pyupgrade_ or " +"`ruff `_ can automate some of this work." +msgstr "" + +#: ../source/guides/dropping-older-python-versions.rst:138 +msgid "Support for the Metadata 1.2 specification has been added in Pip 9.0." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:5 +msgid "Hosting your own simple repository" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:8 +msgid "" +"If you wish to host your own simple repository [1]_, you can either use a " +"software package like :doc:`devpi ` or you can simply create " +"the proper directory structure and use any web server that can serve static " +"files and generate an autoindex." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:13 +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:" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:35 +msgid "\"Manual\" repository" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 +#, fuzzy +#| msgid "Package Index" +msgid "Package upload" +msgstr "套件索引" + +#: ../source/guides/hosting-your-own-index.rst:64 +msgid "PyPI fall-through [2]_" +msgstr "" + +#: ../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/hosting-your-own-index.rst:70 +msgid "" +"multiple indexes with inheritance, with syncing, replication, fail-over; " +"mirroring" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:73 +#: ../source/guides/index-mirrors-and-caches.rst:71 +msgid ":ref:`simpleindex`" +msgstr ":ref:`simpleindex`" + +#: ../source/guides/hosting-your-own-index.rst:78 +msgid ":ref:`pypiserver`" +msgstr ":ref:`pypiserver`" + +#: ../source/guides/hosting-your-own-index.rst:83 +#, fuzzy +#| msgid ":ref:`pip`" +msgid ":ref:`pypiprivate`" +msgstr ":ref:`pip`" + +#: ../source/guides/hosting-your-own-index.rst:88 +#: ../source/guides/index-mirrors-and-caches.rst:77 +msgid ":ref:`pypicloud`" +msgstr ":ref:`pypicloud`" + +#: ../source/guides/hosting-your-own-index.rst:91 +msgid "unmaintained; also cached proxying; authentication, authorisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:93 +msgid ":ref:`pywharf`" +msgstr ":ref:`pywharf`" + +#: ../source/guides/hosting-your-own-index.rst:96 +msgid "unmaintained; serve files in GitHub" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:98 +#: ../source/guides/index-mirrors-and-caches.rst:83 +msgid ":ref:`pulppython`" +msgstr ":ref:`pulppython`" + +#: ../source/guides/hosting-your-own-index.rst:101 +msgid "also mirroring, proxying; plugin for Pulp" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:103 +#, fuzzy +#| msgid ":ref:`pip`" +msgid ":ref:`pip2pi`" +msgstr ":ref:`pip`" + +#: ../source/guides/hosting-your-own-index.rst:106 +msgid "also mirroring; manual synchronisation" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:108 +msgid ":ref:`dumb-pypi`" +msgstr ":ref:`dumb-pypi`" + +#: ../source/guides/hosting-your-own-index.rst:111 +msgid "not a server, but a static file site generator" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:113 +msgid ":ref:`httpserver`" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:116 +msgid "standard-library" +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:118 +#: ../source/guides/index-mirrors-and-caches.rst:107 +#, fuzzy +#| msgid "`Poetry `_" +msgid "`Apache `_" +msgstr "`Poetry `_" + +#: ../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 "" + +#: ../source/guides/hosting-your-own-index.rst:131 +msgid "" +"For complete documentation of the simple repository protocol, " +"see :ref:`simple repository API `." +msgstr "" + +#: ../source/guides/hosting-your-own-index.rst:134 +msgid "" +"Can be configured to fall back to PyPI (or another package index) if a " +"requested package is missing." +msgstr "" + +#: ../source/guides/index.rst:4 +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`." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:5 +msgid "Package index mirrors and caches" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:8 +#, fuzzy +#| msgid "2017-12-01" +msgid "2023-11-08" +msgstr "2017-12-01" + +#: ../source/guides/index-mirrors-and-caches.rst:10 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:15 +msgid "There are multiple classes of options in this area:" +msgstr "" + +#: ../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 "" +"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/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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:31 +msgid "" +"pip provides a number of facilities for speeding up installation by using " +"local cached copies of :term:`packages `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:34 +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." +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:37 +msgid "" +"A variation on the above which pre-builds the installation files for the " +"requirements using :ref:`python3 -m pip wheel `:" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:53 +msgid "Cache" +msgstr "" + +#: ../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 "" +"multiple indexes with inheritance; syncing, replication, fail-over; package " +"upload" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:65 +msgid ":ref:`bandersnatch`" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:75 +msgid "custom plugin enables caching; re-routing to other package indexes" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:81 +msgid "unmaintained; authentication, authorisation" +msgstr "" + +#: ../source/guides/index-mirrors-and-caches.rst:87 +msgid "plugin for Pulp; multiple proxied indexes; package upload" +msgstr "" + +#: ../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 "" + +#: ../source/guides/index-mirrors-and-caches.rst:101 +#, fuzzy +#| msgid ":ref:`pip`" +msgid ":ref:`flaskpypiproxy`" +msgstr ":ref:`pip`" + +#: ../source/guides/index-mirrors-and-caches.rst:105 +#, fuzzy +#| msgid "Maintainer" +msgid "unmaintained" +msgstr "維護者" + +#: ../source/guides/installing-scientific-packages.rst:5 +msgid "Installing scientific packages" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:8 +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." +msgstr "" + +#: ../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 vectorized " +"instructions available in modern CPUs." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:19 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:26 +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)." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:32 +msgid "Building from source" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:34 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:42 +msgid "Linux distribution packages" +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 "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:54 +msgid "Windows installers" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:56 +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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:61 +msgid "" +"The extensions provided in these installers are typically compatible with " +"the CPython Windows installers published on python.org." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:64 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:77 +msgid "macOS installers and package managers" +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 "" + +#: ../source/guides/installing-scientific-packages.rst:83 +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 `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:89 +msgid "SciPy distributions" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:91 +msgid "" +"The SciPy site lists `several distributions `_ " +"that provide the full SciPy stack to end users in an easy to use and update " +"format." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:96 +msgid "" +"Some of these distributions may not be compatible with the standard ``pip`` " +"and ``virtualenv`` based toolchain." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:100 +#: ../source/key_projects.rst:812 +msgid "Spack" +msgstr "Spack" + +#: ../source/guides/installing-scientific-packages.rst:101 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-scientific-packages.rst:119 +msgid "The conda cross-platform package manager" +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:121 +msgid "" +"``conda`` is an open source (BSD licensed) package management system and " +"environment management system 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." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:133 +msgid "" +"Anaconda `Anaconda `_ is a Python " +"distribution published by Anaconda, Inc. It is a stable collection of Open " +"Source packages for big data and scientific use, and a collection of " +"Graphical Interface utilities for managing conda environments." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:135 +msgid "" +"In addition to the full distribution provided by Anaconda, the conda package " +"manager itself is available in `miniconda `_, `miniforge `_, and " +"`pixi `_." +msgstr "" + +#: ../source/guides/installing-scientific-packages.rst:138 +msgid "" +"Conda packages are available on multiple channels on Anaconda.org, including " +"the default channel supported by Anaconda, Inc, the community supported " +"conda-forge channel, which provides a wide variety of pre-built packages, " +"and some domain-specific package collections." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:4 +msgid "Installing stand alone command line tools" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:6 +msgid "" +"Many packages provide command line applications. Examples of such packages " +"are `mypy `_, `flake8 `_, `black `_, and :ref:`pipenv`." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:12 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:17 +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." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:23 +msgid "pipx only works with Python 3.6+." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:25 +msgid "pipx is installed with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:43 +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 "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:46 +msgid "" +"Now you can install packages with ``pipx install`` and run the package's " +"applications(s) from anywhere." +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:54 +#: ../source/specifications/entry-points.rst:114 +msgid "For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:76 +msgid "" +"To see a list of packages installed with pipx and which applications are " +"available, use ``pipx list``:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:100 +msgid "To upgrade or uninstall a package:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:107 +msgid "pipx can be upgraded or uninstalled with pip:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:123 +msgid "" +"pipx also allows you to install and run the latest version of an application " +"in a temporary, ephemeral environment. For example:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:130 +msgid "To see the full list of commands pipx offers, run:" +msgstr "" + +#: ../source/guides/installing-stand-alone-command-line-tools.rst:136 +msgid "You can learn more about pipx at https://pipx.pypa.io/." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:5 +msgid "Installing pip/setuptools/wheel with Linux Package Managers" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:8 +msgid "2021-07-26" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:10 +msgid "" +"This section covers how to install :ref:`pip`, :ref:`setuptools`, " +"and :ref:`wheel` using Linux package managers." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:13 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:17 +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." +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/installing-using-linux-tools.rst:31 +msgid "Fedora" +msgstr "Fedora" + +#: ../source/guides/installing-using-linux-tools.rst:37 +msgid "" +"To learn more about Python in Fedora, please visit the `official Fedora " +"docs`_, `Python Classroom`_ or `Fedora Loves Python`_." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:45 +msgid "CentOS/RHEL" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:47 +msgid "" +"CentOS and RHEL don't offer :ref:`pip` or :ref:`wheel` in their core " +"repositories, although :ref:`setuptools` is installed by default." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:50 +msgid "To install pip and wheel for the system Python, there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:52 +msgid "" +"Enable the `EPEL repository `_ using " +"`these instructions `__. On EPEL 7, you can install pip and wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:61 +msgid "" +"Since EPEL only offers extra, non-conflicting packages, EPEL does not offer " +"setuptools, since it's in the core repository." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:65 +msgid "" +"Enable the `PyPA Copr Repo `_ using `these instructions `__ [1]_. You can install pip and " +"wheel like so:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:74 +msgid "To additionally upgrade setuptools, run:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:81 +msgid "" +"To install pip, wheel, and setuptools, in a parallel, non-system environment " +"(using yum) then there are two options:" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:85 +msgid "" +"Use the \"Software Collections\" feature to enable a parallel collection " +"that includes pip, setuptools, and wheel." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:88 +msgid "" +"For Redhat, see here: https://developers.redhat.com/products/" +"softwarecollections/overview" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:90 +msgid "For CentOS, see here: https://github.com/sclorg" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:92 +msgid "Be aware that collections may not contain the most recent versions." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:94 +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." +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:100 +msgid "For example, for Python 3.4 on CentOS7/RHEL7:" +msgstr "" + +#: ../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 "" + +#: ../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 "" +"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 "" + +#: ../source/guides/installing-using-linux-tools.rst:135 +msgid "Arch Linux" +msgstr "" + +#: ../source/guides/installing-using-linux-tools.rst:143 +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." +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/installing-using-pip-and-virtual-environments.rst:4 +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:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:10 +msgid "Install packages into a virtual environment using the ``pip`` command" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:11 +msgid "Use and create a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:14 +msgid "" +"This guide applies to supported versions of Python, currently 3.8 and higher." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:18 +msgid "" +"This guide uses the term **package** to refer to a :term:`Distribution " +"Package`, which commonly is installed from an external host. This differs " +"from the term :term:`Import Package` which refers to import modules in your " +"Python source code." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:25 +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." +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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/installing-using-pip-and-virtual-environments.rst:48 +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``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:64 +msgid "" +"The second argument is the location to create the virtual environment. " +"Generally, you can just create this in your project and call it ``.venv``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:67 +msgid "" +"``venv`` will create a virtual Python installation in the ``.venv`` folder." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:69 +msgid "" +"You should exclude your virtual environment directory from your version " +"control system using ``.gitignore`` or similar." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:74 +msgid "Activate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:76 +msgid "" +"Before you can start installing or using packages in your virtual " +"environment you'll need to ``activate`` it. Activating a virtual environment " +"will put the virtual environment-specific ``python`` and ``pip`` executables " +"into your shell's ``PATH``." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:93 +msgid "" +"To confirm the virtual environment is activated, check the location of your " +"Python interpreter:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:108 +msgid "" +"While the virtual environment is active, the above command will output a " +"filepath that includes the ``.venv`` directory, by ending with the following:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:124 +msgid "" +"While a virtual environment is activated, pip will install packages into " +"that specific environment. This enables you to import and use packages in " +"your Python application." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:130 +msgid "Deactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:132 +msgid "" +"If you want to switch projects or leave your virtual environment, " +"``deactivate`` the environment:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:140 +msgid "" +"Closing your shell will deactivate the virtual environment. If you open a " +"new shell window and want to use the virtual environment, reactivate it." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:145 +msgid "Reactivate a virtual environment" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:147 +msgid "" +"If you want to reactivate an existing virtual environment, follow the same " +"instructions about activating a virtual environment. There's no need to " +"create a new virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:155 +msgid "" +":ref:`pip` is the reference Python package manager. It's used to install and " +"update packages into a virtual environment." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:161 +msgid "" +"The Python installers for macOS include pip. On Linux, you may have to " +"install an additional package such as ``python3-pip``. You can make sure " +"that pip is up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:170 +msgid "" +"Afterwards, you should have the latest version of pip installed in your user " +"site:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:179 +msgid "" +"The Python installers for Windows include pip. You can make sure that pip is " +"up-to-date by running:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:187 +msgid "Afterwards, you should have the latest version of pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:195 +msgid "Install packages using pip" +msgstr "使用 pip 安裝程式包" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:197 +msgid "" +"When your virtual environment is activated, you can install packages. Use " +"the ``pip install`` command to install packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:201 +#, fuzzy +#| msgid "Installing packages" +msgid "Install a package" +msgstr "安裝軟體套件" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:203 +msgid "" +"For example, let's install the `Requests`_ library from the :term:`Python " +"Package Index (PyPI)`:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:218 +msgid "" +"pip should download requests and all of its dependencies and install them:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:239 +#, fuzzy +#| msgid "Installing packages" +msgid "Install a specific package version" +msgstr "安裝軟體套件" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:241 +msgid "" +"pip allows you to specify which version of a package to install " +"using :term:`version specifiers `. For example, to " +"install a specific version of ``requests``:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:257 +msgid "To install the latest ``2.x`` release of requests:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:271 +msgid "To install pre-release versions of packages, use the ``--pre`` flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:287 +#, fuzzy +msgid "Install extras" +msgstr "安裝軟體套件" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:289 +msgid "" +"Some packages have optional `extras`_. You can tell pip to install these by " +"specifying the extra in brackets:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:309 +#, fuzzy +#| msgid "Installing packages" +msgid "Install a package from source" +msgstr "安裝軟體套件" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:311 +msgid "" +"pip can install a package directly from its source code. For example, to " +"install the source code in the ``google-auth`` directory:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:328 +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:" +msgstr "" + +#: ../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 "" +"pip can install packages directly from their version control system. For " +"example, you can install directly from a git repository:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:356 +msgid "" +"For more information on supported version control systems and syntax, see " +"pip's documentation on :ref:`VCS Support `." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:361 +msgid "Install from local archives" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:363 +msgid "" +"If you have a local copy of a :term:`Distribution Package`'s archive (a zip, " +"wheel, or tar file) you can install it directly with pip:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:378 +msgid "" +"If you have a directory containing archives of multiple packages, you can " +"tell pip to look for packages there and not to use the :term:`Python Package " +"Index (PyPI)` at all:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:394 +msgid "" +"This is useful if you are installing packages on a system with limited " +"connectivity or if you want to strictly control the origin of distribution " +"packages." +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:400 +#, fuzzy +#| msgid "Installing packages" +msgid "Install from other package indexes" +msgstr "安裝軟體套件" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:402 +msgid "" +"If you want to download packages from a different index than " +"the :term:`Python Package Index (PyPI)`, you can use the ``--index-url`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:417 +msgid "" +"If you want to allow packages from both the :term:`Python Package Index " +"(PyPI)` and a separate index, you can use the ``--extra-index-url`` flag " +"instead:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:434 +#: ../source/tutorials/installing-packages.rst:393 +msgid "Upgrading packages" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:436 +msgid "" +"pip can upgrade packages in-place using the ``--upgrade`` flag. For example, " +"to install the latest version of ``requests`` and all of its dependencies:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:452 +msgid "Using a requirements file" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:454 +msgid "" +"Instead of installing packages individually, pip allows you to declare all " +"dependencies in a :ref:`Requirements File `. For " +"example you could create a :file:`requirements.txt` file containing:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:463 +msgid "" +"And tell pip to install all of the packages in this file using the ``-r`` " +"flag:" +msgstr "" + +#: ../source/guides/installing-using-pip-and-virtual-environments.rst:478 +msgid "Freezing dependencies" +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:" +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/installing-using-pip-and-virtual-environments.rst:511 +msgid "" +"The ``pip freeze`` command is useful for creating :ref:`pip:Requirements " +"Files` that can re-create the exact versions of all packages installed in an " +"environment." +msgstr "" + +#: ../source/guides/installing-using-virtualenv.rst:2 +msgid "Installing packages using virtualenv" +msgstr "使用 virtualenv 安裝程式包" + +#: ../source/guides/installing-using-virtualenv.rst:4 +msgid "" +"This guide discusses how to install packages using :ref:`pip` " +"and :ref:`virtualenv`, a tool to create isolated Python environments." +msgstr "" + +#: ../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 "" + +#: ../source/guides/installing-using-virtualenv.rst:13 +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." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:6 +msgid "Licensing examples and user scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:9 +msgid "" +":pep:`639` has specified the way to declare a :term:`Distribution Archive`'s " +"license and paths to license files and other legally required information. " +"This document aims to provide clear guidance how to migrate from the legacy " +"to the standardized way of declaring licenses. Make sure your preferred " +"build backend supports :pep:`639` before trying to apply the newer " +"guidelines." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:18 +#, fuzzy +#| msgid "Examples" +msgid "Licensing Examples" +msgstr "例子" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:23 +msgid "Basic example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:25 +msgid "" +"The Setuptools project itself, as of `version 75.6.0 `__, " +"does not use the ``License`` field in its own project source metadata. " +"Further, it no longer explicitly specifies ``license_file``/" +"``license_files`` as it did previously, since Setuptools relies on its own " +"automatic inclusion of license-related files matching common patterns, such " +"as the :file:`LICENSE` file it uses." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:32 +msgid "" +"It includes the following license-related metadata in " +"its :file:`pyproject.toml`:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:42 +msgid "The simplest migration to PEP 639 would consist of using this instead:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:49 +msgid "Or, if the project used :file:`setup.cfg`, in its ``[metadata]`` table:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:56 +msgid "" +"The output Core Metadata for the :term:`Distribution Package` would then be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:63 +msgid "" +"The :file:`LICENSE` file would be stored at :file:`/setuptools-{VERSION}/" +"LICENSE` in the sdist and :file:`/setuptools-{VERSION}.dist-info/licenses/" +"LICENSE` in the wheel, and unpacked from there into the site directory " +"(e.g. :file:`site-packages/`) on installation; :file:`/` is the root of the " +"respective archive and ``{VERSION}`` the version of the Setuptools release " +"in the Core Metadata." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:74 +msgid "Advanced example" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:76 +msgid "" +"Suppose Setuptools were to include the licenses of the third-party projects " +"that are vendored in the :file:`setuptools/_vendor/` " +"and :file:`pkg_resources/_vendor/` directories; specifically:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:87 +msgid "The appropriate license expressions are:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:96 +msgid "" +"A comprehensive license expression covering both Setuptools proper and its " +"vendored dependencies would contain these metadata, combining all the " +"license expressions into one. Such an expression might be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:104 +msgid "" +"In addition, per the requirements of the licenses, the relevant license " +"files must be included in the package. Suppose the :file:`LICENSE` file " +"contains the text of the MIT license and the copyrights used by Setuptools, " +"``pyparsing``, ``more_itertools`` and ``ordered-set``; and " +"the :file:`LICENSE*` files in the :file:`setuptools/_vendor/packaging/` " +"directory contain the Apache 2.0 and 2-clause BSD license text, and the " +"Packaging copyright statement and `license choice notice " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:112 +msgid "" +"Specifically, we assume the license files are located at the following paths " +"in the project source tree (relative to the project root " +"and :file:`pyproject.toml`):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:123 +msgid "Putting it all together, our :file:`pyproject.toml` would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:134 +msgid "" +"Or alternatively, the license files can be specified explicitly (paths will " +"be interpreted as glob patterns):" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:148 +msgid "If our project used :file:`setup.cfg`, we could define this in :" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:160 +msgid "" +"With either approach, the output Core Metadata in the distribution would be:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:171 +msgid "" +"In the resulting sdist, with :file:`/` as the root of the archive and " +"``{VERSION}`` the version of the Setuptools release specified in the Core " +"Metadata, the license files would be located at the paths:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:182 +msgid "" +"In the built wheel, with :file:`/` being the root of the archive and " +"``{VERSION}`` as the previous, the license files would be stored at:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:192 +msgid "" +"Finally, in the installed project, with :file:`site-packages/` being the " +"site dir and ``{VERSION}`` as the previous, the license files would be " +"installed to:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:204 +msgid "Expression examples" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:206 +msgid "Some additional examples of valid ``License-Expression`` values:" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:221 +msgid "User Scenarios" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:223 +msgid "" +"The following covers the range of common use cases from a user perspective, " +"providing guidance for each. Do note that the following should **not** be " +"considered legal advice, and readers should consult a licensed legal " +"practitioner in their jurisdiction if they are unsure about the specifics " +"for their situation." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:231 +msgid "I have a private package that won't be distributed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:233 +msgid "" +"If your package isn't shared publicly, i.e. outside your company, " +"organization or household, it *usually* isn't strictly necessary to include " +"a formal license, so you wouldn't necessarily have to do anything extra here." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:237 +msgid "" +"However, it is still a good idea to include ``LicenseRef-Proprietary`` as a " +"license expression in your package configuration, and/or a copyright " +"statement and any legal notices in a :file:`LICENSE.txt` file in the root of " +"your project directory, which will be automatically included by packaging " +"tools." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:245 +msgid "I just want to share my own work without legal restrictions" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:247 +msgid "" +"While you aren't required to include a license, if you don't, no one has " +"`any permission to download, use or improve your work " +"`__, so that's probably the *opposite* of what you " +"actually want. The `MIT license `__ is a great choice " +"instead, as it's simple, widely used and allows anyone to do whatever they " +"want with your work (other than sue you, which you probably also don't want)." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:254 +msgid "" +"To apply it, just paste `the text `__ into a file " +"named :file:`LICENSE.txt` at the root of your repo, and add the year and " +"your name to the copyright line. Then, just add ``license = \"MIT\"`` under " +"``[project]`` in your :file:`pyproject.toml` if your packaging tool supports " +"it, or in its config file/section. You're done!" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:262 +msgid "I want to distribute my project under a specific license" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:264 +msgid "" +"To use a particular license, simply paste its text into " +"a :file:`LICENSE.txt` file at the root of your repo, if you don't have it in " +"a file starting with :file:`LICENSE` or :file:`COPYING` already, and add " +"``license = \"LICENSE-ID\"`` under ``[project]`` in " +"your :file:`pyproject.toml` if your packaging tool supports it, or else in " +"its config file. You can find the ``LICENSE-ID`` and copyable license text " +"on sites like `ChooseALicense `__ or `SPDX " +"`__." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:273 +msgid "" +"Many popular code hosts, project templates and packaging tools can add the " +"license file for you, and may support the expression as well in the future." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:278 +msgid "I maintain an existing package that's already licensed" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:280 +msgid "" +"If you already have license files and metadata in your project, you should " +"only need to make a couple of tweaks to take advantage of the new " +"functionality." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:284 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table in :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers. Your existing ``license`` value may already " +"be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc); " +"otherwise, check the `SPDX license list `__ for the identifier " +"that matches the license used." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:293 +msgid "" +"Make sure to list your license files under ``license-files`` under " +"``[project]`` in :file:`pyproject.toml` or else in your tool's configuration " +"file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:297 +msgid "" +"See the :ref:`licensing-example-basic` for a simple but complete real-world " +"demo of how this works in practice. See also the best-effort guidance on how " +"to translate license classifiers into license expression provided by " +"the :pep:`639` authors: `Mapping License Classifiers to SPDX Identifiers " +"`__. Packaging tools may support automatically " +"converting legacy licensing metadata; check your tool's documentation for " +"more information." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:307 +msgid "My package includes other code under different licenses" +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:309 +msgid "" +"If your project includes code from others covered by different licenses, " +"such as vendored dependencies or files copied from other open source " +"software, you can construct a license expression to describe the licenses " +"involved and the relationship between them." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:315 +msgid "" +"In short, ``License-1 AND License-2`` mean that *both* licenses apply (for " +"example, you included a file under another license), and ``License-1 OR " +"License-2`` means that *either* of the licenses can be used, at the user's " +"option (for example, you want to allow users a choice of multiple licenses). " +"You can use parenthesis (``()``) for grouping to form expressions that cover " +"even the most complex situations." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:322 +msgid "" +"In your project config file, enter your license expression under ``license`` " +"(``[project]`` table of :file:`pyproject.toml`), or the equivalent for your " +"packaging tool, and make sure to remove any legacy ``license`` table subkeys " +"or ``License ::`` classifiers." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:328 +msgid "" +"Also, make sure you add the full license text of all the licenses as files " +"somewhere in your project repository. List the relative path or glob " +"patterns to each of them under ``license-files`` under ``[project]`` " +"in :file:`pyproject.toml` (if your tool supports it), or else in your tool's " +"configuration file." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:334 +msgid "" +"As an example, if your project was licensed MIT but incorporated a vendored " +"dependency (say, ``packaging``) that was licensed under either Apache 2.0 or " +"the 2-clause BSD, your license expression would be ``MIT AND (Apache-2.0 OR " +"BSD-2-Clause)``. You might have a :file:`LICENSE.txt` in your repo root, and " +"a :file:`LICENSE-APACHE.txt` and :file:`LICENSE-BSD.txt` in " +"the :file:`_vendor/` subdirectory, so to include all of them, you'd specify " +"``[\"LICENSE.txt\", \"_vendor/packaging/LICENSE*\"]`` as glob patterns, or " +"``[\"LICENSE.txt\", \"_vendor/LICENSE-APACHE.txt\", \"_vendor/LICENSE-" +"BSD.txt\"]`` as literal file paths." +msgstr "" + +#: ../source/guides/licensing-examples-and-user-scenarios.rst:345 +msgid "" +"See a fully worked out :ref:`licensing-example-advanced` for an end-to-end " +"application of this to a real-world complex project, with many technical " +"details, and consult a `tutorial `__ for more help and " +"examples using SPDX identifiers and expressions." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:2 +msgid "Making a PyPI-friendly README" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:4 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:9 +msgid "Creating a README file" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:11 +msgid "" +"README files for Python projects are often named ``README``, ``README.txt``, " +"``README.rst``, or ``README.md``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:13 +msgid "" +"For your README to display properly on PyPI, choose a markup language " +"supported by PyPI. Formats supported by `PyPI's README renderer `_ are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:16 +msgid "plain text" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:17 +msgid "" +"`reStructuredText `_ (without " +"Sphinx extensions)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:18 +msgid "" +"Markdown (`GitHub Flavored Markdown `_ by " +"default, or `CommonMark `_)" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:21 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:25 +msgid "Including your README in your package's metadata" +msgstr "" + +#: ../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 "" + +#: ../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/making-a-pypi-friendly-readme.rst:36 +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``." +msgstr "" + +#: ../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``." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:45 +msgid "" +"If you're using GitHub-flavored Markdown to write a project's description, " +"ensure you upgrade the following tools:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:60 +msgid "The minimum required versions of the respective tools are:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:62 +msgid "``setuptools >= 38.6.0``" +msgstr "``setuptools >= 38.6.0``" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:63 +msgid "``wheel >= 0.31.0``" +msgstr "``wheel >= 0.31.0``" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:64 +msgid "``twine >= 1.11.0``" +msgstr "``twine >= 1.11.0``" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:66 +msgid "" +"It's recommended that you use ``twine`` to upload the project's distribution " +"packages:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:72 +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:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:94 +msgid "Validating reStructuredText markup" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:96 +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." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:99 +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\".``\"." +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:104 +msgid "" +"You can check your README for markup errors before uploading as follows:" +msgstr "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:106 +msgid "" +"Install the latest version of `twine `_; " +"version 1.12.0 or higher is required:" +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 "" + +#: ../source/guides/making-a-pypi-friendly-readme.rst:124 +msgid "Run ``twine check`` on the sdist and wheel:" +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:6 +msgid "Migrating to PyPI.org" +msgstr "" + +#: ../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 "" +":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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:26 +msgid "" +"The default upload settings switched to ``pypi.org`` in the following " +"versions:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:28 +msgid "``twine`` 1.8.0" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:29 +msgid "``setuptools`` 27.0.0" +msgstr "``setuptools`` 27.0.0" + +#: ../source/guides/migrating-to-pypi-org.rst:30 +msgid "Python 2.7.13 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:31 +msgid "Python 3.4.6 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:32 +msgid "Python 3.5.3 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:33 +msgid "Python 3.6.0 (``distutils`` update)" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:35 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:52 +msgid "" +"Then simply delete the line starting with ``repository`` and you will use " +"your upload tool's default URL." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:55 +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:" +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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:77 +msgid "Registering package names & metadata" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:79 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:83 +msgid "" +"As a result, attempting explicit registration after switching to using " +"PyPI.org for uploads will give the following error message::" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:88 +msgid "" +"The solution is to skip the registration step, and proceed directly to " +"uploading artifacts." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:93 +#: ../source/guides/using-testpypi.rst:5 +msgid "Using TestPyPI" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:95 +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:" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:117 +msgid "Registering new user accounts" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:119 +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." +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:125 +msgid "Browsing packages" +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/migrating-to-pypi-org.rst:139 +msgid "Managing published packages and releases" +msgstr "" + +#: ../source/guides/migrating-to-pypi-org.rst:141 +msgid "" +"``pypi.org`` provides a fully functional interface for logged in users to " +"manage their published packages and releases." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:6 +msgid "How to modernize a ``setup.py`` based project?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:10 +msgid "Should ``pyproject.toml`` be added?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:12 +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`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:16 +msgid "" +"Note that it has influence on the build isolation feature of pip, see below." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:23 +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:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:36 +msgid "``python -m build``" +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:48 +msgid "Where to start?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:50 +msgid "" +"The :term:`project` must contain a :file:`pyproject.toml` file at the root " +"of its source tree that contains a ``[build-system]`` table like so:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:60 +msgid "" +"This is the standardized method of letting :term:`build frontends ` know that :ref:`setuptools` is the :term:`build backend ` for this project." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:63 +msgid "" +"Note that the presence of a :file:`pyproject.toml` file (even if empty) " +"triggers :ref:`pip` to change its default behavior to use *build isolation*." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:68 +msgid ":ref:`distributing-packages`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:69 +#: ../source/guides/modernize-setup-py-project.rst:113 +msgid ":ref:`pyproject-build-system-table`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:70 +#: ../source/guides/modernize-setup-py-project.rst:131 +#: ../source/guides/modernize-setup-py-project.rst:247 +msgid ":doc:`pip:reference/build-system`" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:99 +msgid "" +"requires a :file:`pyproject.toml` file like this (:file:`setup.py` stays " +"unchanged):" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/modernize-setup-py-project.rst:124 +msgid "" +"For some projects this isolation is unwanted and it can be deactivated as " +"follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:126 +msgid "``python -m build --no-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:127 +msgid "``python -m pip install --no-build-isolation``" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:135 +msgid "How to handle packaging metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:137 +msgid "" +"All static metadata can optionally be moved to a ``[project]`` table " +"in :file:`pyproject.toml`." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:151 +msgid "can be entirely replaced by a :file:`pyproject.toml` file like this:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:164 +msgid "" +"Read :ref:`pyproject-project-table` for the full specification of the " +"content allowed in the ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:169 +msgid "How to handle dynamic metadata?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:171 +msgid "" +"If some packaging metadata fields are not static they need to be listed as " +"``dynamic`` in this ``[project]`` table." +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:191 +msgid "can be modernized as follows:" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:223 +msgid ":ref:`declaring-project-metadata-dynamic`" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:227 +msgid "What if something that can not be changed expects a ``setup.py`` file?" +msgstr "" + +#: ../source/guides/modernize-setup-py-project.rst:229 +msgid "" +"For example, a process exists that can not be changed easily and it needs to " +"execute a command such as ``python setup.py --name``." +msgstr "" + +#: ../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 "" + +#: ../source/guides/modernize-setup-py-project.rst:246 +#, fuzzy +#| msgid "Project name" +msgid ":ref:`pyproject-toml-spec`" +msgstr "專案名稱" + +#: ../source/guides/modernize-setup-py-project.rst:248 +msgid ":doc:`setuptools:build_meta`" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:6 +msgid "Multi-version installs" +msgstr "" + +#: ../source/guides/multi-version-installs.rst:11 +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``)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/guides/multi-version-installs.rst:34 +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." +msgstr "" + +#: ../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" + +#: ../source/guides/packaging-binary-extensions.rst:10 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:18 +msgid "An overview of binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:21 +msgid "Use cases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:23 +msgid "" +"The typical use cases for binary extensions break down into just three " +"conventional categories:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:26 +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." +msgstr "" + +#: ../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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:45 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:54 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:59 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:69 +msgid "Disadvantages" +msgstr "缺點" + +#: ../source/guides/packaging-binary-extensions.rst:71 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:78 +msgid "This means that binary extensions:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:80 +msgid "" +"require that end users be able to either build them from source, or else " +"that someone publish pre-built binaries for common platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:83 +msgid "" +"may not be compatible with different builds of the CPython reference " +"interpreter" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:86 +msgid "" +"often will not work correctly with alternative interpreters such as PyPy, " +"IronPython or Jython" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:89 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:94 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:99 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:106 +msgid "Alternatives to handcoded accelerator modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:108 +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:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:113 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:120 +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)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:130 +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++)." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:139 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:148 +msgid "Alternatives to handcoded wrapper modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:150 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:156 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:160 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:171 +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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:188 +msgid "" +"`SWIG `__ is a wrapper interface generator that allows " +"a variety of programming languages, including Python, to interface with C " +"and C++ code." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:192 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:206 +msgid "Alternatives for low level system access" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:208 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:216 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:225 +msgid "Implementing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:227 +msgid "" +"The CPython :doc:`Extending and Embedding ` guide " +"includes an introduction to writing a :doc:`custom extension module in C " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:231 +msgid "" +"FIXME: Elaborate that all this is one of the reasons why you probably " +"*don't* want to handcode your extension modules :)" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:236 +msgid "Extension module lifecycle" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:242 +msgid "Implications of shared static state and subinterpreters" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:248 +msgid "Implications of the GIL" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:254 +msgid "Memory allocation APIs" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:262 +msgid "ABI Compatibility" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:264 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:270 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:277 +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\"." +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-binary-extensions.rst:288 +msgid "Building extensions for multiple platforms" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:290 +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`." +msgstr "" + +#: ../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::" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:302 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:309 +msgid "Binary extensions for Windows" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:318 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:326 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:337 +msgid "Binary extensions for Linux" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:339 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:345 +msgid "Binary extensions for macOS" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:347 +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 `_." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:357 +msgid "Publishing binary extensions" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:359 +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 " +"`." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:365 +msgid "Avoid binary-only releases" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:367 +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." +msgstr "" + +#: ../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 "" +"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/packaging-binary-extensions.rst:388 +msgid "Cross-platform wheel generation with scikit-build" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:390 +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." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:398 +msgid "Introduction to C/C++ extension modules" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:400 +msgid "" +"For a more in depth explanation of how extension modules are used by CPython " +"on a Debian system, see the following articles:" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:403 +msgid "" +"`What are (c)python extension modules? `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:404 +msgid "`Releasing the gil `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:405 +msgid "" +"`Writing cpython extension modules using C++ `_" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:408 +msgid "Additional considerations for binary wheels" +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:410 +msgid "" +"The `pypackaging-native `_ website " +"has additional coverage of packaging Python packages with native code. It " +"aims to provide an overview of the most important packaging issues for such " +"projects, with in-depth explanations and references." +msgstr "" + +#: ../source/guides/packaging-binary-extensions.rst:415 +msgid "" +"Examples of topics covered are non-Python compiled dependencies (\"native " +"dependencies\"), the importance of the ABI (Application Binary Interface) of " +"native code, dependency on SIMD code and cross compilation." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:5 +msgid "Packaging namespace packages" +msgstr "" + +#: ../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 "" + +#: ../source/guides/packaging-namespace-packages.rst:26 +msgid "And you use this package in your code like so::" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:31 +msgid "Then you can break these sub-packages into two separate distributions:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:50 +msgid "Each sub-package can now be separately installed, used, and versioned." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:52 +msgid "" +"Namespace packages can be useful for a large collection of loosely-related " +"packages (such as a large corpus of client libraries for multiple products " +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:62 +msgid "Creating a namespace package" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:64 +msgid "" +"There are currently two different approaches to creating namespace packages, " +"from which the latter is discouraged:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:67 +msgid "" +"Use `native namespace packages`_. This type of namespace package is defined " +"in :pep:`420` and is available in Python 3.3 and later. This is recommended " +"if packages in your namespace only ever need to support Python 3 and " +"installation via ``pip``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:71 +msgid "" +"Use `legacy namespace packages`_. This comprises `pkgutil-style namespace " +"packages`_ and `pkg_resources-style namespace packages`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:75 +msgid "Native namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:77 +msgid "" +"Python 3.3 added **implicit** namespace packages from :pep:`420`. All that " +"is required to create a native namespace package is that you just " +"omit :file:`__init__.py` from the namespace package directory. An example " +"file structure (following :ref:`src-layout `):" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:94 +msgid "" +"It is extremely important that every distribution that uses the namespace " +"package omits the :file:`__init__.py` or uses a pkgutil-" +"style :file:`__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 "" + +#: ../source/guides/packaging-namespace-packages.rst:99 +msgid "" +"The ``src-layout`` directory structure allows automatic discovery of " +"packages by most :term:`build backends `. See :ref:`src-" +"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 "" + +#: ../source/guides/packaging-namespace-packages.rst:117 +msgid "The same can be accomplished with a :file:`setup.cfg`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:129 +msgid "Or :file:`setup.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:142 +msgid "" +":ref:`setuptools` will search the directory structure for implicit namespace " +"packages by default." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:145 +msgid "" +"A complete working example of two native namespace packages can be found in " +"the `native namespace package example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:151 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:158 +msgid "Legacy namespace packages" +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 one of these " +"methods." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:164 +msgid "" +"To migrate an existing package, all packages sharing the namespace must be " +"migrated simultaneously." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:166 +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." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:173 +msgid "pkgutil-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:175 +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 was the recommended approach for the highest level of " +"compatibility." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:180 +msgid "" +"To create a pkgutil-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:194 +#: ../source/guides/packaging-namespace-packages.rst:249 +msgid "" +"The :file:`__init__.py` file for the namespace package needs to contain the " +"following:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:201 +#: ../source/guides/packaging-namespace-packages.rst:256 +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 "" + +#: ../source/guides/packaging-namespace-packages.rst:206 +msgid "" +"A complete working example of two pkgutil-style namespace packages can be " +"found in the `pkgutil namespace example project`_." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:216 +msgid "pkg_resources-style namespace packages" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:220 +msgid "" +"The information in this section is obsolete and is no longer functional (as " +"of Setuptools 82.0.0). It is only retained for historical reference." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:223 +msgid "" +"``pkg_resources`` has been deprecated and was fully removed in Setuptools " +"82.0.0." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:225 +msgid "" +":doc:`Setuptools ` previously provided the " +"``pkg_resources.declare_namespace`` function and the ``namespace_packages`` " +"argument to :func:`~setuptools.setup`. Together these could be used to " +"declare namespace packages. While this approach is no longer supported, it " +"may still be encountered in environments using older ``setuptools`` " +"versions. 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 "" + +#: ../source/guides/packaging-namespace-packages.rst:235 +msgid "" +"To create a pkg_resources-style namespace package, you need to provide " +"an :file:`__init__.py` file for the namespace package:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:261 +msgid "" +"Some older recommendations advise the following in the namespace " +"package :file:`__init__.py`:" +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:271 +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``." +msgstr "" + +#: ../source/guides/packaging-namespace-packages.rst:278 +msgid "" +"Finally, every distribution must provide the ``namespace_packages`` argument " +"to :func:`~setuptools.setup` in :file:`setup.py`. For example:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:5 +msgid "" +"Publishing package distribution releases using GitHub Actions CI/CD workflows" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:7 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:35 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:44 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:54 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:63 +msgid "" +"Now, go to https://test.pypi.org/manage/account/publishing/ and repeat the " +"second step, but this time, enter ``testpypi`` as the name of the GitHub " +"Environment." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:66 +msgid "" +"Your \"pending\" publishers are now ready for their first use and will " +"create your projects automatically once you use them for the first time." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:72 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:85 +msgid "Creating a workflow definition" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:87 +msgid "" +"GitHub CI/CD workflows are declared in YAML files stored in the ``.github/" +"workflows/`` directory of your repository." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:90 +msgid "Let's create a ``.github/workflows/publish-to-pypi.yml`` file." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:93 +msgid "" +"Start it with a meaningful name and define the event that should make GitHub " +"run this workflow:" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:103 +msgid "" +"We will have to define two jobs to publish to PyPI and TestPyPI " +"respectively, and an additional job to build the distribution packages." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:107 +msgid "" +"First, we'll define the job for building the dist packages of your project " +"and storing them for later use:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:115 +msgid "" +"This will download your repository into the CI runner and then install and " +"activate the newest available Python 3 release." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:118 +msgid "" +"And now we can build the dists from source and store them. In this example, " +"we'll use the ``build`` package. So add this to the steps list:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:128 +msgid "Defining a workflow job environment" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:148 +msgid "Publishing the distribution to PyPI" +msgstr "" + +#: ../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/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:157 +msgid "" +"This step uses the `pypa/gh-action-pypi-publish`_ GitHub Action: after the " +"stored distribution package has been downloaded by the `download-artifact`_ " +"action, it uploads the contents of the ``dist/`` folder into PyPI " +"unconditionally." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:164 +msgid "" +"Starting with version `v1.11.0 `_, `pypa/gh-action-pypi-publish`_ generates " +"and uploads :pep:`740`-compatible attestations for each distribution by " +"default. No additional manual signing steps are required." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:172 +msgid "Separate workflow for publishing to TestPyPI" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:174 +msgid "" +"Now, repeat these steps and create another job for publishing to the " +"TestPyPI package index under the ``jobs`` section:" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:184 +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." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:188 +msgid "The whole CI/CD workflow" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:190 +msgid "" +"This paragraph showcases the whole workflow after following the above guide." +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:198 +msgid "That's all, folks!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:200 +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!" +msgstr "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:208 +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 "" + +#: ../source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst:216 +msgid "" +"It is recommended to keep the integrated GitHub Actions at their latest " +"versions, updating them frequently." +msgstr "" + +#: ../source/guides/section-build-and-publish.rst:3 +msgid "Building and Publishing" +msgstr "" + +#: ../source/guides/section-hosting.rst:3 +msgid "Hosting" +msgstr "" + +#: ../source/guides/section-install.rst:3 +#: ../source/specifications/pylock-toml.rst:729 +#, fuzzy +#| msgid "Translations" +msgid "Installation" +msgstr "翻譯" + +#: ../source/guides/single-sourcing-package-version.rst:-1 +msgid "0; url=../../discussions/single-source-version/" +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:6 +msgid "Redirecting stale single-source package version link..." +msgstr "" + +#: ../source/guides/single-sourcing-package-version.rst:8 +msgid "" +"If the page doesn't automatically refresh, see :ref:`single-source-version`." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:7 +msgid "Supporting multiple Python versions" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/supporting-multiple-python-versions.rst:42 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:48 +msgid "Automated testing and continuous integration" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:50 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:55 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:59 +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:" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:65 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:68 +msgid "" +"`Appveyor `_ provides a Windows environment " +"(Windows Server 2012)." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:79 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:84 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:88 +msgid "Tools for single-source Python packages" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:90 +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_." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:99 +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" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:106 +msgid "a Python 2 (by syntax) module in a Python 3 project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:107 +msgid "a Python 3 (by syntax) module in a *Python 2* project." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:109 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:116 +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." +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:123 +msgid "What's in which Python?" +msgstr "" + +#: ../source/guides/supporting-multiple-python-versions.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:5 +msgid "Supporting Windows using Appveyor" +msgstr "" + +#: ../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 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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:19 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:23 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:29 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:37 +msgid "Setting up" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:53 +msgid "Adding Appveyor support to your project" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:55 +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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:68 +msgid "appveyor.yml" +msgstr "appveyor.yml" + +#: ../source/guides/supporting-windows-using-appveyor.rst:74 +msgid "" +"This file can be downloaded from `here `__." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:76 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:79 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:87 +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``)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:93 +msgid "" +"The ``build`` section simply switches off builds - there is no build step " +"needed for Python, unlike languages like ``C#``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:96 +msgid "" +"The main sections that will need to be tailored to your project are " +"``test_script`` and ``after_test``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:99 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:108 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:113 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:118 +msgid "Support script" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:120 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:125 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:132 +msgid "" +"You can simply download the batch file and include it in your project " +"unchanged." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:136 +msgid "Access to the built wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:138 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:149 +msgid "Testing with tox" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:151 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:155 +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)." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:169 +msgid "``DISTUTILS_USE_SDK``" +msgstr "``DISTUTILS_USE_SDK``" + +#: ../source/guides/supporting-windows-using-appveyor.rst:170 +msgid "``MSSdk``" +msgstr "``MSSdk``" + +#: ../source/guides/supporting-windows-using-appveyor.rst:171 +msgid "``INCLUDE``" +msgstr "``INCLUDE``" + +#: ../source/guides/supporting-windows-using-appveyor.rst:172 +msgid "``LIB``" +msgstr "``LIB``" + +#: ../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." +msgstr "" + +#: ../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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:187 +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``." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:191 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:196 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:202 +msgid "Automatically uploading wheels" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:204 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:209 +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)." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:215 +msgid "External dependencies" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:217 +msgid "" +"The supplied scripts will successfully build any distribution that does not " +"rely on 3rd party external libraries for the build." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:220 +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." +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:229 +msgid "Support scripts" +msgstr "" + +#: ../source/guides/supporting-windows-using-appveyor.rst:231 +msgid "For reference, the SDK setup support script is listed here:" +msgstr "" + +#: ../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 "" +"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 "" + +#: ../source/guides/tool-recommendations.rst:20 +msgid "Virtual environments" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:22 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:28 +#, fuzzy +#| msgid "Installing packages" +msgid "Installing packages" +msgstr "安裝軟體套件" + +#: ../source/guides/tool-recommendations.rst:30 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:36 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:43 +msgid "" +"For scientific software specifically, consider :ref:`Conda` or :ref:`Spack`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:45 +msgid "Write a \"pip vs. Conda\" comparison, here or in a new discussion." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:47 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:55 +msgid "Lock files" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:57 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:63 +msgid "Build backends" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:67 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:71 +msgid "" +"Popular :term:`build backends ` for pure-Python packages " +"include, in alphabetical order:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:74 +msgid "" +":doc:`Flit-core ` -- developed with but separate " +"from :ref:`Flit`. A minimal and opinionated build backend. It does not " +"support plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:77 +msgid "" +"Hatchling_ -- developed with but separate from :ref:`Hatch`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:79 +msgid "" +"PDM-backend_ -- developed with but separate from :ref:`PDM`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:81 +msgid "" +"Poetry-core_ -- developed with but separate from :ref:`Poetry`. Supports " +"plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:84 +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)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:88 +msgid "" +":ref:`setuptools`, which used to be the only build backend. Supports plugins." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:92 +msgid "" +"If you use setuptools, please be aware that some features that predate " +"standardisation efforts are now deprecated and only *temporarily kept* for " +"compatibility." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:96 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:103 +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`)." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:108 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:115 +msgid "Build backends for extension modules" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:117 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:121 +msgid "" +":ref:`setuptools` -- natively supports C and C++ (with third-party plugins " +"for Go and Rust)," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:122 +msgid "" +":ref:`meson-python` -- C, C++, Fortran, Rust, and other languages supported " +"by Meson," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:123 +msgid "" +":ref:`scikit-build-core` -- C, C++, Fortran, and other languages supported " +"by CMake," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:124 +msgid ":ref:`maturin` -- Rust, via Cargo." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:128 +#, fuzzy +#| msgid "Reviewing new contributions" +msgid "Building distributions" +msgstr "審查新的貢獻" + +#: ../source/guides/tool-recommendations.rst:130 +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`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:135 +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 `." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:139 +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." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:145 +msgid "Uploading to PyPI" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:147 +msgid "" +"For projects hosted on or published via supported CI/CD platforms, it is " +"recommended to use the :ref:`Trusted Publishing `, which " +"allows the package to be securely uploaded to PyPI from a CI/CD workflow " +"without a manually configured API token." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:152 +msgid "" +"As of November 2024, PyPI supports the following platforms as Trusted " +"Publishing providers:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:155 +msgid "GitHub Actions (on ``https://github.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:156 +msgid "GitLab CI/CD (on ``https://gitlab.com``)" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:157 +msgid "ActiveState" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:158 +msgid "Google Cloud" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:160 +msgid "" +"The other available method is to upload the package manually " +"using :ref:`twine`." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:164 +msgid "" +"**Never** use ``python setup.py upload`` for this task. In addition to " +"being :ref:`deprecated `, it is insecure." +msgstr "" + +#: ../source/guides/tool-recommendations.rst:169 +msgid "Workflow tools" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:171 +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:" +msgstr "" + +#: ../source/guides/tool-recommendations.rst:179 +msgid ":ref:`Flit`," +msgstr ":ref:`Flit`," + +#: ../source/guides/tool-recommendations.rst:180 +msgid ":ref:`Hatch`," +msgstr ":ref:`Hatch`," + +#: ../source/guides/tool-recommendations.rst:181 +msgid ":doc:`nox `," +msgstr "" + +#: ../source/guides/tool-recommendations.rst:182 +msgid ":ref:`PDM`," +msgstr ":ref:`PDM`," + +#: ../source/guides/tool-recommendations.rst:183 +msgid ":ref:`Pipenv`," +msgstr ":ref:`Pipenv`," + +#: ../source/guides/tool-recommendations.rst:184 +msgid ":ref:`Poetry`," +msgstr ":ref:`Poetry`," + +#: ../source/guides/tool-recommendations.rst:185 +msgid ":doc:`tox `." +msgstr "" + +#: ../source/guides/using-manifest-in.rst:5 +msgid "Including files in source distributions with ``MANIFEST.in``" +msgstr "" + +#: ../source/guides/using-manifest-in.rst:7 +msgid "" +"The information on this page has moved to :doc:`setuptools:userguide/" +"miscellaneous` in the setuptools documentation." +msgstr "" + +#: ../source/guides/using-testpypi.rst:7 +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 `_" +msgstr "" + +#: ../source/guides/using-testpypi.rst:13 +msgid "Registering your account" +msgstr "" + +#: ../source/guides/using-testpypi.rst:15 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:19 +msgid "" +"The database for TestPyPI may be periodically pruned, so it is not unusual " +"for user accounts to be deleted." +msgstr "" + +#: ../source/guides/using-testpypi.rst:24 +msgid "Using TestPyPI with Twine" +msgstr "" + +#: ../source/guides/using-testpypi.rst:26 +msgid "" +"You can upload your distributions to TestPyPI using :ref:`twine` by " +"specifying the ``--repository`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:33 +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." +msgstr "" + +#: ../source/guides/using-testpypi.rst:39 +msgid "Using TestPyPI with pip" +msgstr "" + +#: ../source/guides/using-testpypi.rst:41 +msgid "" +"You can tell :ref:`pip` to download packages from TestPyPI instead of PyPI " +"by specifying the ``--index-url`` flag:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:56 +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:" +msgstr "" + +#: ../source/guides/using-testpypi.rst:73 +msgid "Setting up TestPyPI in :file:`.pypirc`" +msgstr "" + +#: ../source/guides/using-testpypi.rst:75 +msgid "" +"If you want to avoid being prompted for your username and password every " +"time, you can configure TestPyPI in your :file:`$HOME/.pypirc`:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:5 +msgid "Writing your ``pyproject.toml``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:7 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:11 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:15 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:18 +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." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:25 +msgid "" +"The ``[build-system]`` table should always be present, regardless of which " +"build backend you use (``[build-system]`` *defines* the build tool you use)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:29 +msgid "" +"On the other hand, the ``[project]`` table is understood by *most* build " +"backends, but some build backends use a different format." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:32 +msgid "" +"A notable exception is Poetry_, which before version 2.0 (released January " +"5, 2025) did not use the ``[project]`` table, it used the ``[tool.poetry]`` " +"table instead. With version 2.0, it supports both. Also, the setuptools_ " +"build backend supports both the ``[project]`` table, and the older format in " +"``setup.cfg`` or ``setup.py``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:38 +msgid "" +"For new projects, 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 "" + +#: ../source/guides/writing-pyproject-toml.rst:47 +msgid "Declaring the build backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:49 +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\"]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:55 +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:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:63 +msgid "Static vs. dynamic metadata" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:65 +msgid "The rest of this guide is devoted to the ``[project]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:67 +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\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:71 +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 "" + +#: ../source/guides/writing-pyproject-toml.rst:82 +msgid "" +"When a field is dynamic, it is the build backend's responsibility to fill " +"it. Consult your build backend's documentation to learn how it does it." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:88 +msgid "Basic information" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:93 +#: ../source/specifications/pyproject-toml.rst:122 +#: ../source/specifications/pyproject-toml.rst:147 +#: ../source/specifications/pyproject-toml.rst:159 +msgid "``name``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:95 +msgid "" +"Put the name of your project on PyPI. This field is required and is the only " +"field that cannot be marked as dynamic." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:103 +msgid "" +"The project name must consist of ASCII letters, digits, underscores " +"\"``_``\", hyphens \"``-``\" and periods \"``.``\". It must not start or end " +"with an underscore, hyphen or period." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:107 +msgid "" +"Comparison of project names is case insensitive and treats arbitrarily long " +"runs of underscores, hyphens, and/or periods as equal. For example, if you " +"register a project named ``cool-stuff``, users will be able to download it " +"or declare a dependency on it using any of the following spellings: ``Cool-" +"Stuff``, ``cool.stuff``, ``COOL_STUFF``, ``CoOl__-.-__sTuFF``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:115 +#: ../source/specifications/pyproject-toml.rst:127 +#: ../source/specifications/pyproject-toml.rst:153 +#: ../source/specifications/pyproject-toml.rst:174 +msgid "``version``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:117 +#, fuzzy +#| msgid "List keywords that describe your project." +msgid "Put the version of your project." +msgstr "列出描述您的項目的關鍵字。" + +#: ../source/guides/writing-pyproject-toml.rst:124 +msgid "" +"Some more complicated version specifiers like ``2020.0.0a1`` (for an alpha " +"release) are possible; see the :ref:`specification ` for " +"full details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:128 +msgid "This field is required, although it is often marked as dynamic using" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:135 +msgid "" +"This allows use cases such as filling the version from a ``__version__`` " +"attribute or a Git tag. Consult the :ref:`single-source-version` discussion " +"for more details." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:141 +msgid "Dependencies and requirements" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:453 +msgid "``dependencies``/``optional-dependencies``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:146 +msgid "If your project has dependencies, list them like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:158 +msgid "" +"See :ref:`Dependency specifiers ` for the full syntax " +"you can use to constrain versions." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:161 +msgid "" +"You may want to make some of your dependencies optional, if they are only " +"needed for a specific feature of your package. In that case, put them in " +"``optional-dependencies``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:174 +msgid "" +"Each of the keys defines a \"packaging extra\". In the example above, one " +"could use, e.g., ``pip install your-project-name[gui]`` to install your " +"project with GUI support, adding the PyQt5 dependency." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:183 +#: ../source/specifications/pylock-toml.rst:95 +#: ../source/specifications/pyproject-toml.rst:150 +#: ../source/specifications/pyproject-toml.rst:243 +msgid "``requires-python``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:185 +msgid "" +"This lets you declare the minimum version of Python that you support " +"[#requires-python-upper-bounds]_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:197 +msgid "Creating executable scripts" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:199 +msgid "" +"To install a command as part of your package, declare it in the " +"``[project.scripts]`` table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:207 +msgid "" +"In this example, after installing your project, a ``spam-cli`` command will " +"be available. Executing this command will do the equivalent of ``import sys; " +"from spam import main_cli; sys.exit(main_cli())``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:211 +msgid "" +"On Windows, scripts packaged this way need a terminal, so if you launch them " +"from within a graphical application, they will make a terminal pop up. To " +"prevent this from happening, use the ``[project.gui-scripts]`` table instead " +"of ``[project.scripts]``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:221 +msgid "" +"In that case, launching your script from the command line will give back " +"control immediately, leaving the script to run in the background." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:224 +msgid "" +"The difference between ``[project.scripts]`` and ``[project.gui-scripts]`` " +"is only relevant on Windows." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:230 +msgid "About your project" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:233 +#: ../source/specifications/pyproject-toml.rst:330 +msgid "``authors``/``maintainers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:235 +msgid "" +"Both of these fields contain lists of people identified by a name and/or an " +"email address." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:255 +#: ../source/specifications/pyproject-toml.rst:137 +#: ../source/specifications/pyproject-toml.rst:189 +msgid "``description``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:257 +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 `_)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:268 +#: ../source/specifications/pyproject-toml.rst:149 +#: ../source/specifications/pyproject-toml.rst:202 +msgid "``readme``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:270 +msgid "" +"This is a longer description of your project, to display on your project " +"page on PyPI. Typically, your project will have a ``README.md`` or " +"``README.rst`` file and you just put its file name here." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:279 +msgid "The README's format is auto-detected from the extension:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:281 +msgid "``README.md`` → `GitHub-flavored Markdown `_," +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:282 +msgid "" +"``README.rst`` → `reStructuredText `_ (without Sphinx extensions)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:284 +msgid "You can also specify the format explicitly, like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:297 +msgid "``license`` and ``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:299 +msgid "As per :pep:`639`, licenses should be declared with two fields:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:301 +msgid "" +"``license`` is an :term:`SPDX license expression ` " +"consisting of one or more :term:`license identifiers `." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:303 +msgid "``license-files`` is a list of license file glob patterns." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:305 +msgid "" +"A previous PEP had specified ``license`` to be a table with a ``file`` or a " +"``text`` key, this format is now deprecated. Most :term:`build " +"backends` now support the new format as shown in the " +"following table." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:309 +msgid "build backend versions that introduced :pep:`639` support" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:312 +msgid "hatchling" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:313 +#, fuzzy +#| msgid "``setuptools`` 27.0.0" +msgid "setuptools" +msgstr "``setuptools`` 27.0.0" + +#: ../source/guides/writing-pyproject-toml.rst:314 +msgid "flit-core [#flit-core-pep639]_" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:315 +msgid "pdm-backend" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:316 +msgid "poetry-core" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:317 +#, fuzzy +#| msgid "build" +msgid "uv-build" +msgstr "建置" + +#: ../source/guides/writing-pyproject-toml.rst:318 +msgid "1.27.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:319 +msgid "77.0.3" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:320 +msgid "3.12" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:321 +msgid "2.4.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:322 +msgid "2.2.0" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:323 +msgid "0.7.19" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:329 +#: ../source/specifications/pyproject-toml.rst:144 +#: ../source/specifications/pyproject-toml.rst:255 +msgid "``license``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:331 +msgid "" +"The new format for ``license`` is a valid :term:`SPDX license expression " +"` consisting of one or more :term:`license identifiers " +"`. The full license list is available at the `SPDX " +"license list page `_. The supported list version is 3.17 " +"or any later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:344 +msgid "" +"If you get a build error that ``license`` should be a dict/table, your build " +"backend doesn't yet support the new format. See the `above section `_ for more context. The now deprecated format is " +"`described in PEP 621 `__." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:349 +msgid "" +"As a general rule, it is a good idea to use a standard, well-known license, " +"both to avoid confusion and because some organizations avoid software whose " +"license is unapproved." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:353 +msgid "" +"If your :term:`Distribution Archive` is licensed with a license that doesn't " +"have an existing SPDX identifier, you can create a custom one in format " +"``LicenseRef-[idstring]``. The custom identifiers must follow the SPDX " +"specification, `clause 10.1 `_ of the version 2.2 or any " +"later compatible one." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:368 +#: ../source/specifications/pyproject-toml.rst:145 +#: ../source/specifications/pyproject-toml.rst:291 +msgid "``license-files``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:370 +msgid "" +"This is a list of license files and files containing other legal information " +"you want to distribute with your package." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:378 +msgid "The glob patterns must follow the specification:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:380 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) will be matched verbatim." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:382 +msgid "" +"Special characters: ``*``, ``?``, ``**`` and character ranges: [] are " +"supported." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:383 +msgid "Path delimiters must be the forward slash character (``/``)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:384 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`, " +"and thus may not start with a slash character." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:386 +msgid "Parent directory indicators (``..``) must not be used." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:387 +msgid "Each glob must match at least one file." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:389 +msgid "" +"Literal paths are valid globs. Any characters or character sequences not " +"covered by this specification are invalid." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:395 +#: ../source/specifications/pyproject-toml.rst:143 +#: ../source/specifications/pyproject-toml.rst:374 +msgid "``keywords``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:397 +msgid "" +"This will help PyPI's search box to suggest your project when people search " +"for these keywords." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:409 +#: ../source/specifications/pyproject-toml.rst:135 +#: ../source/specifications/pyproject-toml.rst:386 +msgid "``classifiers``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:411 +msgid "" +"A list of PyPI classifiers that apply to your project. Check the `full list " +"of possibilities `_." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:436 +msgid "" +"Although the list of classifiers is often used to declare what Python " +"versions a project supports, this information is only used for searching and " +"browsing projects on PyPI, not for installing projects. To actually restrict " +"what Python versions a project can be installed on, use the :ref:`requires-" +"python` argument." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:441 +msgid "" +"To prevent a package from being uploaded to PyPI, use the special " +"``Private :: Do Not Upload`` classifier. PyPI will always reject packages " +"with classifiers beginning with ``Private ::``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:448 +#: ../source/specifications/pyproject-toml.rst:152 +#: ../source/specifications/pyproject-toml.rst:404 +msgid "``urls``" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:450 +msgid "" +"A list of URLs associated with your project, displayed on the left sidebar " +"of your PyPI project page." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:455 +msgid "" +"See :ref:`well-known-labels` for a listing of labels that PyPI and other " +"packaging tools are specifically aware of, and `PyPI's project metadata docs " +"`_ for PyPI-specific " +"URL processing." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:469 +msgid "" +"Note that if the label contains spaces, it needs to be quoted, e.g., " +"``Website = \"https://example.com\"`` but ``\"Official Website\" = \"https://" +"example.com\"``." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:473 +msgid "" +"Users are advised to use :ref:`well-known-labels` for their project URLs " +"where appropriate, since consumers of metadata (like package indices) can " +"specialize their presentation." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:477 +msgid "" +"For example in the following metadata, neither ``MyHomepage`` nor " +"``\"Download Link\"`` is a well-known label, so they will be rendered " +"verbatim:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:487 +msgid "" +"Whereas in this metadata ``HomePage`` and ``DOWNLOAD`` both have well-known " +"equivalents (``homepage`` and ``download``), and can be presented with those " +"semantics in mind (the project's home page and its external download " +"location, respectively)." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:499 +msgid "Advanced plugins" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:501 +msgid "" +"Some packages can be extended through plugins. Examples include Pytest_ and " +"Pygments_. To create such a plugin, you need to declare it in a subtable of " +"``[project.entry-points]`` like this:" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:510 +msgid "See the :ref:`Plugin guide ` for more information." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:515 +msgid "A full example" +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:578 +msgid "" +"Think twice before applying an upper bound like ``requires-python = \"<= " +"3.10\"`` here. `This blog post `_ contains some " +"information regarding possible problems." +msgstr "" + +#: ../source/guides/writing-pyproject-toml.rst:582 +msgid "" +"flit-core `does not yet `_ support WITH in SPDX license " +"expressions." +msgstr "" + +#: ../source/index.rst:-1 +msgid "" +"The Python Packaging User Guide (PyPUG) is a collection of tutorials and " +"guides for packaging Python software." +msgstr "" + +#: ../source/index.rst:-1 +msgid "python, packaging, guide, tutorial" +msgstr "" + +#: ../source/index.rst:3 ../source/key_projects.rst:247 +msgid "Python Packaging User Guide" +msgstr "Python 打包使用者指南" + +#: ../source/index.rst:25 +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." +msgstr "" + +#: ../source/index.rst:29 +msgid "" +"This guide is maintained on `GitHub`_ by the :doc:`Python Packaging " +"Authority `. We happily accept :doc:`contributions and feedback " +"`. 😊" +msgstr "" + +#: ../source/index.rst:36 +msgid "Overview and Flow" +msgstr "" + +#: ../source/index.rst:40 +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." +msgstr "" + +#: ../source/index.rst:44 +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." +msgstr "" + +#: ../source/index.rst:51 +msgid "" +"To get an overview of the workflow used to publish your code, " +"see :doc:`packaging flow `." +msgstr "" + +#: ../source/index.rst:57 +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:" +msgstr "" + +#: ../source/index.rst:62 +msgid "" +"A :doc:`tutorial on installing packages `" +msgstr "" + +#: ../source/index.rst:63 +msgid "" +"A :doc:`tutorial on managing application dependencies ` in a version controlled project" +msgstr "" + +#: ../source/index.rst:65 +msgid "" +"A :doc:`tutorial on packaging and distributing ` your project" +msgstr "" + +#: ../source/index.rst:71 +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." +msgstr "" + +#: ../source/index.rst:75 +msgid "" +"The :doc:`guides/index` section provides \"how to\" instructions in three " +"major areas: package installation; building and distributing packages; " +"miscellaneous topics." +msgstr "" + +#: ../source/index.rst:80 +msgid "Explanations and Discussions" +msgstr "" + +#: ../source/index.rst:82 +msgid "" +"The :doc:`discussions/index` section provides in-depth explanations and " +"discussion about topics, such as:" +msgstr "" + +#: ../source/index.rst:85 +msgid ":doc:`discussions/deploying-python-applications`" +msgstr "" + +#: ../source/index.rst:86 +msgid ":doc:`discussions/pip-vs-easy-install`" +msgstr "" + +#: ../source/index.rst:89 +msgid "Reference" +msgstr "參考" + +#: ../source/index.rst:91 +msgid "" +"The :doc:`specifications/index` section for packaging interoperability " +"specifications." +msgstr "" + +#: ../source/index.rst:92 +msgid "" +"The list of :doc:`other projects ` maintained by members of " +"the Python Packaging Authority." +msgstr "" + +#: ../source/index.rst:93 +msgid "The :doc:`glossary` for definitions of terms used in Python packaging." +msgstr "" + +#: ../source/key_projects.rst:6 +msgid "Project Summaries" +msgstr "" + +#: ../source/key_projects.rst:8 +msgid "" +"Summaries and links for the most relevant projects in the space of Python " +"installation and packaging." +msgstr "" + +#: ../source/key_projects.rst:14 +msgid "PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:19 +msgid "bandersnatch" +msgstr "bandersnatch" + +#: ../source/key_projects.rst:21 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +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 "" + +#: ../source/key_projects.rst:37 +msgid "build" +msgstr "建置" + +#: ../source/key_projects.rst:39 +msgid "" +":any:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:44 +msgid "" +"``build`` is a :pep:`517` compatible Python package builder. It provides a " +"CLI to build packages, as well as a Python API." +msgstr "" + +#: ../source/key_projects.rst:51 +msgid "cibuildwheel" +msgstr "cibuildwheel" + +#: ../source/key_projects.rst:53 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__ | " +"`Discussions `__ | " +"`Discord #cibuildwheel `__" +msgstr "" + +#: ../source/key_projects.rst:60 +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`." +msgstr "" + +#: ../source/key_projects.rst:66 +msgid "distlib" +msgstr "" + +#: ../source/key_projects.rst:68 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:73 +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." +msgstr "" + +#: ../source/key_projects.rst:82 +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." +msgstr "" + +#: ../source/key_projects.rst:93 +msgid "distutils" +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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:116 +msgid "flit" +msgstr "" + +#: ../source/key_projects.rst:118 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:142 +msgid "hatch" +msgstr "" + +#: ../source/key_projects.rst:144 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:157 +msgid "packaging" +msgstr "" + +#: ../source/key_projects.rst:159 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:164 +msgid "" +"Core utilities for Python packaging used by :ref:`pip` and :ref:`setuptools`." +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:186 +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "pip" +msgstr "pip" + +#: ../source/key_projects.rst:188 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:193 +msgid "" +"The most popular tool for installing Python packages, and the one included " +"with modern versions of Python." +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:204 +msgid "Pipenv" +msgstr "" + +#: ../source/key_projects.rst:206 +msgid "" +":doc:`Docs ` | `Source `__ | " +"`Issues `__ | `PyPI `__" +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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:225 +msgid "Pipfile" +msgstr "" + +#: ../source/key_projects.rst:227 +msgid "`Source `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:236 +msgid "pipx" +msgstr "pipx" + +#: ../source/key_projects.rst:238 +msgid "" +"`Docs `__ | `GitHub `__ " +"| `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:249 +msgid "" +":doc:`Docs ` | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:253 +msgid "This guide!" +msgstr "" + +#: ../source/key_projects.rst:258 +msgid "readme_renderer" +msgstr "readme_renderer" + +#: ../source/key_projects.rst:260 +msgid "" +"`GitHub and docs `__ | `PyPI " +"`__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:274 +msgid "Setuptools" +msgstr "" + +#: ../source/key_projects.rst:276 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:281 +msgid "" +"Setuptools (which includes ``easy_install``) is a collection of enhancements " +"to the Python distutils that allow you to more easily build and distribute " +"Python :term:`distributions `, especially ones that " +"have dependencies on other packages." +msgstr "" + +#: ../source/key_projects.rst:289 +msgid "trove-classifiers" +msgstr "" + +#: ../source/key_projects.rst:291 +msgid "" +"`Issues `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:314 +msgid "twine" +msgstr "" + +#: ../source/key_projects.rst:316 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:331 ../source/overview.rst:405 +msgid "virtualenv" +msgstr "" + +#: ../source/key_projects.rst:333 +msgid "" +"`Docs `__ | `Issues " +"`__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:350 +msgid "Warehouse" +msgstr "" + +#: ../source/key_projects.rst:352 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:364 +msgid "wheel" +msgstr "" + +#: ../source/key_projects.rst:366 +msgid "" +"`Docs `__ | `Issues `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/key_projects.rst:384 +msgid "Non-PyPA Projects" +msgstr "" + +#: ../source/key_projects.rst:389 +msgid "buildout" +msgstr "" + +#: ../source/key_projects.rst:391 +msgid "" +"`Docs `__ | `Issues `__ | `PyPI `__ | `GitHub `__" +msgstr "" + +#: ../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 "" + +#: ../source/key_projects.rst:403 +msgid "conda" +msgstr "" + +#: ../source/key_projects.rst:405 +msgid ":doc:`Docs `" +msgstr "" + +#: ../source/key_projects.rst:407 +msgid "" +"Conda is a package, dependency, and environment management system for any " +"language — Python, R, Ruby, C/C++, Fortran, and more. It is written in " +"Python and widely used in the Python scientific computing community, due to " +"its support for non-Python compiled libraries and extensions. It is used as " +"the basis of the `Anaconda `__ Python " +"distribution from Anaconda, Inc. It was originally aimed at the scientific " +"community, but can also be used on its own, or with the :doc:`miniconda " +"`, `miniforge `_ " +"or `pixi `_ systems. It is available for Windows, Mac and " +"Linux systems." +msgstr "" + +#: ../source/key_projects.rst:416 +msgid "" +"Conda is a completely separate tool from :ref:`pip`, virtualenv and wheel, " +"but provides many of their combined features, such as package management, " +"virtual environment management and deployment of binary extensions and other " +"binary code." +msgstr "" + +#: ../source/key_projects.rst:420 +msgid "" +"Conda does not install packages from PyPI -- it can only manage packages " +"built specifically for conda, which can be made available on a \"conda " +"channel\", such as those hosted on `anaconda.org `__, " +"or a local (e.g. intranet) package server. In addition to the \"default\" " +"channels managed by `Anaconda, Inc. `__, there " +"are a wide variety of packages from the community supported `conda-forge " +"project `__" +msgstr "" + +#: ../source/key_projects.rst:426 +msgid "" +"Note that :ref:`pip` can be installed into, and work side-by-side with conda " +"for managing :term:`distributions ` from PyPI. It is " +"also possible to build conda packages from Python source packages using " +"tools such as `conda skeleton `__: a tool to " +"automatically make conda packages from Python packages available on PyPI." +msgstr "" + +#: ../source/key_projects.rst:435 +msgid "devpi" +msgstr "" + +#: ../source/key_projects.rst:437 +msgid "" +"`Docs `__ | :gh:`Issues ` " +"| `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:441 +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." +msgstr "" + +#: ../source/key_projects.rst:452 +msgid "dumb-pypi" +msgstr "" + +#: ../source/key_projects.rst:454 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:457 +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 "" + +#: ../source/key_projects.rst:464 +msgid "enscons" +msgstr "" + +#: ../source/key_projects.rst:466 +msgid "" +":gh:`Source ` | :gh:`Issues ` | `PyPI " +"`__" +msgstr "" + +#: ../source/key_projects.rst:470 +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 "" + +#: ../source/key_projects.rst:485 +msgid "Flask-Pypi-Proxy" +msgstr "" + +#: ../source/key_projects.rst:487 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:491 ../source/key_projects.rst:685 +#: ../source/key_projects.rst:744 +msgid "Not maintained, project archived" +msgstr "" + +#: ../source/key_projects.rst:493 +msgid "" +"Flask-Pypi-Proxy is a :term:`package index ` as a cached " +"proxy for PyPI." +msgstr "" + +#: ../source/key_projects.rst:499 +msgid "Hashdist" +msgstr "" + +#: ../source/key_projects.rst:501 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:504 +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 "" + +#: ../source/key_projects.rst:516 +msgid "Maturin" +msgstr "" + +#: ../source/key_projects.rst:518 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:521 +msgid "" +"Maturin is a build backend for Rust extension modules, also written in Rust. " +"It supports building wheels for python 3.7+ on Windows, Linux, macOS and " +"FreeBSD, can upload them to PyPI and has basic PyPy and GraalPy support." +msgstr "" + +#: ../source/key_projects.rst:529 +msgid "meson-python" +msgstr "" + +#: ../source/key_projects.rst:531 +msgid "" +"`Docs `__ | `GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:534 +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 "" + +#: ../source/key_projects.rst:544 +msgid "multibuild" +msgstr "" + +#: ../source/key_projects.rst:546 +msgid "`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:548 +msgid "" +"Multibuild is a set of CI scripts for building and testing " +"Python :term:`wheels ` for Linux, macOS, and (less flexibly) Windows. " +"Also see :ref:`cibuildwheel`." +msgstr "" + +#: ../source/key_projects.rst:554 +msgid "nginx_pypi_cache" +msgstr "" + +#: ../source/key_projects.rst:556 +msgid ":gh:`GitHub `" +msgstr "" + +#: ../source/key_projects.rst:558 +msgid "" +"nginx_pypi_cache is a :term:`package index ` caching proxy " +"using `nginx `_." +msgstr "" + +#: ../source/key_projects.rst:564 +msgid "pdm" +msgstr "" + +#: ../source/key_projects.rst:566 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:570 +msgid "" +"PDM is a modern Python package manager. It uses :term:`pyproject.toml` to " +"store project metadata as defined in :pep:`621`." +msgstr "" + +#: ../source/key_projects.rst:578 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:582 +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 "" + +#: ../source/key_projects.rst:594 +msgid "pip-tools" +msgstr "" + +#: ../source/key_projects.rst:596 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:600 +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." +msgstr "" + +#: ../source/key_projects.rst:612 +msgid "pip2pi" +msgstr "" + +#: ../source/key_projects.rst:614 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:617 +msgid "" +"pip2pi is a :term:`package index ` server where specific " +"packages are manually synchronised." +msgstr "" + +#: ../source/key_projects.rst:623 +msgid "piwheels" +msgstr "" + +#: ../source/key_projects.rst:625 +msgid "" +"`Website `__ | :doc:`Docs ` | " +"`GitHub `__" +msgstr "" + +#: ../source/key_projects.rst:629 +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 "" + +#: ../source/key_projects.rst:638 +msgid "poetry" +msgstr "" + +#: ../source/key_projects.rst:640 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:644 +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." +msgstr "" + +#: ../source/key_projects.rst:654 +msgid "proxpi" +msgstr "" + +#: ../source/key_projects.rst:656 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:659 +msgid "" +"proxpi is a simple :term:`package index ` which proxies PyPI " +"and other indexes with caching." +msgstr "" + +#: ../source/key_projects.rst:665 +msgid "Pulp-python" +msgstr "" + +#: ../source/key_projects.rst:667 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:671 +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." +msgstr "" + +#: ../source/key_projects.rst:679 +msgid "PyPI Cloud" +msgstr "" + +#: ../source/key_projects.rst:681 +msgid "" +"`Docs `__ | :gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:687 +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." +msgstr "" + +#: ../source/key_projects.rst:695 +msgid "pypiprivate" +msgstr "" + +#: ../source/key_projects.rst:697 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:700 +msgid "" +"pypiprivate serves a local (or `AWS S3`_-hosted) directory of packages as " +"a :term:`package index `." +msgstr "" + +#: ../source/key_projects.rst:706 +msgid "pypiserver" +msgstr "" + +#: ../source/key_projects.rst:708 +msgid "" +"`GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:711 +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." +msgstr "" + +#: ../source/key_projects.rst:722 +msgid "PyScaffold" +msgstr "" + +#: ../source/key_projects.rst:724 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:728 +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 "" + +#: ../source/key_projects.rst:739 +msgid "pywharf" +msgstr "" + +#: ../source/key_projects.rst:741 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:746 +msgid "" +"pywharf is a :term:`package index ` server, serving files " +"locally or from `GitHub `_." +msgstr "" + +#: ../source/key_projects.rst:752 +msgid "scikit-build" +msgstr "" + +#: ../source/key_projects.rst:754 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:758 +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 "" + +#: ../source/key_projects.rst:769 +msgid "scikit-build-core" +msgstr "" + +#: ../source/key_projects.rst:771 +msgid "" +"`Docs `__ | `GitHub " +"`__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:775 +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." +msgstr "" + +#: ../source/key_projects.rst:785 +msgid "shiv" +msgstr "" + +#: ../source/key_projects.rst:787 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:791 +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." +msgstr "" + +#: ../source/key_projects.rst:799 +msgid "simpleindex" +msgstr "" + +#: ../source/key_projects.rst:801 +msgid "" +":gh:`GitHub ` | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:804 +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." +msgstr "" + +#: ../source/key_projects.rst:814 +msgid "" +":doc:`Docs ` | `GitHub `__ | " +"`Paper `__ | `Slides `__" +msgstr "" + +#: ../source/key_projects.rst:819 +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 "" + +#: ../source/key_projects.rst:827 +msgid "" +"Spack is not in PyPI (yet), but it requires no installation and can be used " +"immediately after cloning from GitHub." +msgstr "" + +#: ../source/key_projects.rst:833 +msgid "zest.releaser" +msgstr "" + +#: ../source/key_projects.rst:835 +msgid "" +"`Docs `__ | `GitHub `__ | `PyPI `__" +msgstr "" + +#: ../source/key_projects.rst:839 +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." +msgstr "" + +#: ../source/key_projects.rst:846 +msgid "Standard Library Projects" +msgstr "" + +#: ../source/key_projects.rst:851 +msgid "ensurepip" +msgstr "" + +#: ../source/key_projects.rst:853 +msgid "" +"`Docs `__ | `Issues " +"`__" +msgstr "" + +#: ../source/key_projects.rst:856 +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." +msgstr "" + +#: ../source/key_projects.rst:864 +msgid "http.server" +msgstr "" + +#: ../source/key_projects.rst:866 +msgid "" +":doc:`Docs ` | :gh:`Issues `" +msgstr "" + +#: ../source/key_projects.rst:869 +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`)." +msgstr "" + +#: ../source/key_projects.rst:876 +msgid "venv" +msgstr "" + +#: ../source/key_projects.rst:878 +msgid "" +"`Docs `__ | `Issues `__" +msgstr "" + +#: ../source/key_projects.rst:881 +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`." +msgstr "" + +#: ../source/news.rst:2 +msgid "News" +msgstr "新聞" + +#: ../source/news.rst:4 +msgid "" +"This document is not currently updated. Previously, the document highlighted " +"changes in Python packaging." +msgstr "" + +#: ../source/news.rst:9 +msgid "September 2019" +msgstr "" + +#: ../source/news.rst:10 +msgid "Added a guide about publishing dists via GitHub Actions. (:pr:`647`)" +msgstr "" + +#: ../source/news.rst:13 +msgid "August 2019" +msgstr "" + +#: ../source/news.rst:14 +msgid "Updated to use :file:`python3 -m` when installing pipx. (:pr:`631`)" +msgstr "" + +#: ../source/news.rst:17 +msgid "July 2019" +msgstr "" + +#: ../source/news.rst:18 +msgid "Marked all PEP numbers with the :pep: role. (:pr:`629`)" +msgstr "" + +#: ../source/news.rst:19 +msgid "Upgraded Sphinx version and removed pypa.io intersphinx. (:pr:`625`)" +msgstr "" + +#: ../source/news.rst:20 +msgid "Mentioned :file:`find_namespace_packages`. (:pr:`622`)" +msgstr "" + +#: ../source/news.rst:21 +msgid "Updated directory layout examples for consistency. (:pr:`611`)" +msgstr "" + +#: ../source/news.rst:22 +msgid "Updated Bandersnatch link to GitHub. (:pr:`623`)" +msgstr "" + +#: ../source/news.rst:25 +msgid "June 2019" +msgstr "" + +#: ../source/news.rst:26 +msgid "Fixed some typos. (:pr:`620`)" +msgstr "" + +#: ../source/news.rst:29 +msgid "May 2019" +msgstr "" + +#: ../source/news.rst:30 +msgid "Added :file:`python_requires` usage to packaging tutorial. (:pr:`613`)" +msgstr "" + +#: ../source/news.rst:31 +msgid "Added a MANIFEST.in guide page. (:pr:`609`)" +msgstr "" + +#: ../source/news.rst:34 +msgid "April 2019" +msgstr "" + +#: ../source/news.rst:35 +msgid "" +"Added a mention for :file:`shiv` in the key projects section. (:pr:`608`)" +msgstr "" + +#: ../source/news.rst:36 +msgid "Reduced emphasis on virtualenv. (:pr:`606`)" +msgstr "" + +#: ../source/news.rst:39 +msgid "March 2019" +msgstr "" + +#: ../source/news.rst:40 +msgid "Moved single-sourcing guide version option to Python 3. (:pr:`605`)" +msgstr "" + +#: ../source/news.rst:41 +msgid "Covered RTD details for contributing. (:pr:`600`)" +msgstr "" + +#: ../source/news.rst:44 +msgid "February 2019" +msgstr "" + +#: ../source/news.rst:45 +msgid "" +"Elaborate upon the differences between the tutorial and the real packaging " +"process. (:pr:`602`)" +msgstr "" + +#: ../source/news.rst:46 +msgid "Added instructions to install Python CLI applications. (:pr:`594`)" +msgstr "" + +#: ../source/news.rst:49 +msgid "January 2019" +msgstr "" + +#: ../source/news.rst:50 +msgid "Added :file:`--no-deps` to the packaging tutorial. (:pr:`593`)" +msgstr "" + +#: ../source/news.rst:51 +msgid "Updated Sphinx and Nox. (:pr:`591`)" +msgstr "" + +#: ../source/news.rst:52 +msgid "Referenced Twine from Python3. (:pr:`581`)" +msgstr "" + +#: ../source/news.rst:55 +msgid "December 2018" +msgstr "" + +#: ../source/news.rst:56 +msgid "No programmers in the office!" +msgstr "" + +#: ../source/news.rst:59 +msgid "November 2018" +msgstr "" + +#: ../source/news.rst:60 +msgid "Removed landing page link to PyPI migration guide. (:pr:`575`)" +msgstr "" + +#: ../source/news.rst:61 +msgid "Changed bumpversion to bump2version. (:pr:`572`)" +msgstr "" + +#: ../source/news.rst:62 +msgid "Added single-sourcing package version example. (:pr:`573`)" +msgstr "" + +#: ../source/news.rst:63 +msgid "Added a guide for creating documentation. (:pr:`568`)" +msgstr "" + +#: ../source/news.rst:66 +msgid "October 2018" +msgstr "" + +#: ../source/news.rst:67 +msgid "Updated Nox package name. (:pr:`566`)" +msgstr "" + +#: ../source/news.rst:68 +msgid "Mentioned Sphinx extensions in guides. (:pr:`562`)" +msgstr "" + +#: ../source/news.rst:71 +msgid "September 2018" +msgstr "" + +#: ../source/news.rst:72 +msgid "Added a section on checking RST markup. (:pr:`554`)" +msgstr "" + +#: ../source/news.rst:73 +msgid "Updated user installs page. (:pr:`558`)" +msgstr "" + +#: ../source/news.rst:74 +msgid "Updated Google BigQuery urls. (:pr:`556`)" +msgstr "" + +#: ../source/news.rst:75 +msgid "Replaced tar command with working command. (:pr:`552`)" +msgstr "" + +#: ../source/news.rst:76 +msgid "" +"Changed to double quotes in the pip install SomeProject==1.4. (:pr:`550`)" +msgstr "" + +#: ../source/news.rst:79 +msgid "August 2018" +msgstr "" + +#: ../source/news.rst:80 +msgid "Removed the recommendation to store passwords in cleartext. (:pr:`546`)" +msgstr "" + +#: ../source/news.rst:81 +msgid "" +"Moved the Overview to a task based lead in along with the others. (:pr:`540`)" +msgstr "" + +#: ../source/news.rst:82 +msgid "Updated Python version supported by virtualenv. (:pr:`538`)" +msgstr "" + +#: ../source/news.rst:83 +msgid "Added outline/rough draft of new Overview page. (:pr:`519`)" +msgstr "" + +#: ../source/news.rst:86 +msgid "July 2018" +msgstr "" + +#: ../source/news.rst:88 +msgid "Improved binary extension docs. (:pr:`531`)" +msgstr "" + +#: ../source/news.rst:89 +msgid "Added scikit-build to key projects. (:pr:`530`)" +msgstr "" + +#: ../source/news.rst:92 +msgid "June 2018" +msgstr "" + +#: ../source/news.rst:94 +msgid "Fixed categories of interop PEP for pypa.io. (:pr:`527`)" +msgstr "" + +#: ../source/news.rst:95 +msgid "Updated Markdown descriptions explanation. (:pr:`522`)" +msgstr "" + +#: ../source/news.rst:98 +msgid "May 2018" +msgstr "" + +#: ../source/news.rst:100 +msgid "Noted issues with Provides-Dist and Obsoletes-Dist. (:pr:`513`)" +msgstr "" + +#: ../source/news.rst:101 +msgid "" +"Removed outdated warning about Python version mixing with Pipenv. (:pr:`501`)" +msgstr "" + +#: ../source/news.rst:102 +msgid "Simplified packaging tutorial. (:pr:`498`)" +msgstr "" + +#: ../source/news.rst:103 +msgid "Updated Windows users instructions for clarity. (:pr:`493`)" +msgstr "" + +#: ../source/news.rst:104 +msgid "Updated the license section description for completeness. (:pr:`492`)" +msgstr "" + +#: ../source/news.rst:105 +msgid "Added specification-style document to contributing section. (:pr:`489`)" +msgstr "" + +#: ../source/news.rst:106 +msgid "Added documentation types to contributing guide. (:pr:`485`)" +msgstr "" + +#: ../source/news.rst:109 +msgid "April 2018" +msgstr "" + +#: ../source/news.rst:111 +msgid "Added README guide. (:pr:`461`)" +msgstr "" + +#: ../source/news.rst:112 +msgid "Updated instructions and status for PyPI launch. (:pr:`475`)" +msgstr "" + +#: ../source/news.rst:113 +msgid "Added instructions for Warehouse. (:pr:`471`)" +msgstr "" + +#: ../source/news.rst:114 +msgid "Removed GPG references from publishing tutorial. (:pr:`466`)" +msgstr "" + +#: ../source/news.rst:115 +msgid "Added 'What’s in which Python 3.4–3.6?'. (:pr:`468`)" +msgstr "" + +#: ../source/news.rst:116 +msgid "Added a guide for phasing out Python versions. (:pr:`459`)" +msgstr "" + +#: ../source/news.rst:117 +msgid "Made default Description-Content-Type variant GFM. (:pr:`462`)" +msgstr "" + +#: ../source/news.rst:120 +msgid "March 2018" +msgstr "" + +#: ../source/news.rst:122 +msgid "Updated \"installing scientific packages\". (:pr:`455`)" +msgstr "" + +#: ../source/news.rst:123 +msgid "" +"Added :file:`long_description_content_type` to follow PEP 556. (:pr:`457`)" +msgstr "" + +#: ../source/news.rst:124 +msgid "Clarified a long description classifier on pypi.org. (:pr:`456`)" +msgstr "" + +#: ../source/news.rst:125 +msgid "Updated Core Metadata spec to follow PEP 556. (:pr:`412`)" +msgstr "" + +#: ../source/news.rst:128 +msgid "February 2018" +msgstr "" + +#: ../source/news.rst:130 +msgid "" +"Added python3-venv and python3-pip to Debian installation instructions. " +"(:pr:`445`)" +msgstr "" + +#: ../source/news.rst:131 +msgid "Updated PyPI migration info. (:pr:`439`)" +msgstr "" + +#: ../source/news.rst:132 +msgid "" +"Added a warning about managing multiple versions with pipenv. (:pr:`430`)" +msgstr "" + +#: ../source/news.rst:133 +msgid "Added example of multiple emails to Core Metadata. (:pr:`429`)" +msgstr "" + +#: ../source/news.rst:134 +msgid "Added explanation of \"legacy\" in test.pypi.org/legacy. (:pr:`426`)" +msgstr "" + +#: ../source/news.rst:137 +msgid "January 2018" +msgstr "" + +#: ../source/news.rst:139 +msgid "Added a link to PyPI's list of classifiers. (:pr:`425`)" +msgstr "" + +#: ../source/news.rst:140 +msgid "Updated README.rst explanation. (:pr:`419`)" +msgstr "" + +#: ../source/news.rst:143 +msgid "December 2017" +msgstr "" + +#: ../source/news.rst:145 +msgid "" +"Replaced :file:`~` with :file:`$HOME` in guides and tutorials. (:pr:`418`)" +msgstr "" + +#: ../source/news.rst:146 +msgid "Noted which fields can be used with environment markers. (:pr:`416`)" +msgstr "" + +#: ../source/news.rst:147 +msgid "Updated Requires-Python section. (:pr:`414`)" +msgstr "" + +#: ../source/news.rst:148 +msgid "Added news page. (:pr:`404`)" +msgstr "" + +#: ../source/news.rst:151 +msgid "November 2017" +msgstr "" + +#: ../source/news.rst:153 +msgid "" +"Introduced a new dependency management tutorial based on Pipenv. (:pr:`402`)" +msgstr "" + +#: ../source/news.rst:154 +msgid "" +"Updated the *Single Sourcing Package Version* tutorial to reflect pip's " +"current strategy. (:pr:`400`)" +msgstr "" + +#: ../source/news.rst:156 +msgid "" +"Added documentation about the ``py_modules`` argument to ``setup``. " +"(:pr:`398`)" +msgstr "" + +#: ../source/news.rst:157 +msgid "Simplified the wording for the :file:`manifest.in` section. (:pr:`395`)" +msgstr "" + +#: ../source/news.rst:160 +msgid "October 2017" +msgstr "" + +#: ../source/news.rst:162 +msgid "" +"Added a specification for the :file:`entry_points.txt` file. (:pr:`398`)" +msgstr "" + +#: ../source/news.rst:163 +msgid "" +"Created a new guide for managing packages using ``pip`` and ``virtualenv``. " +"(:pr:`385`)" +msgstr "" + +#: ../source/news.rst:164 +msgid "Split the specifications page into multiple pages. (:pr:`386`)" +msgstr "" + +#: ../source/news.rst:167 +msgid "September 2017" +msgstr "" + +#: ../source/news.rst:169 +msgid "" +"Encouraged using ``readme_renderer`` to validate :file:`README.rst`. " +"(:pr:`379`)" +msgstr "" + +#: ../source/news.rst:171 +msgid "Recommended using the ``--user-base`` option. (:pr:`374`)" +msgstr "" + +#: ../source/news.rst:174 +msgid "August 2017" +msgstr "" + +#: ../source/news.rst:176 +msgid "" +"Added a new, experimental tutorial on installing packages using ``Pipenv``. " +"(:pr:`369`)" +msgstr "" + +#: ../source/news.rst:177 +msgid "Added a new guide on how to use ``TestPyPI``. (:pr:`366`)" +msgstr "" + +#: ../source/news.rst:178 +msgid "Added :file:`pypi.org` as a term. (:pr:`365`)" +msgstr "" + +#: ../source/news.rst:181 +msgid "July 2017" +msgstr "" + +#: ../source/news.rst:183 +msgid "Added ``flit`` to the key projects list. (:pr:`358`)" +msgstr "" + +#: ../source/news.rst:184 +msgid "Added ``enscons`` to the list of key projects. (:pr:`357`)" +msgstr "" + +#: ../source/news.rst:185 +msgid "" +"Updated this guide's ``readme`` with instructions on how to build the guide " +"locally. (:pr:`356`)" +msgstr "" + +#: ../source/news.rst:186 +msgid "" +"Made the new ``TestPyPI`` URL more visible, adding note to homepage about " +"pypi.org. (:pr:`354`)" +msgstr "" + +#: ../source/news.rst:187 +msgid "" +"Added a note about the removal of the explicit registration API. (:pr:`347`)" +msgstr "" + +#: ../source/news.rst:190 +msgid "June 2017" +msgstr "" + +#: ../source/news.rst:192 +msgid "Added a document on migrating uploads to :file:`PyPI.org`. (:pr:`339`)" +msgstr "" + +#: ../source/news.rst:193 +msgid "Added documentation for ``python_requires``. (:pr:`338`)" +msgstr "" + +#: ../source/news.rst:194 +msgid "" +"Added a note about PyPI migration in the *Tool Recommendations* tutorial. " +"(:pr:`335`)" +msgstr "" + +#: ../source/news.rst:195 +msgid "" +"Added a note that :file:`manifest.in` does not affect wheels. (:pr:`332`)" +msgstr "" + +#: ../source/news.rst:196 +msgid "Added a license section to the distributing guide. (:pr:`331`)" +msgstr "" + +#: ../source/news.rst:197 +msgid "Expanded the section on the ``name`` argument. (:pr:`329`)" +msgstr "" + +#: ../source/news.rst:198 +msgid "Adjusted the landing page. (:pr:`327`, :pr:`326`, :pr:`324`)" +msgstr "" + +#: ../source/news.rst:199 +msgid "Updated to Sphinx 1.6.2. (:pr:`323`)" +msgstr "" + +#: ../source/news.rst:200 +msgid "Switched to the PyPA theme. (:pr:`305`)" +msgstr "" + +#: ../source/news.rst:201 +msgid "Re-organized the documentation into the new structure. (:pr:`318`)" +msgstr "" + +#: ../source/news.rst:204 +msgid "May 2017" +msgstr "" + +#: ../source/news.rst:206 +msgid "" +"Added documentation for the ``Description-Content-Type`` field. (:pr:`258`)" +msgstr "" + +#: ../source/news.rst:207 +msgid "Added contributor and style guide. (:pr:`307`)" +msgstr "" + +#: ../source/news.rst:208 +msgid "" +"Documented ``pip`` and ``easy_install``'s differences for per-project " +"indexes. (:pr:`233`)" +msgstr "" + +#: ../source/news.rst:211 +msgid "April 2017" +msgstr "" + +#: ../source/news.rst:213 +msgid "Added travis configuration for testing pull requests. (:pr:`300`)" +msgstr "" + +#: ../source/news.rst:214 +msgid "" +"Mentioned the requirement of the ``wheel`` package for creating wheels " +"(:pr:`299`)" +msgstr "" + +#: ../source/news.rst:215 +msgid "" +"Removed the ``twine register`` reference in the *Distributing Packages* " +"tutorial. (:pr:`271`)" +msgstr "" + +#: ../source/news.rst:216 +msgid "Added a topic on plugin discovery. (:pr:`294`, :pr:`296`)" +msgstr "" + +#: ../source/news.rst:217 +msgid "Added a topic on namespace packages. (:pr:`290`)" +msgstr "" + +#: ../source/news.rst:218 +msgid "" +"Added documentation explaining prominently how to install ``pip`` in ``/usr/" +"local``. (:pr:`230`)" +msgstr "" + +#: ../source/news.rst:219 +msgid "" +"Updated development mode documentation to mention that order of local " +"packages matters. (:pr:`208`)" +msgstr "" + +#: ../source/news.rst:220 +msgid "" +"Convert readthedocs link for their ``.org`` -> ``.io`` migration for hosted " +"projects (:pr:`239`)" +msgstr "" + +#: ../source/news.rst:221 +msgid "" +"Swapped order of :file:`setup.py` arguments for the upload command, as order " +"is significant. (:pr:`260`)" +msgstr "" + +#: ../source/news.rst:223 +msgid "" +"Explained how to install from unsupported sources using a helper " +"application. (:pr:`289`)" +msgstr "" + +#: ../source/news.rst:227 +msgid "March 2017" +msgstr "" + +#: ../source/news.rst:229 +msgid "Covered ``manylinux1`` in *Platform Wheels*. (:pr:`283`)" +msgstr "" + +#: ../source/news.rst:232 +msgid "February 2017" +msgstr "" + +#: ../source/news.rst:234 +msgid "Added :pep:`518`. (:pr:`281`)" +msgstr "" + +#: ../source/overview.rst:3 +msgid "Overview of Python Packaging" +msgstr "" + +#: ../source/overview.rst:7 +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." +msgstr "" + +#: ../source/overview.rst:12 +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." +msgstr "" + +#: ../source/overview.rst:18 +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." +msgstr "" + +#: ../source/overview.rst:23 +msgid "Thinking about deployment" +msgstr "" + +#: ../source/overview.rst:25 +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:" +msgstr "" + +#: ../source/overview.rst:29 +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?" +msgstr "" + +#: ../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/overview.rst:34 +msgid "" +"Is your software installed individually, or in large deployment batches?" +msgstr "" + +#: ../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/overview.rst:43 +msgid "Packaging Python libraries and tools" +msgstr "" + +#: ../source/overview.rst:45 +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`." +msgstr "" + +#: ../source/overview.rst:50 +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`." +msgstr "" + +#: ../source/overview.rst:56 +msgid "Python modules" +msgstr "" + +#: ../source/overview.rst:58 +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." +msgstr "" + +#: ../source/overview.rst:63 +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 " +"`." +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 "" + +#: ../source/overview.rst:75 +msgid "Python source distributions" +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 "" + +#: ../source/overview.rst:81 +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." +msgstr "" + +#: ../source/overview.rst:87 +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." +msgstr "" + +#: ../source/overview.rst:92 +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." +msgstr "" + +#: ../source/overview.rst:97 +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." +msgstr "" + +#: ../source/overview.rst:104 +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!" +msgstr "" + +#: ../source/overview.rst:111 +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``." +msgstr "" + +#: ../source/overview.rst:116 +msgid "Python binary distributions" +msgstr "" + +#: ../source/overview.rst:118 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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 "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:145 +msgid "A summary of Python's packaging capabilities for tools and libraries." +msgstr "" + +#: ../source/overview.rst:145 +msgid "" +"Python's recommended built-in library and tool packaging technologies. " +"Excerpted from `The Packaging Gradient (2017) `_." +msgstr "" + +#: ../source/overview.rst:152 +msgid "Packaging Python applications" +msgstr "" + +#: ../source/overview.rst:154 +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." +msgstr "" + +#: ../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/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 "" + +#: ../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." +msgstr "" + +#: ../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/overview.rst:178 +msgid "Depending on a framework" +msgstr "" + +#: ../source/overview.rst:180 +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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/overview.rst:196 +msgid "Service platforms" +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:209 +msgid "Web browsers and mobile applications" +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 "" + +#: ../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/overview.rst:220 +#, fuzzy +msgid "`Kivy `_" +msgstr "`Poetry `_" + +#: ../source/overview.rst:221 +msgid "`Beeware `_" +msgstr "" + +#: ../source/overview.rst:222 +msgid "`Brython `_" +msgstr "" + +#: ../source/overview.rst:223 +msgid "`Flexx `_" +msgstr "" + +#: ../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/overview.rst:230 +msgid "Depending on a pre-installed Python" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:238 +msgid "Technologies which support this model:" +msgstr "" + +#: ../source/overview.rst:240 +msgid ":gh:`PEX ` (Python EXecutable)" +msgstr "" + +#: ../source/overview.rst:241 +msgid "" +":doc:`zipapp ` (does not help manage dependencies, " +"requires Python 3.5+)" +msgstr "" + +#: ../source/overview.rst:242 +msgid ":gh:`shiv ` (requires Python 3)" +msgstr "" + +#: ../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 "" + +#: ../source/overview.rst:249 +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 "" + +#: ../source/overview.rst:256 +msgid "Depending on a separate software distribution ecosystem" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../source/overview.rst:273 +msgid "Instructions on building and publishing for the Anaconda ecosystem:" +msgstr "" + +#: ../source/overview.rst:275 +msgid "" +"`Building libraries and applications with conda `_" +msgstr "" + +#: ../source/overview.rst:276 +msgid "" +"`Transitioning a native Python package to Anaconda `_" +msgstr "" + +#: ../source/overview.rst:278 +msgid "" +"A similar model involves installing an alternative Python distribution, but " +"does not support arbitrary operating system-level packages:" +msgstr "" + +#: ../source/overview.rst:282 +msgid "" +"`ActiveState ActivePython `_" +msgstr "" + +#: ../source/overview.rst:283 +msgid "`WinPython `_" +msgstr "" + +#: ../source/overview.rst:288 +msgid "Bringing your own Python executable" +msgstr "" + +#: ../source/overview.rst:290 +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." +msgstr "" + +#: ../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 "" + +#: ../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/overview.rst:303 +msgid "A selection of Python freezers:" +msgstr "" + +#: ../source/overview.rst:305 +msgid "" +"`pyInstaller `_ - Cross-" +"platform" +msgstr "" + +#: ../source/overview.rst:306 +msgid "" +"`cx_Freeze `_ - Cross-platform" +msgstr "" + +#: ../source/overview.rst:307 +msgid "" +"`constructor `_ - For command-line " +"installers" +msgstr "" + +#: ../source/overview.rst:308 +msgid "`py2exe `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:309 +msgid "`py2app `_ - Mac only" +msgstr "" + +#: ../source/overview.rst:310 +msgid "`osnap `_ - Windows and Mac" +msgstr "" + +#: ../source/overview.rst:311 +msgid "`pynsist `_ - Windows only" +msgstr "" + +#: ../source/overview.rst:313 +msgid "" +"Most of the above imply single-user deployments. For multi-component server " +"applications, see :gh:`Chef Omnibus `." +msgstr "" + +#: ../source/overview.rst:319 +msgid "Bringing your own userspace" +msgstr "" + +#: ../source/overview.rst:321 +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*." +msgstr "" + +#: ../source/overview.rst:328 +msgid "" +"These techniques are mostly Python agnostic, because they package whole OS " +"filesystems, not just Python or Python packages." +msgstr "" + +#: ../source/overview.rst:331 +msgid "" +"Adoption is most extensive among Linux servers, where the technology " +"originated and where the technologies below work best:" +msgstr "" + +#: ../source/overview.rst:334 +msgid "`AppImage `_" +msgstr "" + +#: ../source/overview.rst:335 +msgid "`Docker `_" +msgstr "" + +#: ../source/overview.rst:336 +msgid "`Flatpak `_" +msgstr "" + +#: ../source/overview.rst:337 +msgid "`Snapcraft `_" +msgstr "" + +#: ../source/overview.rst:340 +msgid "Bringing your own kernel" +msgstr "" + +#: ../source/overview.rst:342 +msgid "" +"Most desktop 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 "" + +#: ../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:" +msgstr "" + +#: ../source/overview.rst:351 +msgid "KVM on Linux" +msgstr "" + +#: ../source/overview.rst:352 +msgid "Hyper-V on Windows" +msgstr "" + +#: ../source/overview.rst:353 +msgid "" +"`VHD `_, `AMI `_, and :doc:`other formats " +"`" +msgstr "" + +#: ../source/overview.rst:356 +msgid "" +"`OpenStack `_ - A cloud " +"management system written in Python, with extensive VM support" +msgstr "" + +#: ../source/overview.rst:360 +msgid "Bringing your own hardware" +msgstr "" + +#: ../source/overview.rst:362 +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." +msgstr "" + +#: ../source/overview.rst:366 +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/overview.rst:370 +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 "" + +#: ../source/overview.rst:379 +msgid "A summary of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:379 +msgid "" +"The simplified gamut of technologies used to package Python applications." +msgstr "" + +#: ../source/overview.rst:382 +msgid "What about..." +msgstr "" + +#: ../source/overview.rst:384 +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:388 +msgid "Operating system packages" +msgstr "" + +#: ../source/overview.rst:390 +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 "" + +#: ../source/overview.rst:401 +msgid "" +"In most deployment pipelines, the OS package manager is just one piece of " +"the puzzle." +msgstr "" + +#: ../source/overview.rst:407 +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." +msgstr "" + +#: ../source/overview.rst:416 +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." +msgstr "" + +#: ../source/overview.rst:421 +msgid "Security" +msgstr "安全" + +#: ../source/overview.rst:423 +msgid "" +"The further down the gradient you come, the harder it gets to update " +"components of your package. Everything is more tightly bound together." +msgstr "" + +#: ../source/overview.rst:426 +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 `_." +msgstr "" + +#: ../source/overview.rst:435 +msgid "Wrap up" +msgstr "" + +#: ../source/overview.rst:437 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:7 +msgid "Binary distribution format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:9 +msgid "" +"This page specifies the binary distribution format for Python packages, also " +"called the wheel format." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:12 +msgid "" +"A wheel is a ZIP-format archive with a specially formatted file name and the " +"``.whl`` extension. It contains a single distribution nearly as it would be " +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:22 +msgid "Details" +msgstr "詳細資訊" + +#: ../source/specifications/binary-distribution-format.rst:25 +msgid "Installing a wheel 'distribution-1.0-py32-none-any.whl'" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:27 +msgid "Wheel installation notionally consists of two phases:" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:32 +msgid "" +"Check that installer is compatible with Wheel-Version. Warn if minor " +"version is greater, abort if major version is greater." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:34 +msgid "" +"If Root-Is-Purelib == 'true', unpack archive into purelib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:36 +msgid "Else unpack archive into platlib (site-packages)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:38 +msgid "Spread." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:40 +msgid "" +"Unpacked archive includes ``distribution-1.0.dist-info/`` and (if there is " +"data) ``distribution-1.0.data/``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:42 +msgid "" +"Move each subtree of ``distribution-1.0.data/`` onto its destination path. " +"Each subdirectory of ``distribution-1.0.data/`` is a key into a dict of " +"destination directories, such as ``distribution-1.0.data/(purelib|platlib|" +"headers|scripts|data)``. These subdirectories are :ref:`installation paths " +"defined by sysconfig `." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:48 +msgid "" +"If applicable, update scripts starting with ``#!python`` to point to the " +"correct interpreter." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:50 +msgid "Update ``distribution-1.0.dist-info/RECORD`` with the installed paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:52 +msgid "Remove empty ``distribution-1.0.data`` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:53 +msgid "" +"Compile any installed .py to .pyc. (Uninstallers should be smart enough to " +"remove .pyc even if it is not mentioned in RECORD.)" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:57 +msgid "Recommended installer features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:67 +msgid "Rewrite ``#!python``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:60 +msgid "" +"In wheel, scripts are packaged in ``{distribution}-{version}.data/scripts/" +"``. If the first line of a file in ``scripts/`` starts with exactly ``b'#!" +"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 "" + +#: ../source/specifications/binary-distribution-format.rst:66 +msgid "" +"The ``b'#!pythonw'`` convention is allowed. ``b'#!pythonw'`` indicates a GUI " +"script instead of a console script." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:72 +msgid "Generate script wrappers." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:70 +msgid "" +"In wheel, scripts packaged on Unix systems will certainly not have " +"accompanying .exe wrappers. Windows installers may want to add them during " +"install." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:75 +msgid "Recommended archiver features" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:82 +msgid "Place ``.dist-info`` at the end of the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:78 +msgid "" +"Archivers are encouraged to place the ``.dist-info`` files physically at the " +"end of the archive. This enables some potentially interesting ZIP tricks " +"including the ability to amend the metadata without rewriting the entire " +"archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:85 +#: ../source/specifications/pylock-toml.rst:51 +msgid "File Format" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:90 +msgid "File name convention" +msgstr "" + +#: ../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:96 +msgid "distribution" +msgstr "distribution" + +#: ../source/specifications/binary-distribution-format.rst:96 +msgid "Distribution name, e.g. 'django', 'pyramid'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "version" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:99 +msgid "Distribution version, e.g. 1.0." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:124 +msgid "build tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:102 +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``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:109 +msgid "" +"A common use-case for build numbers is rebuilding a binary distribution due " +"to a change in the build environment, like when using the manylinux image to " +"build distributions using pre-release CPython versions." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:116 +msgid "" +"Build numbers are not a part of the distribution version and thus are " +"difficult to reference externally, especially so outside the Python " +"ecosystem of tools and standards. A common case where a distribution would " +"need to referenced externally is when resolving a security vulnerability." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:121 +msgid "" +"Due to this limitation, new distributions which need to be referenced " +"externally **should not** use build numbers when building the new " +"distribution. Instead a **new distribution version** should be created for " +"such cases." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "language implementation and version tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:127 +msgid "E.g. 'py27', 'py2', 'py3'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +#: ../source/specifications/platform-compatibility-tags.rst:20 +msgid "abi tag" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:130 +msgid "E.g. 'cp33m', 'abi3', 'none'." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:135 +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." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:145 +msgid "Escaping and Unicode" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:150 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:157 +msgid "" +"Version numbers should be normalised according to the :ref:`Version " +"specifier specification `. Normalised version numbers " +"cannot contain ``-``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:159 +msgid "" +"The remaining components may not contain ``-`` characters, so no escaping is " +"necessary." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/binary-distribution-format.rst:165 +msgid "" +"The archive filename is Unicode. It will be some time before the tools are " +"updated to support non-ASCII filenames, but they are supported in this " +"specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:169 +msgid "" +"The filenames *inside* the archive are encoded as UTF-8. Although some ZIP " +"clients in common use do not properly display UTF-8 filenames, the encoding " +"is supported by both the ZIP specification and Python's ``zipfile``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:175 +msgid "File contents" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:177 +msgid "" +"The contents of a wheel file, where {distribution} is replaced with " +"the :ref:`normalized name ` of the package, e.g. " +"``beaglevote`` and {version} is replaced with its :ref:`normalized version " +"`, e.g. ``1.0.0``, (with dash/``-`` " +"characters replaced with underscore/``_`` characters in both fields) consist " +"of:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:184 +msgid "" +"``/``, the root of the archive, contains all files to be installed in " +"``purelib`` or ``platlib`` as specified in ``WHEEL``. ``purelib`` and " +"``platlib`` are usually both ``site-packages``." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:187 +msgid "``{distribution}-{version}.dist-info/`` contains metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:188 +msgid "" +":file:`{distribution}-{version}.dist-info/licenses/` contains license files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:189 +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``)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:193 +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. The " +"``scripts`` directory may only contain regular files." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:197 +msgid "" +"``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.1 or " +"greater format metadata." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:199 +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:209 +msgid "``Wheel-Version`` is the version number of the Wheel specification." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:210 +msgid "" +"``Generator`` is the name and optionally the version of the software that " +"produced the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:212 +msgid "" +"``Root-Is-Purelib`` is true if the top level directory of the archive should " +"be installed into purelib; otherwise the root should be installed into " +"platlib." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:215 +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:217 +msgid "" +"``Build`` is the build number and is omitted if there is no build number." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:218 +msgid "" +"A wheel installer should warn if Wheel-Version is greater than the version " +"it supports, and must fail if Wheel-Version has a greater major version than " +"the version it supports." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:221 +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:223 +msgid "Wheel does not contain setup.py or setup.cfg." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:225 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:232 +#: ../source/specifications/recording-installed-packages.rst:23 +msgid "The .dist-info directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:234 +msgid "" +"Wheel .dist-info directories include at a minimum METADATA, WHEEL, and " +"RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:236 +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:238 +msgid "WHEEL is the wheel metadata specific to a build of the package." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:239 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:244 +msgid "PEP 376's INSTALLER and REQUESTED are not included in the archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:245 +msgid "" +"RECORD.jws and RECORD.p7s are deprecated. Where they are still used, " +"neither RECORD.jws nor RECORD.p7s are mentioned in RECORD. Build backends " +"and other tools must not add them to wheels anymore, installers should be " +"aware that these files may still be part of some wheels." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:250 +msgid "" +"During extraction, wheel installers verify all the hashes in RECORD against " +"the file contents. Apart from RECORD, RECORD.jws and RECORD.p7s, " +"installation will fail if any file in the archive is not both mentioned and " +"correctly hashed in RECORD." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:256 +msgid "Subdirectories in :file:`.dist-info/`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:258 +msgid "" +"Subdirectories under :file:`.dist-info/` are reserved for future use. The " +"following subdirectory names under :file:`.dist-info/` are reserved for " +"specific usage:" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:262 +#, fuzzy +#| msgid "Project name" +msgid "Subdirectory name" +msgstr "專案名稱" + +#: ../source/specifications/binary-distribution-format.rst:262 +msgid "PEP / Standard" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:264 +#, fuzzy +#| msgid "License" +msgid "``licenses``" +msgstr "許可證" + +#: ../source/specifications/binary-distribution-format.rst:264 +#: ../source/specifications/binary-distribution-format.rst:265 +msgid ":pep:`639`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:265 +msgid "``license_files``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:266 +#, fuzzy +#| msgid "``LIB``" +msgid "``LICENSES``" +msgstr "``LIB``" + +#: ../source/specifications/binary-distribution-format.rst:266 +msgid "`REUSE licensing framework `__" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid "``sboms``" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:267 +msgid ":pep:`770`" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:271 +msgid "The :file:`.dist-info/licenses/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:273 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory, which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:280 +msgid "The :file:`.dist-info/sboms/` directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:282 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the distribution archive." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:287 +msgid "The .data directory" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:289 +msgid "" +"Any file that is not normally installed inside site-packages goes into " +"the .data directory, named as the .dist-info directory but with the .data/ " +"extension::" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:297 +msgid "" +"The .data directory contains subdirectories with the scripts, headers, " +"documentation and so forth from the distribution. During installation the " +"contents of these subdirectories are moved onto their destination paths." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:303 +#: ../source/specifications/platform-compatibility-tags.rst:376 +msgid "FAQ" +msgstr "常見問題" + +#: ../source/specifications/binary-distribution-format.rst:307 +msgid "Wheel defines a .data directory. Should I put all my data there?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:309 +msgid "" +"This specification does not have an opinion on how you should organize your " +"code. The .data directory is just a place for any files that are not " +"normally installed inside ``site-packages`` or on the PYTHONPATH. In other " +"words, you may continue to use ``pkgutil.get_data(package, resource)`` even " +"though *those* files will usually not be distributed in *wheel's* ``.data`` " +"directory." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:318 +msgid "What's the deal with \"purelib\" vs. \"platlib\"?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:320 +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'." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:325 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:330 +msgid "" +"In practice a wheel should have only one of \"purelib\" or \"platlib\" " +"depending on whether it is pure Python or not and those files should be at " +"the root with the appropriate setting given for \"Root-is-purelib\"." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:338 +msgid "Is it possible to import Python code directly from a wheel file?" +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:340 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:346 +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)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:355 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:372 +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." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:380 +#: ../source/specifications/core-metadata.rst:1035 +#: ../source/specifications/dependency-groups.rst:250 +#: ../source/specifications/dependency-specifiers.rst:516 +#: ../source/specifications/direct-url-data-structure.rst:292 +#: ../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:213 +#: ../source/specifications/name-normalization.rst:50 +#: ../source/specifications/platform-compatibility-tags.rst:440 +#: ../source/specifications/pylock-toml.rst:826 +#: ../source/specifications/pyproject-toml.rst:632 +#: ../source/specifications/recording-installed-packages.rst:278 +#: ../source/specifications/simple-repository-api.rst:974 +#: ../source/specifications/source-distribution-format.rst:153 +#: ../source/specifications/version-specifiers.rst:1285 +#: ../source/specifications/virtual-environments.rst:54 +msgid "History" +msgstr "歷史" + +#: ../source/specifications/binary-distribution-format.rst:382 +msgid "February 2013: This specification was approved through :pep:`427`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:383 +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:385 +msgid "" +"December 2024: Clarified that the ``scripts`` folder should only contain " +"regular files (the expected behaviour of consuming tools when encountering " +"symlinks or subdirectories in this folder is not formally defined, and hence " +"may vary between tools)." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:389 +#: ../source/specifications/recording-installed-packages.rst:288 +msgid "" +"December 2024: The :file:`.dist-info/licenses/` directory was specified " +"through :pep:`639`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:391 +msgid "" +"January 2025: Clarified that name and version needs to be normalized for " +"``.dist-info`` and ``.data`` directories." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:393 +msgid "January 2026: Deprecate RECORD.jws and RECORD.p7s :pep:`815`." +msgstr "" + +#: ../source/specifications/binary-distribution-format.rst:397 +msgid "Appendix" +msgstr "附錄" + +#: ../source/specifications/binary-distribution-format.rst:399 +msgid "Example urlsafe-base64-nopad implementation::" +msgstr "" + +#: ../source/specifications/build-details/index.rst:7 +#: ../source/specifications/build-details/index.rst:41 +msgid "v1.0" +msgstr "" + +#: ../source/specifications/build-details/index.rst:5 +msgid ":file:`build-details.json`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:13 +msgid "" +"The ``build-details.json`` file is a standardized file format that provides " +"build-specfic information of a Python installation, such as its version, " +"extension ABI details, and other information that is specific to that " +"particular build of Python." +msgstr "" + +#: ../source/specifications/build-details/index.rst:18 +msgid "" +"Starting from Python 3.14, a ``build-details.json`` file is installed in the " +"platform-independent standard library directory (``stdlib``, e.g. ``/usr/lib/" +"python3.14/build-details.json``)." +msgstr "" + +#: ../source/specifications/build-details/index.rst:22 +msgid "" +"Please refer to the :ref:`latest version ` for its " +"specification." +msgstr "" + +#: ../source/specifications/build-details/index.rst:28 +#: ../source/specifications/build-details/v1.0.rst:16 +#: ../source/specifications/inline-script-metadata.rst:100 +#: ../source/specifications/pylock-toml.rst:722 +msgid "Example" +msgstr "" + +#: ../source/specifications/build-details/index.rst:35 +msgid "Changelog" +msgstr "" + +#: ../source/specifications/build-details/index.rst:45 +#: ../source/specifications/build-details/v1.0.rst:9 +#: ../source/specifications/dependency-groups.rst:20 +#: ../source/specifications/dependency-specifiers.rst:26 +#: ../source/specifications/direct-url-data-structure.rst:19 +#: ../source/specifications/direct-url.rst:15 +#: ../source/specifications/file-yanking.rst:20 +#: ../source/specifications/index-hosted-attestations.rst:17 +#: ../source/specifications/inline-script-metadata.rst:13 +#: ../source/specifications/license-expression.rst:12 +#: ../source/specifications/project-status-markers.rst:20 +msgid "Specification" +msgstr "規格" + +#: ../source/specifications/build-details/index.rst:46 +msgid ":ref:`build-details-v1.0`" +msgstr "" + +#: ../source/specifications/build-details/index.rst:48 +msgid "Schema" +msgstr "" + +#: ../source/specifications/build-details/index.rst:49 +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"https://packaging.python.org/en/latest/specifications/schemas/build-details-" +"v1.0.schema.json" +msgstr "" + +#: ../source/specifications/build-details/index.rst:52 +msgid "Initial version, introduced by :pep:`739`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:5 +msgid "``build-details.json`` v1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"*build-details.json — a static description file with build details of Python " +"installations*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "type" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Project" +msgid "*object*" +msgstr "專案" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "properties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**schema\\_version**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Python version" +msgid "Schema version." +msgstr "Python 版本" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is a string following the format ``.``, where ```` " +"and ```` are unpaded numbers and represent the **major** and " +"**minor** components of the version. Versions may be arithmetically compared " +"by intrepreting the version string as a decimal number." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"For this specification version, this value is constant and **MUST** be " +"``1.0``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Future versions of this schema **MUST** use a higher version number. Future " +"versions of this schema **MUST NOT** use the same **major** version " +"component as other schema version unless its specification is deemed " +"backwards-compatible with them — it can't change, or extend, any parts of " +"the current specification in such a way as the semantics of the interpreted " +"data differ, or that data valid under the new specification is invalid under " +"the older specification, with the exception of additional properties (errors " +"caused by ``additionalProperties``)." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*string*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "const" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**base\\_prefix**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Base prefix of the Python installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Either an absolute path, or a path relative to directory where this file is " +"contained." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Examples" +msgid "examples" +msgstr "例子" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "../.." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "base\\_interpreter" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the Python interprer of the base installation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Either an absolute path, or a path relative to ``base_prefix``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the installation provides an interpreter " +"executable." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/bin/python" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "python" +msgid "bin/python" +msgstr "python" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**platform**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "System platform string." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This field **SHOULD** be equivalent to ``sysconfig.get_platform()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "linux-x86\\_64" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**language**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python language specification." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Versions" +msgid "**version**" +msgstr "版本" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"String representation the Python language version — a version string " +"consisting only of the *major* and *minor* components." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **SHOULD** be equivalent to ``sysconfig.get_python_version()``." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +msgid "version\\_info" +msgstr "翻譯" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object in the format of :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "This section **SHOULD** be equivalent to :py:data:`sys.version_info`." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "major" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "3" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "minor" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "micro" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "1" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Release" +msgid "releaselevel" +msgstr "發行版本" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Mercurial" +msgid "serial" +msgstr "Mercurial" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**major**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*number*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**minor**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**micro**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**releaselevel**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "enum" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "alpha, beta, candidate, final" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**serial**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "additionalProperties" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "False" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Documentation types" +msgid "**implementation**" +msgstr "文件類型" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **SHOULD** be equivalent to :py:data:`sys.implementation`. It " +"follows specification defined in PEP 421, meaning that on top of the " +"required keys, implementation-specific keys can also exist, but must be " +"prefixed with an underscore." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**name**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Lower-case name of the Python implementation." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "python" +msgid "cpython" +msgstr "python" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pypy" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Object in the format of :py:data:`sys.version_info`, containing the " +"implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "7" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "16" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "True" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "abi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "**Headings**" +msgid "**flags**" +msgstr "**標題**" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Build configuration flags, used to calculate the extension suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"The flags **MUST** be defined in the order they appear on the extension " +"suffix." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*array*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "t" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "d" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "extension\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Suffix used for extensions built against the current implementation version." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation supports " +"extensions, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-314-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "stable\\_abi\\_suffix" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Suffix used for extensions built against the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation has a stable ABI " +"extension suffix, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".abi3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "suffixes" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Valid module suffixes grouped by type." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python installation supports " +"importing external files, and it **SHOULD** be equivalent to the " +"``importlib.machinery.*_SUFFIXES`` attributes." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"Additionally, if a Python implementation provides extension kinds other than " +"the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-" +"section for them." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "source" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".py" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".pyc" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "optimized_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "debug_bytecode" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "Versions" +msgid "extensions" +msgstr "版本" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".cpython-313-x86\\_64-linux-gnu.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid ".so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +#, fuzzy +#| msgid "python" +msgid "libpython" +msgstr "python" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** by present if Python installation provides a " +"``libpython`` library, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.14.so.1.0" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "dynamic\\_stableabi" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the dynamic ``libpython`` library for the stable ABI." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a dynamic " +"``libpython`` library targeting the Stable ABI, otherwise this entry will be " +"missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "If this key is present ``dynamic`` **MUST** also be set." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/libpython3.so" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "static" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the static ``libpython`` library." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python installation provides a static " +"``libpython`` library, otherwise this entry will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/python3.14/config-3.14-x86\\_64-linux-gnu/libpython3.14.a" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "link\\_extensions" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Should extensions built against a dynamic ``libpython`` link to it?" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "*boolean*" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "c\\_api" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing details related to the Python C API." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This section **MUST** be present if the Python implementation provides a C " +"API, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "**headers**" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the C API headers." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "include/python3.14" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "pkgconfig\\_path" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "The path to the pkg-config definition files." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This field **MUST** be present if the Python implementation provides pkg-" +"config definition files, otherwise this section will be missing." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "/usr/lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "lib/pkgconfig" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "arbitrary\\_data" +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "Object containing extra arbitrary data." +msgstr "" + +#: ../source/specifications/build-details/v1.0.rst:12 +msgid "" +"This is meant to be used as an escape-hatch, to include any relevant data " +"that is not covered by this specification. Implementations may choose what " +"data to provide in this section." +msgstr "" + +#: ../source/specifications/core-metadata.rst:7 +msgid "Core metadata specifications" +msgstr "" + +#: ../source/specifications/core-metadata.rst:9 +msgid "This page describes version 2.5, approved in September 2025." +msgstr "" + +#: ../source/specifications/core-metadata.rst:11 +msgid "" +"Fields defined in the following specification should be considered valid, " +"complete and not subject to change. The required fields are:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:14 +msgid "``Metadata-Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:15 +msgid "``Name``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:16 +msgid "``Version``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:18 +msgid "All the other fields are optional." +msgstr "" + +#: ../source/specifications/core-metadata.rst:20 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:29 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:32 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:37 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:48 +msgid "Metadata-Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:52 +msgid "" +"Version of the file format; legal values are \"1.0\", \"1.1\", \"1.2\", " +"\"2.1\", \"2.2\", \"2.3\", \"2.4\", and \"2.5\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:55 +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)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:62 +msgid "" +"For broader compatibility, build tools MAY choose to produce distribution " +"metadata using the lowest metadata version that includes all of the needed " +"fields." +msgstr "" + +#: ../source/specifications/core-metadata.rst:66 +#: ../source/specifications/core-metadata.rst:84 +#: ../source/specifications/core-metadata.rst:101 +#: ../source/specifications/core-metadata.rst:176 +#: ../source/specifications/core-metadata.rst:191 +#: ../source/specifications/core-metadata.rst:229 +#: ../source/specifications/core-metadata.rst:301 +#: ../source/specifications/core-metadata.rst:305 +#: ../source/specifications/core-metadata.rst:309 +#: ../source/specifications/core-metadata.rst:313 +#: ../source/specifications/core-metadata.rst:345 +#: ../source/specifications/core-metadata.rst:367 +#: ../source/specifications/core-metadata.rst:385 +#: ../source/specifications/core-metadata.rst:410 +#: ../source/specifications/core-metadata.rst:432 +#: ../source/specifications/core-metadata.rst:658 +#: ../source/specifications/core-metadata.rst:693 +#: ../source/specifications/core-metadata.rst:703 +#: ../source/specifications/core-metadata.rst:932 +#: ../source/specifications/core-metadata.rst:1029 +msgid "Example::" +msgstr "例子::" + +#: ../source/specifications/core-metadata.rst:74 +msgid "Name" +msgstr "" + +#: ../source/specifications/core-metadata.rst:77 +msgid "Added restrictions on format from the :ref:`name format `." +msgstr "" + +#: ../source/specifications/core-metadata.rst:80 +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 "" + +#: ../source/specifications/core-metadata.rst:88 +msgid "" +"For comparison purposes, the names should be :ref:`normalized ` before comparing." +msgstr "" + +#: ../source/specifications/core-metadata.rst:93 +msgid "Version" +msgstr "" + +#: ../source/specifications/core-metadata.rst:97 +msgid "" +"A string containing the distribution's version number. This field must be " +"in the format specified in the :ref:`Version specifier specification " +"`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:109 +msgid "Dynamic (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:113 +msgid "" +"A string containing the name of another core metadata field. The field names " +"``Name``, ``Version``, and ``Metadata-Version`` may not be specified in this " +"field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:117 +msgid "" +"When found in the metadata of a source distribution, the following rules " +"apply:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:120 +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 "" + +#: ../source/specifications/core-metadata.rst:124 +msgid "" +"If a field is marked as ``Dynamic``, it may contain any valid value in a " +"wheel built from the sdist (including not being present at all)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:127 +msgid "" +"If the sdist metadata version is older than version 2.2, then all fields " +"should be treated as if they were specified with ``Dynamic`` (i.e. there are " +"no special restrictions on the metadata of wheels built from the sdist)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:131 +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 "" + +#: ../source/specifications/core-metadata.rst:136 +msgid "" +"Note in particular that if you have obtained a prebuilt wheel, you cannot " +"assume that a field which is not marked as ``Dynamic`` will have the same " +"value in other wheels, as some wheels are not built directly from the sdist, " +"but are modified from existing wheels (the ``auditwheel`` tool does this, " +"for example, and it's commonly used when building wheels for PyPI). Such " +"modifications *could* include changing metadata (even non-dynamic " +"metadata). Similarly, if you have a sdist and a wheel which you didn't " +"build from that sdist, you cannot assume that the wheel's metadata matches " +"that of the sdist, even if the field is not marked as ``Dynamic``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:146 +msgid "" +"Full details of the semantics of ``Dynamic`` are described in :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:151 +msgid "Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:155 +msgid "" +"A Platform specification describing an operating system supported by the " +"distribution which is not listed in the \"Operating System\" Trove " +"classifiers. See \"Classifier\" below." +msgstr "" + +#: ../source/specifications/core-metadata.rst:159 +#: ../source/specifications/core-metadata.rst:465 +#: ../source/specifications/core-metadata.rst:492 +#: ../source/specifications/core-metadata.rst:515 +#: ../source/specifications/core-metadata.rst:544 +#: ../source/specifications/core-metadata.rst:585 +#: ../source/specifications/core-metadata.rst:641 +#: ../source/specifications/core-metadata.rst:775 +#: ../source/specifications/core-metadata.rst:816 +#: ../source/specifications/core-metadata.rst:873 +#: ../source/specifications/core-metadata.rst:903 +#: ../source/specifications/core-metadata.rst:983 +#: ../source/specifications/core-metadata.rst:1005 +msgid "Examples::" +msgstr "例子::" + +#: ../source/specifications/core-metadata.rst:167 +msgid "Supported-Platform (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:171 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:185 +msgid "Summary" +msgstr "" + +#: ../source/specifications/core-metadata.rst:189 +msgid "A one-line summary of what the distribution does." +msgstr "" + +#: ../source/specifications/core-metadata.rst:209 +msgid "This field may be specified in the message body instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:212 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:217 +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 "" + +#: ../source/specifications/core-metadata.rst:223 +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]_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:240 +msgid "" +"This encoding implies that any occurrences of a CRLF followed by 7 spaces " +"and a pipe char have to be replaced by a single CRLF when the field is " +"unfolded using a RFC822 reader." +msgstr "" + +#: ../source/specifications/core-metadata.rst:244 +msgid "" +"Alternatively, the distribution's description may instead be provided in the " +"message body (i.e., after a completely blank line following the headers, " +"with no indentation or other special formatting necessary)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:253 +msgid "Description-Content-Type" +msgstr "" + +#: ../source/specifications/core-metadata.rst:257 +msgid "" +"A string stating the markup syntax (if any) used in the distribution's " +"description, so that tools can intelligently render the description." +msgstr "" + +#: ../source/specifications/core-metadata.rst:260 +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 "" + +#: ../source/specifications/core-metadata.rst:273 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:279 +msgid "Format::" +msgstr "格式::" + +#: ../source/specifications/core-metadata.rst:283 +msgid "The ``type/subtype`` part has only a few legal values:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:285 +msgid "``text/plain``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:286 +msgid "``text/x-rst``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:287 +msgid "``text/markdown``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:289 +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``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:293 +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:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:298 +msgid "``GFM`` for :rfc:`GitHub-flavored Markdown <7764#section-3.2>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:299 +msgid "``CommonMark`` for :rfc:`CommonMark <7764#section-3.5>`" +msgstr "" + +#: ../source/specifications/core-metadata.rst:317 +msgid "" +"If a ``Description-Content-Type`` is not specified, then applications should " +"attempt to render it as ``text/x-rst; charset=UTF-8`` and fall back to " +"``text/plain`` if it is not valid rst." +msgstr "" + +#: ../source/specifications/core-metadata.rst:321 +msgid "" +"If a ``Description-Content-Type`` is an unrecognized value, then the assumed " +"content type is ``text/plain`` (Although PyPI will probably reject anything " +"with an unrecognized value)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:325 +msgid "" +"If the ``Description-Content-Type`` is ``text/markdown`` and ``variant`` is " +"not specified or is set to an unrecognized value, then the assumed " +"``variant`` is ``GFM``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:329 +msgid "" +"So for the last example above, the ``charset`` defaults to ``UTF-8`` and the " +"``variant`` defaults to ``GFM`` and thus it is equivalent to the example " +"before it." +msgstr "" + +#: ../source/specifications/core-metadata.rst:338 +msgid "Keywords" +msgstr "關鍵字" + +#: ../source/specifications/core-metadata.rst:342 +msgid "" +"A list of additional keywords, separated by commas, to be used to assist " +"searching for the distribution in a larger catalog." +msgstr "" + +#: ../source/specifications/core-metadata.rst:351 +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 "" + +#: ../source/specifications/core-metadata.rst:360 +msgid "Author" +msgstr "作者" + +#: ../source/specifications/core-metadata.rst:364 +msgid "" +"A string containing the author's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:377 +msgid "Author-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:381 +msgid "" +"A string containing the author's e-mail address. It can contain a name and " +"e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:389 +#: ../source/specifications/core-metadata.rst:436 +msgid "" +"Per RFC-822, this field may contain multiple comma-separated e-mail " +"addresses::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:399 +msgid "Maintainer" +msgstr "維護者" + +#: ../source/specifications/core-metadata.rst:403 +msgid "" +"A string containing the maintainer's name at a minimum; additional contact " +"information may be provided." +msgstr "" + +#: ../source/specifications/core-metadata.rst:406 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:420 +msgid "Maintainer-email" +msgstr "" + +#: ../source/specifications/core-metadata.rst:424 +msgid "" +"A string containing the maintainer's e-mail address. It can contain a name " +"and e-mail address in the legal forms for a RFC-822 ``From:`` header." +msgstr "" + +#: ../source/specifications/core-metadata.rst:428 +msgid "" +"Note that this field is intended for use when a project is being maintained " +"by someone other than the original author: it should be omitted if it is " +"identical to ``Author-email``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:446 +msgid "License" +msgstr "許可證" + +#: ../source/specifications/core-metadata.rst:449 +msgid "in favour of ``License-Expression``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:453 +msgid "" +"As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually " +"exclusive. If both are specified, tools which parse metadata will disregard " +"``License`` and PyPI will reject uploads. See `PEP 639 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:458 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:478 +msgid "License-Expression" +msgstr "" + +#: ../source/specifications/core-metadata.rst:482 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:486 +msgid "" +"Note that the expression in this field only applies to " +"the :term:`Distribution Archive` containing the metadata with this field " +"(e.g., :term:`Source Distribution ` " +"or :term:`Wheel`), not the project overall or other files related to the " +"project (including other distribution archives)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:507 +msgid "License-File (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:511 +msgid "" +"Each entry is a string representation of the path of a license-related file. " +"The path is located within the project source tree, relative to the project " +"root directory. For details see :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:528 +msgid "Classifier (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:532 +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 "" + +#: ../source/specifications/core-metadata.rst:538 +msgid "" +"The use of ``License ::`` classifiers is deprecated as of Metadata 2.4, use " +"``License-Expression`` instead. See `PEP 639 `_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:542 +#: ../source/specifications/core-metadata.rst:632 +#: ../source/specifications/core-metadata.rst:871 +#: ../source/specifications/core-metadata.rst:896 +msgid "This field may be followed by an environment marker after a semicolon." +msgstr "" + +#: ../source/specifications/core-metadata.rst:553 +msgid "Requires-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:556 +#: ../source/specifications/core-metadata.rst:619 +#: ../source/specifications/core-metadata.rst:843 +#: ../source/specifications/core-metadata.rst:885 +msgid "" +"The field format specification was relaxed to accept the syntax used by " +"popular publishing tools." +msgstr "" + +#: ../source/specifications/core-metadata.rst:560 +msgid "" +"Each entry contains a string naming some other distutils project required by " +"this distribution." +msgstr "" + +#: ../source/specifications/core-metadata.rst:563 +msgid "The format of a requirement string contains from one to four parts:" +msgstr "" + +#: ../source/specifications/core-metadata.rst:565 +msgid "" +"A project name, in the same format as the ``Name:`` field. The only " +"mandatory part." +msgstr "" + +#: ../source/specifications/core-metadata.rst:567 +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 "" + +#: ../source/specifications/core-metadata.rst:571 +msgid "" +"A version specifier. Tools parsing the format should accept optional " +"parentheses around this, but tools generating it should not use parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:574 +msgid "" +"An environment marker after a semicolon. This means that the requirement is " +"only needed in the specified conditions." +msgstr "" + +#: ../source/specifications/core-metadata.rst:577 +msgid "See :pep:`508` for full details of the allowed format." +msgstr "" + +#: ../source/specifications/core-metadata.rst:579 +msgid "" +"The project names should correspond to names as found on the `Python Package " +"Index`_." +msgstr "" + +#: ../source/specifications/core-metadata.rst:582 +msgid "" +"Version specifiers must follow the rules described in :doc:`version-" +"specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:596 +msgid "Requires-Python" +msgstr "" + +#: ../source/specifications/core-metadata.rst:600 +msgid "" +"This field specifies the Python version(s) that the distribution is " +"compatible with. Installation tools may look at this when picking which " +"version of a project to install." +msgstr "" + +#: ../source/specifications/core-metadata.rst:604 +msgid "The value must be in the format specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:606 +msgid "" +"For example, if a distribution uses :ref:`f-strings ` " +"then it may prevent installation on Python < 3.6 by specifying::" +msgstr "" + +#: ../source/specifications/core-metadata.rst:611 +msgid "This field cannot be followed by an environment marker." +msgstr "" + +#: ../source/specifications/core-metadata.rst:616 +msgid "Requires-External (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:623 +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 "" + +#: ../source/specifications/core-metadata.rst:628 +msgid "" +"The format of a requirement string is a name of an external dependency, " +"optionally followed by a version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:634 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:639 +msgid "Notice that there is no particular rule on the strings to be used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:651 +msgid "Project-URL (multiple-use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:655 +msgid "" +"A string containing a browsable URL for the project and a label for it, " +"separated by a comma." +msgstr "" + +#: ../source/specifications/core-metadata.rst:662 +msgid "The label is free text limited to 32 characters." +msgstr "" + +#: ../source/specifications/core-metadata.rst:664 +msgid "" +"Starting with :pep:`753`, project metadata consumers (such as the Python " +"Package Index) can use a standard normalization process to discover \"well-" +"known\" labels, which can then be given special presentations when being " +"rendered for human consumption. See :ref:`well-known-project-urls`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:674 +msgid "Provides-Extra (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:677 +msgid "" +":pep:`685` restricted valid values to be unambiguous (i.e. no normalization " +"required). For older metadata versions, value restrictions were brought into " +"line with ``Name:`` and normalization rules were introduced." +msgstr "" + +#: ../source/specifications/core-metadata.rst:682 +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 "" + +#: ../source/specifications/core-metadata.rst:690 +msgid "" +"The specified name may be used to make a dependency conditional on whether " +"the optional feature has been requested." +msgstr "" + +#: ../source/specifications/core-metadata.rst:698 +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/core-metadata.rst:708 +msgid "" +"Two feature names ``test`` and ``doc`` are reserved to mark dependencies " +"that are needed for running automated tests and generating documentation, " +"respectively." +msgstr "" + +#: ../source/specifications/core-metadata.rst:712 +msgid "" +"It is legal to specify ``Provides-Extra:`` without referencing it in any " +"``Requires-Dist:``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:715 +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 "" + +#: ../source/specifications/core-metadata.rst:720 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:730 +msgid "Import-Name (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:734 +msgid "" +"A string containing an import name that the project exclusively provides " +"when installed. The specified import name MUST be a valid Python identifier " +"or can be empty. The import names listed in this field MUST be importable " +"when the project is installed on *some* platform for the same version of the " +"project. This implies that the metadata MUST be consistent across all sdists " +"and wheels for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:741 +#: ../source/specifications/core-metadata.rst:796 +msgid "" +"An import name MAY be followed by a semicolon and the term \"private\" (e.g. " +"``; private``) with any amount of whitespace surrounding the semicolon. This " +"signals to tools that the import name is not part of the public API for the " +"project." +msgstr "" + +#: ../source/specifications/core-metadata.rst:746 +#: ../source/specifications/core-metadata.rst:801 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name SHOULD also be listed " +"appropriately in ``Import-Name`` and/or ``Import-Namespace``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:751 +#: ../source/specifications/core-metadata.rst:811 +msgid "" +"If a project lists the same name in both ``Import-Name`` and ``Import-" +"Namespace``, tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/core-metadata.rst:754 +msgid "" +"Tools SHOULD raise an error when two projects that are about to be installed " +"list names that overlap in each other's ``Import-Name`` entries, or when a " +"project has an entry in ``Import-Name`` that overlaps with another project's " +"``Import-Namespace`` entries. This is to avoid projects unexpectedly " +"shadowing another project's code. Tools MAY warn or raise an error when " +"installing a project into a preexisting environment where there is import " +"name overlap with a project that is already installed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:762 +msgid "" +"Projects MAY have an empty ``Import-Name`` field in their metadata to " +"represent a project with no import names (i.e. there are no Python modules " +"of any kind in the distribution file)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:766 +msgid "" +"Since projects MAY have no ``Import-Name`` metadata (either because the " +"project uses an older metadata version, or because it didn't specify any), " +"then tools have no information about what names the project provides. " +"However, in practice the majority of projects have their project name match " +"what their import name would be. As such, it is a reasonable assumption to " +"make that a project name that is normalized in some way to an import name " +"(e.g. ``packaging.utils.canonicalize_name(name, validate=True).replace(\"-" +"\", \"_\")``) can be used if some answer is needed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:786 +msgid "Import-Namespace (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:790 +msgid "" +"A string containing an import name that the project provides when installed, " +"but not exclusively. The specified import name MUST be a valid Python " +"identifier. This field is used for namespace packages where multiple " +"projects can contribute to the same import namespace. Projects all listing " +"the same import name in ``Import-Namespace`` can be installed together " +"without shadowing each other." +msgstr "" + +#: ../source/specifications/core-metadata.rst:806 +msgid "" +"The import names listed in this field MUST be importable when the project is " +"installed on *some* platform for the same version of the project. This " +"implies that the metadata MUST be consistent across all sdists and wheels " +"for a project release." +msgstr "" + +#: ../source/specifications/core-metadata.rst:814 +msgid "Note that ``Import-Namespace`` CANNOT be empty like ``Import-Name``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:823 +msgid "Rarely Used Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:825 +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 `__." +msgstr "" + +#: ../source/specifications/core-metadata.rst:830 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:840 +msgid "Provides-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:847 +msgid "" +"Each entry contains a string naming a Distutils project which is contained " +"within this distribution. This field *must* include the project identified " +"in the ``Name`` field, followed by the version : Name (Version)." +msgstr "" + +#: ../source/specifications/core-metadata.rst:852 +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 "" + +#: ../source/specifications/core-metadata.rst:859 +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." +msgstr "" + +#: ../source/specifications/core-metadata.rst:867 +msgid "" +"A version declaration may be supplied and must follow the rules described " +"in :doc:`version-specifiers`. The distribution's version number will be " +"implied if none is specified." +msgstr "" + +#: ../source/specifications/core-metadata.rst:882 +msgid "Obsoletes-Dist (multiple use)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:889 +msgid "" +"Each entry contains a string describing a distutils project's distribution " +"which this distribution renders obsolete, meaning that the two projects " +"should not be installed at the same time." +msgstr "" + +#: ../source/specifications/core-metadata.rst:893 +msgid "" +"Version declarations can be supplied. Version numbers must be in the format " +"specified in :doc:`version-specifiers`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:898 +msgid "" +"The most common use of this field will be in case a project name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon distribution should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:911 +msgid "Deprecated Fields" +msgstr "" + +#: ../source/specifications/core-metadata.rst:913 +msgid "" +"Deprecated fields should be avoided, but they are valid metadata fields. " +"They may be removed in future versions of the core metadata standard (at " +"which point they will only be valid in files that specify a metadata version " +"prior to the removal). Tools SHOULD warn users when deprecated fields are " +"used." +msgstr "" + +#: ../source/specifications/core-metadata.rst:922 +msgid "Home-page" +msgstr "" + +#: ../source/specifications/core-metadata.rst:928 +#: ../source/specifications/core-metadata.rst:945 +msgid "Per :pep:`753`, use :ref:`core-metadata-project-url` instead." +msgstr "" + +#: ../source/specifications/core-metadata.rst:930 +msgid "A string containing the URL for the distribution's home page." +msgstr "" + +#: ../source/specifications/core-metadata.rst:939 +msgid "Download-URL" +msgstr "" + +#: ../source/specifications/core-metadata.rst:947 +msgid "" +"A string containing the URL from which this version of the distribution can " +"be downloaded. (This means that the URL can't be something like \"``.../" +"BeagleVote-latest.tgz``\", but instead must be \"``.../" +"BeagleVote-0.45.tgz``\".)" +msgstr "" + +#: ../source/specifications/core-metadata.rst:953 +msgid "Requires" +msgstr "需要" + +#: ../source/specifications/core-metadata.rst:956 +msgid "in favour of ``Requires-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:959 +msgid "" +"Each entry contains a string describing some other module or package " +"required by this package." +msgstr "" + +#: ../source/specifications/core-metadata.rst:962 +msgid "" +"The format of a requirement string is identical to that of a module or " +"package name usable with the ``import`` statement, optionally followed by a " +"version declaration within parentheses." +msgstr "" + +#: ../source/specifications/core-metadata.rst:966 +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\"," +msgstr "" + +#: ../source/specifications/core-metadata.rst:974 +msgid "" +"Any number of conditional operators can be specified, e.g. the string " +"\">1.0, !=1.3.4, <2.0\" is a legal version declaration." +msgstr "" + +#: ../source/specifications/core-metadata.rst:977 +msgid "" +"All of the following are possible requirement strings: \"rfc822\", \"zlib " +"(>=1.1.4)\", \"zope\"." +msgstr "" + +#: ../source/specifications/core-metadata.rst:980 +msgid "" +"There’s no canonical list of what strings should be used; the Python " +"community is left to choose its own standards." +msgstr "" + +#: ../source/specifications/core-metadata.rst:993 +msgid "Provides" +msgstr "提供" + +#: ../source/specifications/core-metadata.rst:996 +msgid "in favour of ``Provides-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:999 +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 "" + +#: ../source/specifications/core-metadata.rst:1015 +msgid "Obsoletes" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1018 +msgid "in favour of ``Obsoletes-Dist``" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1021 +msgid "" +"Each entry contains a string describing a package or module that this " +"package renders obsolete, meaning that the two packages should not be " +"installed at the same time. Version declarations can be supplied." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1025 +msgid "" +"The most common use of this field will be in case a package name changes, " +"e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install " +"Torqued Python, the Gorgon package should be removed." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1037 +msgid "March 2001: Core metadata 1.0 was approved through :pep:`241`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1039 +msgid "April 2003: Core metadata 1.1 was approved through :pep:`314`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1041 +msgid "February 2010: Core metadata 1.2 was approved through :pep:`345`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1043 +msgid "February 2018: Core metadata 2.1 was approved through :pep:`566`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1045 +msgid "Added ``Description-Content-Type`` and ``Provides-Extra``." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1046 +msgid "Added canonical method for transforming metadata to JSON." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1047 +msgid "Restricted the grammar of the ``Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1049 +msgid "October 2020: Core metadata 2.2 was approved through :pep:`643`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1051 +msgid "Added the ``Dynamic`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1053 +msgid "March 2022: Core metadata 2.3 was approved through :pep:`685`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1055 +msgid "Restricted extra names to be normalized." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1057 +msgid "August 2024: Core metadata 2.4 was approved through :pep:`639`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1059 +msgid "Added the ``License-Expression`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1060 +msgid "Added the ``License-File`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1062 +msgid "" +"August 2025: Clarified that ``Dynamic`` only affects how fields must be " +"treated when building a wheel from a sdist, not when modifying a wheel." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1066 +msgid "September 2025: Core metadata 2.5 was approved through :pep:`794`." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1068 +msgid "Added the ``Import-Name`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1069 +msgid "Added the ``Import-Namespace`` field." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1071 +msgid "" +"October 2025: Clarified that ``License-Expression`` applies to the " +"containing distribution file and not the project itself." +msgstr "" + +#: ../source/specifications/core-metadata.rst:1076 +msgid "reStructuredText markup: https://docutils.sourceforge.io/" +msgstr "" + +#: ../source/specifications/core-metadata.rst:1081 +msgid "RFC 822 Long Header Fields: :rfc:`822#section-3.1.1`" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:5 +msgid "Dependency Groups" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:7 +msgid "" +"This specification defines dependency groups, a mechanism for storing " +"package requirements in ``pyproject.toml`` files such that they are not " +"included in project metadata when it is built." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:11 +msgid "" +"Dependency groups are suitable for internal development use-cases like " +"linting and testing, as well as for projects which are not built for " +"distribution, like collections of related scripts." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:15 +msgid "" +"Fundamentally, dependency groups should be thought of as being a " +"standardized subset of the capabilities of ``requirements.txt`` files (which " +"are ``pip``-specific)." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:25 +msgid "This is a simple table which shows ``docs`` and ``test`` groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:31 +msgid "" +"and a similar table which defines ``docs``, ``test``, and ``coverage`` " +"groups::" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:39 +msgid "The ``[dependency-groups]`` Table" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:41 +msgid "" +"Dependency groups are defined as a table in ``pyproject.toml`` named " +"``dependency-groups``. The ``dependency-groups`` table contains an arbitrary " +"number of user-defined keys, each of which has, as its value, a list of " +"requirements." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:46 +msgid "" +"``[dependency-groups]`` keys, sometimes also called \"group names\", must " +"be :ref:`valid non-normalized names `. Tools which handle " +"Dependency Groups MUST :ref:`normalize ` these names " +"before comparisons." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:51 +msgid "" +"Tools SHOULD prefer to present the original, non-normalized name to users, " +"and if duplicate names are detected after normalization, tools SHOULD emit " +"an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:55 +msgid "" +"Requirement lists, the values in ``[dependency-groups]``, may contain " +"strings, tables (``dict`` in Python), or a mix of strings and tables. " +"Strings must be valid :ref:`dependency specifiers `, " +"and tables must be valid Dependency Group Includes." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:61 +msgid "Dependency Group Include" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:63 +msgid "" +"A Dependency Group Include includes another Dependency Group in the current " +"group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:66 +msgid "" +"An include is a table with exactly one key, ``\"include-group\"``, whose " +"value is a string, the name of another Dependency Group." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:69 +msgid "" +"Includes are defined to be exactly equivalent to the contents of the named " +"Dependency Group, inserted into the current group at the location of the " +"include. For example, if ``foo = [\"a\", \"b\"]`` is one group, and ``bar = " +"[\"c\", {include-group = \"foo\"}, \"d\"]`` is another, then ``bar`` should " +"evaluate to ``[\"c\", \"a\", \"b\", \"d\"]`` when Dependency Group Includes " +"are expanded." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:75 +msgid "" +"Dependency Group Includes may specify the same package multiple times. Tools " +"SHOULD NOT deduplicate or otherwise alter the list contents produced by the " +"include. For example, given the following table:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:92 +msgid "" +"The resolved value of ``all`` SHOULD be ``[\"foo\", \"foo\", \"foo>1.0\", " +"\"foo<1.0\"]``. Tools should handle such a list exactly as they would handle " +"any other case in which they are asked to process the same requirement " +"multiple times with different version constraints." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:97 +msgid "" +"Dependency Group Includes may include groups containing Dependency Group " +"Includes, in which case those includes should be expanded as well. " +"Dependency Group Includes MUST NOT include cycles, and tools SHOULD report " +"an error if they detect a cycle." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:102 +#, fuzzy +#| msgid "Package Index" +msgid "Package Building" +msgstr "套件索引" + +#: ../source/specifications/dependency-groups.rst:104 +msgid "" +"Build backends MUST NOT include Dependency Group data in built distributions " +"as package metadata. This means that sdist ``PKG-INFO`` and wheel " +"``METADATA`` files should not include referenceable fields containing " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:108 +msgid "" +"It is, however, valid to use dependency groups in the evaluation of dynamic " +"metadata, and ``pyproject.toml`` files included in sdists will still contain " +"``[dependency-groups]``. However, the table's contents are not part of a " +"built package's interfaces." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:114 +#, fuzzy +msgid "Installing Dependency Groups & Extras" +msgstr "安裝軟體套件" + +#: ../source/specifications/dependency-groups.rst:116 +msgid "" +"There is no syntax or specification-defined interface for installing or " +"referring to dependency groups. Tools are expected to provide dedicated " +"interfaces for this purpose." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:120 +msgid "" +"Tools MAY choose to provide the same or similar interfaces for interacting " +"with dependency groups as they do for managing extras. Tools authors are " +"advised that the specification does not forbid having an extra whose name " +"matches a Dependency Group. Separately, users are advised to avoid creating " +"dependency groups whose names match extras, and tools MAY treat such " +"matching as an error." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:128 +msgid "Validation and Compatibility" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:130 +msgid "" +"Tools supporting dependency groups may want to validate data before using " +"it. When implementing such validation, authors should be aware of the " +"possibility of future extensions to the specification, so that they do not " +"unnecessarily emit errors or warnings." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:135 +msgid "" +"Tools SHOULD error when evaluating or processing unrecognized data in " +"dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:138 +msgid "" +"Tools SHOULD NOT eagerly validate the contents of *all* dependency groups " +"unless they have a need to do so." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:141 +msgid "" +"This means that in the presence of the following data, most tools should " +"allow the ``foo`` group to be used and only error if the ``bar`` group is " +"used:" +msgstr "" + +#: ../source/specifications/dependency-groups.rst:152 +msgid "" +"There are several known cases of tools which have good cause to be stricter. " +"Linters and validators are an example, as their purpose is to validate the " +"contents of all dependency groups." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:157 +#: ../source/specifications/inline-script-metadata.rst:123 +#, fuzzy +#| msgid "Documentation types" +msgid "Reference Implementation" +msgstr "文件類型" + +#: ../source/specifications/dependency-groups.rst:159 +msgid "" +"The following Reference Implementation prints the contents of a Dependency " +"Group to stdout, newline delimited. The output is therefore valid " +"``requirements.txt`` data." +msgstr "" + +#: ../source/specifications/dependency-groups.rst:252 +msgid "October 2024: This specification was approved through :pep:`735`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:7 +msgid "Dependency specifiers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:9 +msgid "" +"This document describes the dependency specifiers format as originally " +"specified in :pep:`508`." +msgstr "" + +#: ../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 "" + +#: ../source/specifications/dependency-specifiers.rst:18 +msgid "" +"The language defined is a compact line based format which is already in " +"widespread use in pip requirements files, though we do not specify the " +"command line option handling that those files permit. There is one caveat - " +"the URL reference form, specified in :ref:`Versioning specifier " +"specification ` is not actually implemented in pip, but " +"we use that format rather than pip's current native format." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst: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 "" + +#: ../source/specifications/dependency-specifiers.rst:40 +msgid "Concepts" +msgstr "概念" + +#: ../source/specifications/dependency-specifiers.rst:42 +msgid "" +"A dependency specification always specifies a distribution name. It may " +"include extras, which expand the dependencies of the named distribution to " +"enable optional features. The version installed can be controlled using " +"version limits, or giving the URL to a specific artifact to install. Finally " +"the dependency can be made conditional using environment markers." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:49 +msgid "Grammar" +msgstr "文法" + +#: ../source/specifications/dependency-specifiers.rst:51 +msgid "" +"We first cover the grammar briefly and then drill into the semantics of each " +"section later." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:54 +msgid "" +"A distribution specification is written in ASCII text. We use a parsley " +"[#parsley]_ grammar to provide a precise grammar. It is expected that the " +"specification will be embedded into a larger system which offers framing " +"such as comments, multiple line support via continuations, or other such " +"features." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:59 +msgid "" +"The full grammar including annotations to build a useful parse tree is " +"included at the end of this document." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:62 +msgid "" +"Versions may be specified according to the rules of the :ref:`Version " +"specifier specification `. (Note: URI is defined " +"in :rfc:`std-66 <3986>`)::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:73 +msgid "" +"Environment markers allow making a specification only take effect in some " +"environments::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:102 +msgid "" +"Optional components of a distribution may be specified using the extras " +"field::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:111 +msgid "Restrictions on names for extras is defined in :pep:`685`." +msgstr "" + +#: ../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 "" +"Non line-breaking whitespace is mostly optional with no semantic meaning. " +"The sole exception is detecting the end of a URL requirement." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:134 +msgid "Names" +msgstr "名稱" + +#: ../source/specifications/dependency-specifiers.rst:136 +msgid "" +"Python distribution names are currently defined in :pep:`345`. Names act as " +"the primary identifier for distributions. They are present in all dependency " +"specifications, and are sufficient to be a specification on their own. " +"However, PyPI places strict restrictions on names - they must match a case " +"insensitive regex or they won't be accepted. Accordingly, in this document " +"we limit the acceptable values for identifiers to that regex. A full " +"redefinition of name may take place in a future metadata PEP. The regex (run " +"with re.IGNORECASE) is::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:150 +msgid "Extras" +msgstr "額外" + +#: ../source/specifications/dependency-specifiers.rst:152 +msgid "" +"An extra is an optional part of a distribution. Distributions can specify as " +"many extras as they wish, and each extra results in the declaration of " +"additional dependencies of the distribution **when** the extra is used in a " +"dependency specification. For instance::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:159 +msgid "" +"Extras union in the dependencies they define with the dependencies of the " +"distribution they are attached to. The example above would result in " +"requests being installed, and requests own dependencies, and also any " +"dependencies that are listed in the \"security\" extra of requests." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:164 +msgid "" +"If multiple extras are listed, all the dependencies are unioned together." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:169 +msgid "Versions" +msgstr "版本" + +#: ../source/specifications/dependency-specifiers.rst:171 +msgid "" +"See the :ref:`Version specifier specification ` for more " +"detail on both version numbers and version comparisons. Version " +"specifications limit the versions of a distribution that can be used. They " +"only apply to distributions looked up by name, rather than via a URL. " +"Version comparison are also used in the markers feature. The optional " +"brackets around a version are present for compatibility with :pep:`345` but " +"should not be generated, only accepted." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:182 +msgid "Environment Markers" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:184 +msgid "" +"Environment markers allow a dependency specification to provide a rule that " +"describes when the dependency should be used. For instance, consider a " +"package that needs argparse. In Python 2.7 argparse is always present. On " +"older Python versions it has to be installed as a dependency. This can be " +"expressed as so::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:191 +msgid "" +"A marker expression evaluates to either True or False. When it evaluates to " +"False, the dependency specification should be ignored." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:194 +msgid "" +"The marker language is inspired by Python itself, chosen for the ability to " +"safely evaluate it without running arbitrary code that could become a " +"security vulnerability. Markers were first standardised in :pep:`345`. This " +"document fixes some issues that were observed in the design described " +"in :pep:`426`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:199 +msgid "" +"Comparisons in marker expressions are typed by the comparison operator and " +"the type of the marker value. The operators that are not in " +" perform the same as they do for strings or sets in Python " +"based on whether the marker value is a string or set itself. 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 for the " +"types involved. Otherwise an error should be raised. e.g. the following will " +"result in errors::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:213 +msgid "" +"User supplied constants are always encoded as strings with either ``'`` or " +"``\"`` quote marks. Note that backslash escapes are not defined, but " +"existing implementations do support them. They are not included in this " +"specification because they add complexity and there is no observable need " +"for them today. Similarly we do not define non-ASCII character support: all " +"the runtime variables we are referencing are expected to be ASCII-only." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:220 +msgid "" +"The variables in the marker grammar such as \"os_name\" resolve to values " +"looked up in the Python runtime. With the exception of \"extra\" all values " +"are defined on all Python versions today - it is an error in the " +"implementation of markers if a value is not defined." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:225 +msgid "" +"Unknown variables must raise an error rather than resulting in a comparison " +"that evaluates to True or False." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:228 +msgid "" +"Variables whose value cannot be calculated on a given Python implementation " +"should evaluate to ``0`` for versions, and an empty string for all other " +"variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:232 +msgid "" +"The \"extra\" variable is special. It is used by wheels to signal which " +"specifications apply to a given extra in the wheel ``METADATA`` file, but " +"since the ``METADATA`` file is based on a draft version of :pep:`426`, there " +"is no current specification for this. Regardless, outside of a context where " +"this special handling is taking place, the \"extra\" variable should result " +"in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:239 +msgid "" +"The \"extras\" and \"dependency_groups\" variables are also special. They " +"are used to specify any requested extras or dependency groups when " +"installing from a lock file. Outside of the context of lock files, these two " +"variables should result in an error like all other unknown variables." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:247 +msgid "Marker" +msgstr "標記" + +#: ../source/specifications/dependency-specifiers.rst:248 +#, fuzzy +msgid "Python equivalent" +msgstr "Python 版本" + +#: ../source/specifications/dependency-specifiers.rst:249 +msgid "Type" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:250 +msgid "Sample values" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:251 +msgid "``os_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:252 +msgid ":py:data:`os.name`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:253 +#: ../source/specifications/dependency-specifiers.rst:257 +#: ../source/specifications/dependency-specifiers.rst:262 +#: ../source/specifications/dependency-specifiers.rst:266 +#: ../source/specifications/dependency-specifiers.rst:270 +#: ../source/specifications/dependency-specifiers.rst:274 +#: ../source/specifications/dependency-specifiers.rst:278 +#: ../source/specifications/dependency-specifiers.rst:292 +#: ../source/specifications/dependency-specifiers.rst:301 +msgid "String" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:254 +msgid "``posix``, ``java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:255 +msgid "``sys_platform``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:256 +msgid ":py:data:`sys.platform`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:258 +msgid "" +"``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that \"linux\" is " +"from Python3 and \"linux2\" from Python2)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:260 +msgid "``platform_machine``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:261 +msgid ":py:func:`platform.machine()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:263 +#: ../source/specifications/platform-compatibility-tags.rst:262 +msgid "``x86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:264 +msgid "``platform_python_implementation``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:265 +msgid ":py:func:`platform.python_implementation()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:267 +msgid "``CPython``, ``Jython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:268 +msgid "``platform_release``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:269 +msgid ":py:func:`platform.release()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:271 +msgid "``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:272 +msgid "``platform_system``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:273 +msgid ":py:func:`platform.system()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:275 +msgid "``Linux``, ``Windows``, ``Java``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:276 +msgid "``platform_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:277 +msgid ":py:func:`platform.version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:279 +msgid "" +"``#1 SMP Fri Apr 25 13:07:35 EDT 2014`` ``Java HotSpot(TM) 64-Bit Server VM, " +"25.51-b03, Oracle Corporation`` ``Darwin Kernel Version 14.5.0: Wed Jul 29 " +"02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:282 +msgid "``python_version``" +msgstr "``python_version``" + +#: ../source/specifications/dependency-specifiers.rst:283 +msgid "``'.'.join(platform.python_version_tuple()[:2])``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:284 +#: ../source/specifications/dependency-specifiers.rst:288 +#: ../source/specifications/dependency-specifiers.rst:296 +msgid ":ref:`Version `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:285 +msgid "``3.4``, ``2.7``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:286 +msgid "``python_full_version``" +msgstr "``python_full_version``" + +#: ../source/specifications/dependency-specifiers.rst:287 +msgid ":py:func:`platform.python_version()`" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:289 +#: ../source/specifications/dependency-specifiers.rst:297 +msgid "``3.4.0``, ``3.5.0b1``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:290 +msgid "``implementation_name``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:291 +msgid ":py:data:`sys.implementation.name `" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:293 +msgid "``cpython``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:294 +msgid "``implementation_version``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:295 +msgid "see definition below" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:298 +msgid "``extra``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:299 +#: ../source/specifications/dependency-specifiers.rst:304 +#: ../source/specifications/dependency-specifiers.rst:309 +msgid "" +"An error except when defined by the context interpreting the specification." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:302 +#, fuzzy +#| msgid "pyproject.toml" +msgid "``toml``" +msgstr "pyproject.toml" + +#: ../source/specifications/dependency-specifiers.rst:303 +#: ../source/specifications/pylock-toml.rst:108 +#, fuzzy +#| msgid "Extras" +msgid "``extras``" +msgstr "額外" + +#: ../source/specifications/dependency-specifiers.rst:306 +#: ../source/specifications/dependency-specifiers.rst:311 +msgid "Set of strings" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:307 +msgid "``{\"toml\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:308 +msgid "``dependency_groups``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:312 +msgid "``{\"test\"}``" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:314 +msgid "" +"The ``implementation_version`` marker variable is derived " +"from :py:data:`sys.implementation.version `:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:331 +msgid "" +"This environment markers section, initially defined through :pep:`508`, " +"supersedes the environment markers section in :pep:`345`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:337 +msgid "Complete Grammar" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:339 +msgid "The complete parsley grammar::" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:446 +msgid "A test program - if the grammar is in a string ``grammar``:" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:518 +msgid "November 2015: This specification was approved through :pep:`508`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:519 +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]_" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:524 +msgid "" +"June 2024: The definition of ``version_many`` was changed to allow trailing " +"commas, matching with the behavior of the Python implementation that has " +"been in use since late 2022." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:527 +msgid "" +"April 2025: Added ``extras`` and ``dependency_groups`` for :ref:`lock-file-" +"spec` as approved through :pep:`751`." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:529 +#: ../source/specifications/name-normalization.rst:56 +msgid "" +"August 2025: The suggested name validation regex was fixed to match the " +"field specification (it previously finished with ``$`` instead of ``\\Z``, " +"incorrectly permitting trailing newlines)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:532 +msgid "" +"December 2025: Ensure ``===`` before ``==`` in grammar, to allow arbitrary " +"equality comparisons to be parsed." +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:539 +msgid "" +"pip, the recommended installer for Python packages (http://" +"pip.readthedocs.org/en/stable/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:542 +msgid "The parsley PEG library. (https://pypi.python.org/pypi/parsley/)" +msgstr "" + +#: ../source/specifications/dependency-specifiers.rst:545 +msgid "" +"Future Python versions might be problematic with the definition of " +"Environment Marker Variable ``python_version`` (https://github.com/python/" +"peps/issues/560)" +msgstr "" + +#: ../source/specifications/direct-url.rst:6 +msgid "Recording the Direct URL Origin of installed distributions" +msgstr "" + +#: ../source/specifications/direct-url.rst:8 +msgid "" +"This document specifies a :file:`direct_url.json` file in the ``*.dist-" +"info`` directory of an installed distribution, to record the Direct URL " +"Origin of the distribution. The general structure and usage of ``*.dist-" +"info`` directories is described in :ref:`recording-installed-packages`." +msgstr "" + +#: ../source/specifications/direct-url.rst:17 +msgid "" +"The :file:`direct_url.json` file MUST be created in the :file:`*.dist-info` " +"directory by installers when installing a distribution from a requirement " +"specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/direct-url.rst:21 +#: ../source/specifications/recording-installed-packages.rst:222 +msgid "" +"This file MUST NOT be created when installing a distribution from an other " +"type of requirement (i.e. name plus version specifier)." +msgstr "" + +#: ../source/specifications/direct-url.rst:24 +msgid "" +"This JSON file MUST be a UTF-8 encoded, :rfc:`8259` compliant, serialization " +"of the :doc:`direct-url-data-structure`." +msgstr "" + +#: ../source/specifications/direct-url.rst:29 +msgid "" +"When the requested URL has the file:// scheme and points to a local " +"directory that happens to contain a VCS checkout, installers MUST NOT " +"attempt to infer any VCS information and therefore MUST NOT output any VCS " +"related information (such as ``vcs_info``) in :file:`direct_url.json`." +msgstr "" + +#: ../source/specifications/direct-url.rst:36 +msgid "" +"As a general rule, installers should as much as possible preserve the " +"information that was provided in the requested URL when " +"generating :file:`direct_url.json`. For example user:password environment " +"variables should be preserved and ``requested_revision`` should reflect the " +"revision that was provided in the requested URL as faithfully as possible. " +"This information is however *enriched* with more precise data, such as " +"``commit_id``." +msgstr "" + +#: ../source/specifications/direct-url.rst:45 +msgid "Example pip commands and their effect on direct_url.json" +msgstr "" + +#: ../source/specifications/direct-url.rst:47 +msgid "Commands that generate a ``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url.rst:49 +msgid "``pip install https://example.com/app-1.0.tgz``" +msgstr "" + +#: ../source/specifications/direct-url.rst:50 +msgid "``pip install https://example.com/app-1.0.whl``" +msgstr "" + +#: ../source/specifications/direct-url.rst:51 +msgid "" +"``pip install \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"``" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/direct-url.rst:54 +msgid "" +"``pip install --editable \"app @ git+https://example.com/repo/" +"app.git#subdirectory=setup\"`` (in which case, ``url`` will be the local " +"directory where the git repository has been cloned to, and ``dir_info`` will " +"be present with ``\"editable\": true`` and no ``vcs_info`` will be set)" +msgstr "" + +#: ../source/specifications/direct-url.rst:58 +msgid "``pip install -e ./app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:60 +msgid "Commands that *do not* generate a ``direct_url.json``" +msgstr "" + +#: ../source/specifications/direct-url.rst:62 +msgid "``pip install app``" +msgstr "" + +#: ../source/specifications/direct-url.rst:63 +msgid "``pip install app --no-index --find-links https://example.com/``" +msgstr "" + +#: ../source/specifications/direct-url.rst:69 +msgid "March 2020: This specification was approved through :pep:`610`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:7 +msgid "Direct URL Data Structure" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:9 +msgid "" +"This document specifies a JSON-serializable abstract data structure that can " +"represent URLs to python projects and distribution artifacts such as VCS " +"source trees, local source trees, source distributions and wheels." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:13 +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 " +"`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:21 +msgid "" +"The Direct URL Data Structure MUST be a dictionary, serializable to JSON " +"according to :rfc:`8259`." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:24 +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 `_." +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 "" + +#: ../source/specifications/direct-url-data-structure.rst:35 +msgid "Security Considerations" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:37 +msgid "" +"When persisted, ``url`` MUST be stripped of any sensitive authentication " +"information, for security reasons." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:40 +msgid "" +"The user:password section of the URL MAY however be composed of environment " +"variables, matching the following regular expression:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:48 +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 a URL " +"such as ``ssh://git@gitlab.com/user/repo``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:55 +msgid "VCS URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:57 +msgid "" +"When ``url`` refers to a VCS repository, the ``vcs_info`` key MUST be " +"present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:60 +msgid "" +"A ``vcs`` key (type ``string``) MUST be present, containing the name of the " +"VCS (i.e. one of ``git``, ``hg``, ``bzr``, ``svn``). Other VCS's SHOULD be " +"registered by writing a PEP to amend this specification. The ``url`` value " +"MUST be compatible with the corresponding VCS, so an installer can hand it " +"off without transformation to a checkout/download command of the VCS." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:66 +msgid "" +"A ``requested_revision`` key (type ``string``) MAY be present naming a " +"branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). " +"This 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:70 +msgid "" +"A ``commit_id`` key (type ``string``) MUST be present, containing the exact " +"commit/revision number that was/is to be installed. If the VCS supports " +"commit-hash based revision identifiers, such commit-hash MUST be used as " +"``commit_id`` in order to reference an immutable version of the source code." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:80 +msgid "Archive URLs" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:82 +msgid "" +"When ``url`` refers to a source archive or a wheel, the ``archive_info`` key " +"MUST be present as a dictionary with the following keys:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:85 +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:88 +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:92 +msgid "These hash names SHOULD always be normalized to be lowercase." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:94 +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." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:100 +msgid "" +"A deprecated ``hash`` key (type ``string``) MAY be present for backwards " +"compatibility purposes, with value ``=``." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:103 +msgid "" +"Producers of the data structure SHOULD emit the ``hashes`` key whether one " +"or multiple hashes are available. Producers SHOULD continue to emit the " +"``hash`` key in contexts where they did so before, so as to keep backwards " +"compatibility for existing clients." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:107 +msgid "" +"When both the ``hash`` and ``hashes`` keys are present, the hash represented " +"in the ``hash`` key MUST also be present in the ``hashes`` dictionary, so " +"consumers can consider the ``hashes`` key only if it is present, and fall " +"back to ``hash`` otherwise." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:114 +msgid "Local directories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:116 +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:119 +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:122 +msgid "" +"When ``url`` refers to a local directory, it MUST have the ``file`` scheme " +"and be compliant with :rfc:`8089`. In particular, the path component must be " +"absolute. Symbolic links SHOULD be preserved when making relative paths " +"absolute." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:130 +msgid "Projects in subdirectories" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:132 +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:139 +msgid "Registered VCS" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:141 +msgid "" +"This section lists the registered VCS's; expanded, VCS-specific information " +"on how to use the ``vcs``, ``requested_revision``, and other fields of " +"``vcs_info``; and in some cases additional VCS-specific fields. Tools MAY " +"support other VCS's although it is RECOMMENDED to register them by writing a " +"PEP to amend this specification. The ``vcs`` field SHOULD be the command " +"name (lowercased). Additional fields that would be necessary to support such " +"VCS SHOULD be prefixed with the VCS command name." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:151 +msgid "Git" +msgstr "Git" + +#: ../source/specifications/direct-url-data-structure.rst:154 +#: ../source/specifications/direct-url-data-structure.rst:181 +#: ../source/specifications/direct-url-data-structure.rst:199 +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "Home page" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:154 +msgid "https://git-scm.com/" +msgstr "https://git-scm.com/" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:220 +msgid "vcs command" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:157 +#: ../source/specifications/direct-url-data-structure.rst:160 +msgid "git" +msgstr "git" + +#: ../source/specifications/direct-url-data-structure.rst:160 +#: ../source/specifications/direct-url-data-structure.rst:187 +#: ../source/specifications/direct-url-data-structure.rst:205 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "``vcs`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:164 +#: ../source/specifications/direct-url-data-structure.rst:190 +#: ../source/specifications/direct-url-data-structure.rst:208 +#: ../source/specifications/direct-url-data-structure.rst:227 +msgid "``requested_revision`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:163 +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:167 +#: ../source/specifications/direct-url-data-structure.rst:193 +#: ../source/specifications/direct-url-data-structure.rst:211 +#: ../source/specifications/direct-url-data-structure.rst:232 +msgid "``commit_id`` field" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:167 +msgid "A commit hash (40 hexadecimal characters sha1)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:171 +msgid "" +"Tools can use the ``git show-ref`` and ``git symbolic-ref`` commands to " +"determine if the ``requested_revision`` corresponds to a Git ref. In turn, a " +"ref beginning with ``refs/tags/`` corresponds to a tag, and a ref beginning " +"with ``refs/remotes/origin/`` after cloning corresponds to a branch." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:178 +msgid "Mercurial" +msgstr "Mercurial" + +#: ../source/specifications/direct-url-data-structure.rst:181 +msgid "https://www.mercurial-scm.org/" +msgstr "https://www.mercurial-scm.org/" + +#: ../source/specifications/direct-url-data-structure.rst:184 +#: ../source/specifications/direct-url-data-structure.rst:187 +msgid "hg" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:190 +msgid "A tag name, branch name, changeset ID, shortened changeset ID." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:193 +msgid "A changeset ID (40 hexadecimal characters)." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:196 +msgid "Bazaar" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:199 +msgid "https://www.breezy-vcs.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:202 +#: ../source/specifications/direct-url-data-structure.rst:205 +msgid "bzr" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:208 +msgid "A tag name, branch name, revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:211 +msgid "A revision id." +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:214 +msgid "Subversion" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:217 +msgid "https://subversion.apache.org/" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:220 +#: ../source/specifications/direct-url-data-structure.rst:223 +msgid "svn" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:226 +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:230 +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:235 +msgid "JSON Schema" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:237 +msgid "" +"The following JSON Schema can be used to validate the contents of " +"``direct_url.json``:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:244 +msgid "Source archive:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:257 +msgid "Git URL with tag and commit-hash:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:270 +msgid "Local directory:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:279 +msgid "Local directory in editable mode:" +msgstr "" + +#: ../source/specifications/direct-url-data-structure.rst:294 +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:296 +msgid "" +"January 2023: Added the ``archive_info.hashes`` key (`discussion `_)." +msgstr "" + +#: ../source/specifications/entry-points.rst:5 +msgid "Entry points specification" +msgstr "" + +#: ../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/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 "" + +#: ../source/specifications/entry-points.rst:14 +msgid "" +"Applications can use entry points to load plugins; e.g. Pygments (a syntax " +"highlighting tool) can use additional lexers and styles from separately " +"installed packages. For more about this, see :doc:`/guides/creating-and-" +"discovering-plugins`." +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:28 +msgid "Data model" +msgstr "" + +#: ../source/specifications/entry-points.rst:30 +msgid "Conceptually, an entry point is defined by three required properties:" +msgstr "" + +#: ../source/specifications/entry-points.rst:32 +msgid "" +"The **group** that an entry point belongs to indicates what sort of object " +"it provides. For instance, the group ``console_scripts`` is for entry points " +"referring to functions which can be used as a command, while " +"``pygments.styles`` is the group for classes defining pygments styles. The " +"consumer typically defines the expected interface. To avoid clashes, " +"consumers defining a new group should use names starting with a PyPI name " +"owned by the consumer project, followed by ``.``. Group names must be one or " +"more groups of letters, numbers and underscores, separated by dots (regex " +"``^\\w+(\\.\\w+)*$``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:42 +msgid "" +"The **name** identifies this entry point within its group. The precise " +"meaning of this is up to the consumer. For console scripts, the name of the " +"entry point is the command that will be used to launch it. Within a " +"distribution, entry point names should be unique. If different distributions " +"provide the same name, the consumer decides how to handle such conflicts. " +"The name may contain any characters except ``=``, but it cannot start or end " +"with any whitespace character, or start with ``[``. For new entry points, it " +"is recommended to use only letters, numbers, underscores, dots and dashes " +"(regex ``[\\w.-]+``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:51 +msgid "" +"The **object reference** points to a Python object. It is either in the form " +"``importable.module``, or ``importable.module:object.attr``. Each of the " +"parts delimited by dots and the colon is a valid Python identifier. It is " +"intended to be looked up like this::" +msgstr "" + +#: ../source/specifications/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/entry-points.rst:68 +msgid "" +"There is also an optional property: the **extras** are a set of strings " +"identifying optional features of the distribution providing the entry point. " +"If these are specified, the entry point requires the dependencies of those " +"'extras'. See the metadata field :ref:`metadata_provides_extra`." +msgstr "" + +#: ../source/specifications/entry-points.rst:73 +msgid "" +"Using extras for an entry point is no longer recommended. Consumers should " +"support parsing them from existing distributions, but may then ignore them. " +"New publishing tools need not support specifying extras. The functionality " +"of handling extras was tied to setuptools' model of managing 'egg' packages, " +"but newer tools such as pip and virtualenv use a different model." +msgstr "" + +#: ../source/specifications/entry-points.rst:80 +msgid "File format" +msgstr "" + +#: ../source/specifications/entry-points.rst:82 +msgid "" +"Entry points are defined in a file called :file:`entry_points.txt` in " +"the :file:`*.dist-info` directory of the distribution. This is the directory " +"described in :ref:`recording-installed-packages` for installed " +"distributions, and in :ref:`binary-distribution-format` for wheels. The file " +"uses the UTF-8 character encoding." +msgstr "" + +#: ../source/specifications/entry-points.rst:88 +msgid "" +"The file contents are in INI format, as read by Python's :mod:`configparser` " +"module. However, configparser treats names as case-insensitive by default, " +"whereas entry point names are case sensitive. A case-sensitive config parser " +"can be made like this::" +msgstr "" + +#: ../source/specifications/entry-points.rst:98 +msgid "" +"The entry points file must always use ``=`` to delimit names from values " +"(whereas configparser also allows using ``:``)." +msgstr "" + +#: ../source/specifications/entry-points.rst:101 +msgid "" +"The sections of the config file represent entry point groups, the names are " +"names, and the values encode both the object reference and the optional " +"extras. If extras are used, they are a comma-separated list inside square " +"brackets." +msgstr "" + +#: ../source/specifications/entry-points.rst:105 +msgid "" +"Within a value, readers must accept and ignore spaces (including multiple " +"consecutive spaces) before or after the colon, between the object reference " +"and the left square bracket, between the extra names and the square brackets " +"and colons delimiting them, and after the right square bracket. The syntax " +"for extras is formally specified as part of :pep:`508` (as ``extras``) and " +"restrictions on values specified in :pep:`685`. For tools writing the file, " +"it is recommended only to insert a space between the object reference and " +"the left square bracket." +msgstr "" + +#: ../source/specifications/entry-points.rst:128 +msgid "Use for scripts" +msgstr "" + +#: ../source/specifications/entry-points.rst:130 +msgid "" +"Two groups of entry points have special significance in packaging: " +"``console_scripts`` and ``gui_scripts``. In both groups, the name of the " +"entry point should be usable as a command in a system shell after the " +"package is installed. The object reference points to a function which will " +"be called with no arguments when this command is run. The function may " +"return an integer to be used as a process exit code, and returning ``None`` " +"is equivalent to returning ``0``." +msgstr "" + +#: ../source/specifications/entry-points.rst:138 +msgid "" +"For instance, the entry point ``mycmd = mymod:main`` would create a command " +"``mycmd`` launching a script like this::" +msgstr "" + +#: ../source/specifications/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 "" + +#: ../source/specifications/entry-points.rst:153 +msgid "" +"Install tools are expected to set up wrappers for both ``console_scripts`` " +"and ``gui_scripts`` in the scripts directory of the install scheme. They are " +"not responsible for putting this directory in the ``PATH`` environment " +"variable which defines where command-line tools are found." +msgstr "" + +#: ../source/specifications/entry-points.rst:158 +msgid "" +"As files are created from the names, and some filesystems are case-" +"insensitive, packages should avoid using names in these groups which differ " +"only in case. The behaviour of install tools when names differ only in case " +"is undefined." +msgstr "" + +#: ../source/specifications/entry-points.rst:166 +msgid "" +"October 2017: This specification was written to formalize the existing entry " +"points feature of setuptools (discussion_)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:6 +msgid "Externally Managed Environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:8 +msgid "" +"While some Python installations are entirely managed by the user that " +"installed Python, others may be provided and managed by another means (such " +"as the operating system package manager in a Linux distribution, or as a " +"bundled Python environment in an application with a dedicated installer)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:13 +msgid "" +"Attempting to use conventional Python packaging tools to manipulate such " +"environments can be confusing at best and outright break the entire " +"underlying operating system at worst. Documentation and interoperability " +"guides only go so far in resolving such problems." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:18 +msgid "" +"This specification defines an ``EXTERNALLY-MANAGED`` marker file that allows " +"a Python installation to indicate to Python-specific tools such as ``pip`` " +"that they neither install nor remove packages into the interpreter’s default " +"installation environment, and should instead guide the end user towards " +"using :ref:`virtual-environments`." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:24 +msgid "" +"It also standardizes an interpretation of the ``sysconfig`` schemes so that, " +"if a Python-specific package manager is about to install a package in an " +"interpreter-wide context, it can do so in a manner that will avoid " +"conflicting with the external package manager and reduces the risk of " +"breaking software shipped by the external package manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:32 +msgid "Terminology" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:34 +msgid "" +"A few terms used in this specification have multiple meanings in the " +"contexts that it spans. For clarity, this specification uses the following " +"terms in specific ways:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:61 +msgid "distro" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:39 +msgid "" +"Short for \"distribution,\" a collection of various sorts of software, " +"ideally designed to work properly together, including (in contexts relevant " +"to this document) the Python interpreter itself, software written in Python, " +"and software written in other languages. That is, this is the sense used in " +"phrases such as \"Linux distro\" or \"Berkeley Software Distribution.\"" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:46 +msgid "" +"A distro can be an operating system (OS) of its own, such as Debian, Fedora, " +"or FreeBSD. It can also be an overlay distribution that installs on top of " +"an existing OS, such as Homebrew or MacPorts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:51 +msgid "" +"This document uses the short term \"distro,\" because the term " +"\"distribution\" has another meaning in Python packaging contexts: a source " +"or binary distribution package of a single piece of Python language " +"software, that is, in the sense of ``setuptools.dist.Distribution`` or " +"\"sdist\". To avoid confusion, this document does not use the plain term " +"\"distribution\" at all. In the Python packaging sense, it uses the full " +"phrase \"distribution package\" or just \"package\" (see below)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:60 +msgid "" +"The provider of a distro - the team or company that collects and publishes " +"the software and makes any needed modifications - is its **distributor**." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:79 +#, fuzzy +#| msgid "Package Index" +msgid "package" +msgstr "套件索引" + +#: ../source/specifications/externally-managed-environments.rst:64 +msgid "" +"A unit of software that can be installed and used within Python. That is, " +"this refers to what Python-specific packaging tools tend to call " +"a :term:`distribution package` or simply a \"distribution\"; the colloquial " +"abbreviation \"package\" is used in the sense of the Python Package Index." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:70 +msgid "" +"This document does not use \"package\" in the sense of an importable name " +"that contains Python modules, though in many cases, a distribution package " +"consists of a single importable package of the same name." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:75 +msgid "" +"This document generally does not use the term \"package\" to refer to units " +"of installation by a distro's package manager (such as ``.deb`` or ``.rpm`` " +"files). When needed, it uses phrasing such as \"a distro's package.\" " +"(Again, in many cases, a Python package is shipped inside a distro's package " +"named something like ``python-`` plus the Python package name.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:102 +msgid "Python-specific package manager" +msgstr "Python 套件管理器" + +#: ../source/specifications/externally-managed-environments.rst:82 +msgid "" +"A tool for installing, upgrading, and/or removing Python packages in a " +"manner that conforms to Python packaging standards. The most popular Python-" +"specific package manager is pip_; other examples include the old `Easy " +"Install command `_ as well as direct usage of a ``setup.py`` " +"command." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:92 +msgid "" +"(Note that the ``easy_install`` command was removed in setuptools version " +"52, released 23 January 2021.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:96 +msgid "" +"(Conda_ is a bit of a special case, as the ``conda`` command can install " +"much more than just Python packages, making it more like a distro package " +"manager in some senses. Since the ``conda`` command generally only operates " +"on Conda-created environments, most of the concerns in this document do not " +"apply to ``conda`` when acting as a Python-specific package manager.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:118 +msgid "distro package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:105 +msgid "" +"A tool for installing, upgrading, and/or removing a distro's packages in an " +"installed instance of that distro, which is capable of installing Python " +"packages as well as non-Python packages, and therefore generally has its own " +"database of installed software unrelated to the :ref:`database of installed " +"distributions `. Examples include ``apt``, " +"``dpkg``, ``dnf``, ``rpm``, ``pacman``, and ``brew``. The salient feature is " +"that if a package was installed by a distro package manager, removing or " +"upgrading it in a way that would satisfy a Python-specific package manager " +"will generally leave a distro package manager in an inconsistent state." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:117 +msgid "" +"This document also uses phrases like \"external package manager\" or " +"\"system's package manager\" to refer to a distro package manager in certain " +"contexts." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:127 +msgid "shadow" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:121 +msgid "" +"To shadow an installed Python package is to cause some other package to be " +"preferred for imports without removing any files from the shadowed package. " +"This requires multiple entries on ``sys.path``: if package A 2.0 installs " +"module ``a.py`` in one ``sys.path`` entry, and package A 1.0 installs module " +"``a.py`` in a later ``sys.path`` entry, then ``import a`` returns the module " +"from the former, and we say that A 2.0 shadows A 1.0." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:132 +msgid "This specification is twofold." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:134 +msgid "" +"First, it describes **a way for distributors of a Python interpreter to mark " +"that interpreter as having its packages managed by means external to " +"Python**, such that Python-specific tools like pip should not change the " +"installed packages in the interpreter's global ``sys.path`` in any way (add, " +"upgrade/downgrade, or remove) unless specifically overridden. It also " +"provides a means for the distributor to indicate how to use a virtual " +"environment as an alternative." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:142 +msgid "" +"This is an opt-in mechanism: by default, the Python interpreter compiled " +"from upstream sources will not be so marked, and so running ``pip install`` " +"with a self-compiled interpreter, or with a distro that has not explicitly " +"marked its interpreter, will work as it always has worked." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:148 +msgid "" +"Second, it sets the rule that when installing packages to an interpreter's " +"global context (either to an unmarked interpreter, or if overriding the " +"marking), **Python-specific package managers should modify or delete files " +"only within the directories of the sysconfig scheme in which they would " +"create files**. This permits a distributor of a Python interpreter to set up " +"two directories, one for its own managed packages, and one for unmanaged " +"packages installed by the end user, and ensure that installing unmanaged " +"packages will not delete (or overwrite) files owned by the external package " +"manager." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:160 +msgid "Marking an interpreter as using an external package manager" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:162 +msgid "" +"Before a Python-specific package installer (that is, a tool such as pip - " +"not an external tool such as apt) installs a package into a certain Python " +"context, it should make the following checks by default:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:167 +msgid "" +"Is it running outside of a virtual environment? It can determine this by " +"whether ``sys.prefix == sys.base_prefix``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:170 +msgid "" +"Is there an ``EXTERNALLY-MANAGED`` file in the directory identified by " +"``sysconfig.get_path(\"stdlib\", sysconfig.get_default_scheme())``?" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:173 +msgid "" +"If both of these conditions are true, the installer should exit with an " +"error message indicating that package installation into this Python " +"interpreter's directory are disabled outside of a virtual environment." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:177 +msgid "" +"The installer should have a way for the user to override these rules, such " +"as a command-line flag ``--break-system-packages``. This option should not " +"be enabled by default and should carry some connotation that its use is " +"risky." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:182 +msgid "" +"The ``EXTERNALLY-MANAGED`` file is an INI-style metadata file intended to be " +"parsable by the standard library configparser_ module. If the file can be " +"parsed by ``configparser.ConfigParser(interpolation=None)`` using the UTF-8 " +"encoding, and it contains a section ``[externally-managed]``, then the " +"installer should look for an error message specified in the file and output " +"it as part of its error. If the first element of the tuple returned by " +"``locale.getlocale(locale.LC_MESSAGES)``, i.e., the language code, is not " +"``None``, it should look for the error message as the value of a key named " +"``Error-`` followed by the language code. If that key does not exist, and if " +"the language code contains underscore or hyphen, it should look for a key " +"named ``Error-`` followed by the portion of the language code before the " +"underscore or hyphen. If it cannot find either of those, or if the language " +"code is ``None``, it should look for a key simply named ``Error``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:200 +msgid "" +"If the installer cannot find an error message in the file (either because " +"the file cannot be parsed or because no suitable error key exists), then the " +"installer should just use a pre-defined error message of its own, which " +"should suggest that the user create a virtual environment to install " +"packages." +msgstr "" + +#: ../source/specifications/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 an ``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/externally-managed-environments.rst:230 +msgid "" +"which provides useful and distro-relevant information to a user trying to " +"install a package. Optionally, translations can be provided in the same file:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:240 +msgid "" +"In certain contexts, such as single-application container images that aren't " +"updated after creation, a distributor may choose not to ship an ``EXTERNALLY-" +"MANAGED`` file, so that users can install whatever they like (as they can " +"today) without having to manually override this rule." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:247 +msgid "Writing to only the target ``sysconfig`` scheme" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:249 +msgid "" +"Usually, a Python package installer installs to directories in a scheme " +"returned by the ``sysconfig`` standard library package. Ordinarily, this is " +"the scheme returned by ``sysconfig.get_default_scheme()``, but based on " +"configuration (e.g. ``pip install --user``), it may use a different scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:255 +msgid "" +"Whenever the installer is installing to a ``sysconfig`` scheme, this " +"specification declares that the installer should never modify or delete " +"files outside of that scheme. For instance, if it's upgrading a package, and " +"the package is already installed in a directory outside that scheme (perhaps " +"in a directory from another scheme), it should leave the existing files " +"alone." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:262 +msgid "" +"If the installer does end up shadowing an existing installation during an " +"upgrade, we recommend that it produces a warning at the end of its run." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:266 +msgid "" +"If the installer is installing to a location outside of a ``sysconfig`` " +"scheme (e.g., ``pip install --target``), then this subsection does not apply." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:271 +msgid "Recommendations for distros" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:273 +msgid "" +"This section is non-normative. It provides best practices we believe distros " +"should follow unless they have a specific reason otherwise." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:277 +msgid "Mark the installation as externally managed" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:279 +msgid "" +"Distros should create an ``EXTERNALLY-MANAGED`` file in their ``stdlib`` " +"directory." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:283 +msgid "Guide users towards virtual environments" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:285 +msgid "" +"The file should contain a useful and distro-relevant error message " +"indicating both how to install system-wide packages via the distro's package " +"manager and how to set up a virtual environment. If your distro is often " +"used by users in a state where the ``python3`` command is available (and " +"especially where ``pip`` or ``get-pip`` is available) but ``python3 -m " +"venv`` does not work, the message should indicate clearly how to make " +"``python3 -m venv`` work properly." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:293 +msgid "" +"Consider packaging pipx_, a tool for installing Python-language " +"applications, and suggesting it in the error. pipx automatically creates a " +"virtual environment for that application alone, which is a much better " +"default for end users who want to install some Python-language software " +"(which isn't available in the distro) but are not themselves Python users. " +"Packaging pipx in the distro avoids the irony of instructing users to ``pip " +"install --user --break-system-packages pipx`` to *avoid* breaking system " +"packages. Consider arranging things so your distro's package / environment " +"for Python for end users (e.g., ``python3`` on Fedora or ``python3-full`` on " +"Debian) depends on pipx." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:308 +msgid "Keep the marker file in container images" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:310 +msgid "" +"Distros that produce official images for single-application containers " +"(e.g., Docker container images) should keep the ``EXTERNALLY-MANAGED`` file, " +"preferably in a way that makes it not go away if a user of that image " +"installs package updates inside their image (think ``RUN apt-get dist-" +"upgrade``)." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:317 +msgid "Create separate distro and local directories" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:319 +msgid "" +"Distros should place two separate paths on the system interpreter's " +"``sys.path``, one for distro-installed packages and one for packages " +"installed by the local system administrator, and configure " +"``sysconfig.get_default_scheme()`` to point at the latter path. This ensures " +"that tools like pip will not modify distro-installed packages. The path for " +"the local system administrator should come before the distro path on " +"``sys.path`` so that local installs take preference over distro packages." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:328 +msgid "" +"For example, Fedora and Debian (and their derivatives) both implement this " +"split by using ``/usr/local`` for locally-installed packages and ``/usr`` " +"for distro-installed packages. Fedora uses ``/usr/local/lib/python3.x/site-" +"packages`` vs. ``/usr/lib/python3.x/site-packages``. (Debian uses ``/usr/" +"local/lib/python3/dist-packages`` vs. ``/usr/lib/python3/dist-packages`` as " +"an additional layer of separation from a locally-compiled Python " +"interpreter: if you build and install upstream CPython in ``/usr/local/" +"bin``, it will look at ``/usr/local/lib/python3/site-packages``, and Debian " +"wishes to make sure that packages installed via the locally-built " +"interpreter don't show up on ``sys.path`` for the distro interpreter.)" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:341 +msgid "" +"Note that the ``/usr/local`` vs. ``/usr`` split is analogous to how the " +"``PATH`` environment variable typically includes ``/usr/local/bin:/usr/bin`` " +"and non-distro software installs to ``/usr/local`` by default. This split is " +"`recommended by the Filesystem Hierarchy Standard`__." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:349 +msgid "" +"There are two ways you could do this. One is, if you are building and " +"packaging Python libraries directly (e.g., your packaging helpers unpack a " +"wheel or call ``setup.py install``), arrange for those tools to use a " +"directory that is not in a ``sysconfig`` scheme but is still on ``sys.path``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:355 +msgid "" +"The other is to arrange for the default ``sysconfig`` scheme to change when " +"running inside a package build versus when running on an installed system. " +"The ``sysconfig`` customization hooks from bpo-43976_ should make this easy " +"(once accepted and implemented): make your packaging tool set an environment " +"variable or some other detectable configuration, and define a " +"``get_preferred_schemes`` function to return a different scheme when called " +"from inside a package build. Then you can use ``pip install`` as part of " +"your distro packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:367 +msgid "" +"We propose adding a ``--scheme=...`` option to instruct pip to run against a " +"specific scheme. (See `Implementation Notes`_ below for how pip currently " +"determines schemes.) Once that's available, for local testing and possibly " +"for actual packaging, you would be able to run something like ``pip install " +"--scheme=posix_distro`` to explicitly install a package into your distro's " +"location (bypassing ``get_preferred_schemes``). One could also, if " +"absolutely needed, use ``pip uninstall --scheme=posix_distro`` to use pip to " +"remove packages from the system-managed directory." +msgstr "" + +#: ../source/specifications/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/externally-managed-environments.rst:383 +msgid "" +"The advantage of setting these up to be automatic (suppressing the marker " +"file in your build environment and having ``get_preferred_schemes`` " +"automatically return your distro's scheme) is that an unadorned ``pip " +"install`` will work inside a package build, which generally means that an " +"unmodified upstream build script that happens to internally call ``pip " +"install`` will do the right thing. You can, of course, just ensure that your " +"packaging process always calls ``pip install --scheme=posix_distro --break-" +"system-packages``, which would work too." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:393 +msgid "" +"The best approach here depends a lot on your distro's conventions and " +"mechanisms for packaging." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:396 +msgid "" +"Similarly, the ``sysconfig`` paths that are not for importable Python code - " +"that is, ``include``, ``platinclude``, ``scripts``, and ``data`` - should " +"also have two variants, one for use by distro-packaged software and one for " +"use for locally-installed software, and the distro should be set up such " +"that both are usable. For instance, a typical FHS-compliant distro will use " +"``/usr/local/include`` for the default scheme's ``include`` and ``/usr/" +"include`` for distro-packaged headers and place both on the compiler's " +"search path, and it will use ``/usr/local/bin`` for the default scheme's " +"``scripts`` and ``/usr/bin`` for distro-packaged entry points and place both " +"on ``$PATH``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:410 +#, fuzzy +#| msgid "Documentation types" +msgid "Implementation Notes" +msgstr "文件類型" + +#: ../source/specifications/externally-managed-environments.rst:412 +msgid "" +"This section is non-normative and contains notes relevant to both the " +"specification and potential implementations." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:415 +msgid "" +"Currently (as of May 2021), pip does not directly expose a way to choose a " +"target ``sysconfig`` scheme, but it has three ways of looking up schemes " +"when installing:" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:422 +msgid "``pip install``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:420 +msgid "" +"Calls ``sysconfig.get_default_scheme()``, which is usually (in upstream " +"CPython and most current distros) the same as " +"``get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "``pip install --prefix=/some/path``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:425 +msgid "Calls ``sysconfig.get_preferred_scheme('prefix')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "``pip install --user``" +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:428 +msgid "Calls ``sysconfig.get_preferred_scheme('user')``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:430 +msgid "" +"Finally, ``pip install --target=/some/path`` writes directly to ``/some/" +"path`` without looking up any schemes." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:433 +msgid "" +"Debian currently carries a `patch to change the default install location " +"inside a virtual environment`__, using a few heuristics (including checking " +"for the ``VIRTUAL_ENV`` environment variable), largely so that the directory " +"used in a virtual environment remains ``site-packages`` and not ``dist-" +"packages``. This does not particularly affect this proposal, because the " +"implementation of that patch does not actually change the default " +"``sysconfig`` scheme, and notably does not change the result of " +"``sysconfig.get_path(\"stdlib\")``." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:445 +msgid "" +"Fedora currently carries a `patch to change the default install location " +"when not running inside rpmbuild`__, which they use to implement the two-" +"system-wide-directories approach. This is conceptually the sort of hook " +"envisioned by bpo-43976_, except implemented as a code patch to " +"``distutils`` instead of as a changed ``sysconfig`` scheme." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:454 +msgid "" +"The implementation of ``is_virtual_environment`` above, as well as the logic " +"to load the ``EXTERNALLY-MANAGED`` file and find the error message from it, " +"may as well get added to the standard library (``sys`` and ``sysconfig``, " +"respectively), to centralize their implementations, but they don't need to " +"be added yet." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:464 +msgid "Copyright" +msgstr "著作權" + +#: ../source/specifications/externally-managed-environments.rst:466 +msgid "" +"This document is placed in the public domain or under the CC0-1.0-Universal " +"license, whichever is more permissive." +msgstr "" + +#: ../source/specifications/externally-managed-environments.rst:474 +msgid "June 2022: This specification was approved through :pep:`668`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:5 +msgid "File Yanking" +msgstr "" + +#: ../source/specifications/file-yanking.rst:9 +msgid "This specification was originally defined in :pep:`592`." +msgstr "" + +#: ../source/specifications/file-yanking.rst:14 +msgid "" +":pep:`592` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/file-yanking.rst:22 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:29 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:34 +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)." +msgstr "" + +#: ../source/specifications/file-yanking.rst:40 +#, fuzzy +msgid "Installers" +msgstr "安裝軟體套件" + +#: ../source/specifications/file-yanking.rst:42 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:49 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:56 +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:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:60 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:67 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:73 +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/file-yanking.rst:81 +msgid "Mirrors" +msgstr "" + +#: ../source/specifications/file-yanking.rst:83 +msgid "Mirrors can generally treat yanked files one of two ways:" +msgstr "" + +#: ../source/specifications/file-yanking.rst:85 +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." +msgstr "" + +#: ../source/specifications/file-yanking.rst:88 +msgid "" +"They may choose to include yanked files, and additionally mirror the ``data-" +"yanked`` attribute as well." +msgstr "" + +#: ../source/specifications/file-yanking.rst:91 +msgid "" +"Mirrors **MUST NOT** mirror a yanked file without also mirroring the ``data-" +"yanked`` attribute for it." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:3 +msgid "``glob`` patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:5 +msgid "" +"Some PyPA specifications, e.g. :ref:`pyproject.toml's license-files " +"`, accept certain types of *glob patterns* to " +"match a given string containing wildcards and character ranges against files " +"and directories. This specification defines which patterns are acceptable " +"and how they should be handled." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:13 +msgid "Valid glob patterns" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:15 +msgid "" +"For PyPA purposes, a *valid glob pattern* MUST be a string matched against " +"filesystem entries as specified below:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:18 +msgid "" +"Alphanumeric characters, underscores (``_``), hyphens (``-``) and dots " +"(``.``) MUST be matched verbatim." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:21 +msgid "" +"Special glob characters: ``*``, ``?``, ``**`` and character ranges: ``[]`` " +"containing only the verbatim matched characters MUST be supported. Within " +"``[...]``, the hyphen indicates a locale-agnostic range (e.g. ``a-z``, order " +"based on Unicode code points). Hyphens at the start or end are matched " +"literally." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:27 +msgid "Path delimiters MUST be the forward slash character (``/``)." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:29 +msgid "" +"Patterns always refer to *relative paths*, e.g., when used " +"in :file:`pyproject.toml`, patterns should always be relative to the " +"directory containing that file. Therefore the leading slash character MUST " +"NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:34 +msgid "Parent directory indicators (``..``) MUST NOT be used." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:36 +msgid "" +"Any characters or character sequences not covered by this specification are " +"invalid. Projects MUST NOT use such values. Tools consuming glob patterns " +"SHOULD reject invalid values with an error." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:40 +msgid "" +"Literal paths (e.g. :file:`LICENSE`) are valid globs which means they can " +"also be defined." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:43 +msgid "Tools consuming glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:45 +msgid "" +"MUST treat each value as a glob pattern, and MUST raise an error if the " +"pattern contains invalid glob syntax." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:47 +msgid "" +"MUST raise an error if any individual user-specified pattern does not match " +"at least one file." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:50 +msgid "Examples of valid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:61 +msgid "Examples of invalid glob patterns:" +msgstr "" + +#: ../source/specifications/glob-patterns.rst:74 +#, fuzzy +#| msgid "Documentation types" +msgid "Reference implementation in Python" +msgstr "文件類型" + +#: ../source/specifications/glob-patterns.rst:76 +msgid "" +"It is possible to defer the majority of the pattern matching against the " +"file system to the :mod:`glob` module in Python's standard library. It is " +"necessary however to perform additional validations." +msgstr "" + +#: ../source/specifications/glob-patterns.rst:80 +msgid "The code below is as a simple reference implementation:" +msgstr "" + +#: ../source/specifications/index.rst:4 +msgid "PyPA specifications" +msgstr "" + +#: ../source/specifications/index.rst:6 +msgid "" +"This is a list of currently active interoperability specifications " +"maintained by the Python Packaging Authority. The process for updating these " +"standards, and for proposing new ones, is documented on `pypa.io `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:6 +msgid "Index hosted attestations" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:8 +msgid "This specification was originally defined in :pep:`740`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:12 +msgid "" +":pep:`740` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`simple-" +"repository-api-base` and :ref:`json-serialization`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:22 +msgid "Upload endpoint changes" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:26 +msgid "" +"The \"legacy\" upload API is not standardized. See `PyPI's Upload API " +"documentation `_ for how attestations are " +"uploaded." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:33 +msgid "Attestation objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:35 +msgid "" +"An attestation object is a JSON object with several required keys; " +"applications or signers may include additional keys so long as all " +"explicitly listed keys are provided. The required layout of an attestation " +"object is provided as pseudocode below." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:88 +msgid "" +"A full data model for each object in ``transparency_entries`` is provided " +"in :ref:`appendix`. Attestation objects **SHOULD** include one or more " +"transparency log entries, and **MAY** include additional keys for other " +"sources of signed time (such as an :rfc:`3161` Time Stamping Authority or a " +"`Roughtime `__ server)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:94 +msgid "" +"Attestation objects are versioned; this PEP specifies version 1. Each " +"version is tied to a single cryptographic suite to minimize unnecessary " +"cryptographic agility. In version 1, the suite is as follows:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:98 +msgid "" +"Certificates are specified as X.509 certificates, and comply with the " +"profile in :rfc:`5280`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:100 +msgid "" +"The message signature algorithm is ECDSA, with the P-256 curve for public " +"keys and SHA-256 as the cryptographic digest function." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:103 +msgid "" +"Future PEPs may change this suite (and the overall shape of the attestation " +"object) by selecting a new version number." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:109 +msgid "Attestation statement and signature generation" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:111 +msgid "" +"The *attestation statement* is the actual claim that is cryptographically " +"signed over within the attestation object (i.e., the ``envelope.statement``)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:114 +msgid "" +"The attestation statement is encoded as a `v1 in-toto Statement object " +"`__, in JSON form. When serialized the statement is treated as " +"an opaque binary blob, avoiding the need for canonicalization." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:119 +msgid "" +"In addition to being a v1 in-toto Statement, the attestation statement is " +"constrained in the following ways:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:122 +msgid "The in-toto ``subject`` **MUST** contain only a single subject." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:123 +msgid "" +"``subject[0].name`` is the distribution's filename, which **MUST** be a " +"valid :ref:`source distribution ` or :ref:`wheel " +"distribution ` filename." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:126 +msgid "" +"``subject[0].digest`` **MUST** contain a SHA-256 digest. Other digests " +"**MAY** be present. The digests **MUST** be represented as hexadecimal " +"strings." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:128 +msgid "The following ``predicateType`` values are supported:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:130 +msgid "" +"`SLSA Provenance `__: ``https://slsa.dev/" +"provenance/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:131 +msgid "" +"`PyPI Publish Attestation `__: ``https://docs.pypi.org/attestations/publish/v1``" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:133 +msgid "" +"The signature over this statement is constructed using the `v1 DSSE " +"signature protocol `__, with a ``PAYLOAD_TYPE`` of ``application/vnd.in-toto+json`` " +"and a ``PAYLOAD_BODY`` of the JSON-encoded statement above. No other " +"``PAYLOAD_TYPE`` is permitted." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:141 +msgid "Provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:143 +msgid "" +"The index will serve uploaded attestations along with metadata that can " +"assist in verifying them in the form of JSON serialized objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:146 +msgid "" +"These *provenance objects* will be available via both the Simple Index and " +"JSON-based Simple API as described above, and will have the following layout:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:169 +msgid "or, as pseudocode:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:217 +msgid "" +"``version`` is ``1``. Like attestation objects, provenance objects are " +"versioned, and this PEP only defines version ``1``." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:219 +msgid "" +"``attestation_bundles`` is a **required** JSON array, containing one or more " +"\"bundles\" of attestations. Each bundle corresponds to a signing identity " +"(such as a Trusted Publishing identity), and contains one or more " +"attestation objects." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:224 +msgid "" +"As noted in the ``Publisher`` model, each ``AttestationBundle.publisher`` " +"object is specific to its Trusted Publisher but must include at minimum:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:228 +msgid "" +"A ``kind`` key, which **MUST** be a JSON string that uniquely identifies the " +"kind of Trusted Publisher." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:230 +msgid "" +"A ``claims`` key, which **MUST** be a JSON object containing any context-" +"specific claims retained by the index during Trusted Publisher " +"authentication." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:233 +msgid "All other keys in the publisher object are publisher-specific." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:235 +msgid "" +"Each array of attestation objects is a superset of the ``attestations`` " +"array supplied by the uploaded through the ``attestations`` field at upload " +"time, as described in :ref:`upload-endpoint` and :ref:`changes-to-provenance-" +"objects`." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:243 +msgid "Changes to provenance objects" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:245 +msgid "" +"Provenance objects are *not* immutable, and may change over time. Reasons " +"for changes to the provenance object include but are not limited to:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:248 +msgid "" +"Addition of new attestations for a pre-existing signing identity: the index " +"**MAY** choose to allow additional attestations by pre-existing signing " +"identities, such as newer attestation versions for already uploaded files." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:253 +msgid "" +"Addition of new signing identities and associated attestations: the index " +"**MAY** choose to support attestations from sources other than the file's " +"uploader, such as third-party auditors or the index itself. These " +"attestations may be performed asynchronously, requiring the index to insert " +"them into the provenance object *post facto*." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:262 +msgid "Attestation verification" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:264 +msgid "" +"Verifying an attestation object against a distribution file requires " +"verification of each of the following:" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:267 +msgid "``version`` is ``1``. The verifier **MUST** reject any other version." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:268 +msgid "" +"``verification_material.certificate`` is a valid signing certificate, as " +"issued by an *a priori* trusted authority (such as a root of trust already " +"present within the verifying client)." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:271 +msgid "" +"``verification_material.certificate`` identifies an appropriate signing " +"subject, such as the machine identity of the Trusted Publisher that " +"published the package." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:274 +msgid "" +"``envelope.statement`` is a valid in-toto v1 Statement, with a subject and " +"digest that **MUST** match the distribution's filename and contents. For the " +"distribution's filename, matching **MUST** be performed by parsing using the " +"appropriate source distribution or wheel filename format, as the statement's " +"subject may be equivalent but normalized." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:279 +msgid "" +"``envelope.signature`` is a valid signature for ``envelope.statement`` " +"corresponding to ``verification_material.certificate``, as reconstituted via " +"the `v1 DSSE signature protocol `__." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:284 +msgid "" +"In addition to the above required steps, a verifier **MAY** additionally " +"verify ``verification_material.transparency_entries`` on a policy basis, " +"e.g. requiring at least one transparency log entry or a threshold of " +"entries. When verifying transparency entries, the verifier **MUST** confirm " +"that the inclusion time for each entry lies within the signing certificate's " +"validity period." +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:293 +msgid "Appendix: Data models for Transparency Log Entries" +msgstr "" + +#: ../source/specifications/index-hosted-attestations.rst:295 +msgid "" +"This appendix contains pseudocoded data models for transparency log entries " +"in attestation objects. Each transparency log entry serves as a source of " +"signed inclusion time, and can be verified either online or offline." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:5 +msgid "Inline script metadata" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:7 +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/inline-script-metadata.rst:15 +msgid "" +"This specification defines a metadata comment block format (loosely inspired " +"by `reStructuredText Directives`__)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:20 +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/inline-script-metadata.rst:28 +msgid "" +"Every line between these two lines (``# /// TYPE`` and ``# ///``) MUST be a " +"comment starting with ``#``. If there are characters after the ``#`` then " +"the first character MUST be a space. The embedded content is formed by " +"taking away the first two characters of each line if the second character is " +"a space, otherwise just the first character (which means the line consists " +"of only a single ``#``)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:35 +msgid "" +"Precedence for an ending line ``# ///`` is given when the next line is not a " +"valid embedded content line as described above. For example, the following " +"is a single fully valid block:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:51 +msgid "" +"A starting line MUST NOT be placed between another starting line and its " +"ending line. In such cases tools MAY produce an error. Unclosed blocks MUST " +"be ignored." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:54 +msgid "" +"When there are multiple comment blocks of the same ``TYPE`` defined, tools " +"MUST produce an error." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:57 +msgid "" +"Tools reading embedded metadata MAY respect the standard Python encoding " +"declaration. If they choose not to do so, they MUST process the file as " +"UTF-8." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:60 +msgid "" +"This is the canonical regular expression that MAY be used to parse the " +"metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:67 +msgid "" +"In circumstances where there is a discrepancy between the text specification " +"and the regular expression, the text specification takes precedence." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:70 +msgid "" +"Tools MUST NOT read from metadata blocks with types that have not been " +"standardized by this specification." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:74 +msgid "script type" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:76 +msgid "" +"The first type of metadata block is named ``script``, which contains script " +"metadata (dependency data and tool configuration)." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:79 +msgid "" +"This document MAY include the top-level fields ``dependencies`` and " +"``requires-python``, and MAY optionally include a ``[tool]`` table." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:82 +msgid "" +"The ``[tool]`` table 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/inline-script-metadata.rst:86 +msgid "The top-level fields are:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:88 +msgid "" +"``dependencies``: A list of strings that specifies the runtime dependencies " +"of the script. Each entry MUST be a valid :ref:`dependency specifier " +"`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:91 +msgid "" +"``requires-python``: A string that specifies the Python version(s) with " +"which the script is compatible. The value of this field MUST be a " +"valid :ref:`version specifier `." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:95 +msgid "" +"Script runners MUST error if the specified ``dependencies`` cannot be " +"provided. Script runners SHOULD error if no version of Python that satisfies " +"the specified ``requires-python`` can be provided." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:102 +msgid "The following is an example of a script with embedded metadata:" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:125 +msgid "" +"The following is an example of how to read the metadata on Python 3.11 or " +"higher." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:151 +msgid "" +"Often tools will edit dependencies like package managers or dependency " +"update automation in CI. The following is a crude example of modifying the " +"content using the ``tomlkit`` library__." +msgstr "" + +#: ../source/specifications/inline-script-metadata.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." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:186 +msgid "" +"The following is an example of how to read a stream of arbitrary metadata " +"blocks." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:205 +#: ../source/specifications/simple-repository-api.rst:916 +msgid "Recommendations" +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:207 +msgid "" +"Tools that support managing different versions of Python should attempt to " +"use the highest available version of Python that is compatible with the " +"script's ``requires-python`` metadata, if defined." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:215 +msgid "" +"October 2023: This specification was conditionally approved " +"through :pep:`723`." +msgstr "" + +#: ../source/specifications/inline-script-metadata.rst:216 +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." +msgstr "" + +#: ../source/specifications/license-expression.rst:5 +msgid "" +":pep:`639` defined a new :ref:`pyproject.toml's license ` value and added a corresponding :ref:`core metadata License-" +"Expression field `. This specification " +"defines which license expressions are acceptable." +msgstr "" + +#: ../source/specifications/license-expression.rst:14 +msgid "" +"License can be defined as a text string that is a valid SPDX :term:`license " +"expression `, as documented in the `SPDX specification " +"`__, either Version 2.2 or a later compatible version." +msgstr "" + +#: ../source/specifications/license-expression.rst:19 +msgid "A license expression can use the following license identifiers:" +msgstr "" + +#: ../source/specifications/license-expression.rst:21 +msgid "" +"Any SPDX-listed license short-form identifiers that are published in the " +"`SPDX License List `__, version 3.17 or any later compatible " +"version." +msgstr "" + +#: ../source/specifications/license-expression.rst:25 +msgid "" +"The custom ``LicenseRef-[idstring]`` string(s), where ``[idstring]`` is a " +"unique string containing letters, numbers, ``.`` and/or ``-``, to identify " +"licenses that are not included in the SPDX license list. The custom " +"identifiers must follow the SPDX specification, `clause 10.1 " +"`__ of the given specification version." +msgstr "" + +#: ../source/specifications/license-expression.rst:32 +msgid "Examples of valid license expressions:" +msgstr "" + +#: ../source/specifications/license-expression.rst:45 +msgid "Examples of invalid license expressions:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:3 +#, fuzzy +msgid "Names and normalization" +msgstr "翻譯" + +#: ../source/specifications/name-normalization.rst:5 +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." +msgstr "" + +#: ../source/specifications/name-normalization.rst:13 +msgid "Name format" +msgstr "" + +#: ../source/specifications/name-normalization.rst:15 +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`)::" +msgstr "" + +#: ../source/specifications/name-normalization.rst:26 +#, fuzzy +msgid "Name normalization" +msgstr "翻譯" + +#: ../source/specifications/name-normalization.rst:28 +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:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:39 +msgid "This means that the following names are all equivalent:" +msgstr "" + +#: ../source/specifications/name-normalization.rst:41 +msgid "``friendly-bard`` (normalized form)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:42 +msgid "``Friendly-Bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:43 +msgid "``FRIENDLY-BARD``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:44 +msgid "``friendly.bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:45 +msgid "``friendly_bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:46 +msgid "``friendly--bard``" +msgstr "" + +#: ../source/specifications/name-normalization.rst:47 +msgid "" +"``FrIeNdLy-._.-bArD`` (a *terrible* way to write a name, but it is valid)" +msgstr "" + +#: ../source/specifications/name-normalization.rst:52 +msgid "" +"September 2015: The specification of name normalized was approved " +"through :pep:`503 <503#normalized-names>`." +msgstr "" + +#: ../source/specifications/name-normalization.rst:54 +msgid "" +"November 2015: The specification of valid names was approved " +"through :pep:`508 <508#names>`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:6 +msgid "Platform compatibility tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:8 +msgid "" +"Platform compatibility tags allow build tools to mark distributions as being " +"compatible with specific platforms, and allows installers to understand " +"which distributions are compatible with the system they are running on." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:16 +msgid "The tag format is ``{python tag}-{abi tag}-{platform tag}``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:18 +msgid "python tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:19 +msgid "'py27', 'cp33'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:21 +msgid "'cp32dmu', 'none'" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:23 +msgid "'linux_x86_64', 'any'" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:28 +msgid "" +"The ``wheel`` built package format includes these tags in its filenames, of " +"the form ``{distribution}-{version}(-{build tag})?-{python tag}-{abitag}-" +"{platform tag}.whl``. Other package formats may have their own conventions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:33 +msgid "Any potential spaces in any tag should be replaced with ``_``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:37 +msgid "Python Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:39 +msgid "" +"The Python tag indicates the implementation and version required by a " +"distribution. Major implementations have abbreviated codes, initially:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:42 +msgid "py: Generic Python (does not require implementation-specific features)" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:43 +msgid "cp: CPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:44 +msgid "ip: IronPython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:45 +msgid "pp: PyPy" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:46 +msgid "jy: Jython" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:48 +msgid "" +"Other Python implementations should use :py:data:`sys.implementation.name " +"`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:50 +msgid "" +"The version is ``py_version_nodot``. CPython gets away with no dot, but if " +"one is needed the underscore ``_`` is used instead. PyPy should probably " +"use its own versions here ``pp18``, ``pp19``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:54 +msgid "" +"The version can be just the major version ``2`` or ``3`` ``py2``, ``py3`` " +"for many pure-Python distributions." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:57 +msgid "" +"Importantly, major-version-only tags like ``py2`` and ``py3`` are not " +"shorthand for ``py20`` and ``py30``. Instead, these tags mean the packager " +"intentionally released a cross-version-compatible distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:61 +msgid "" +"A single-source Python 2/3 compatible distribution can use the compound tag " +"``py2.py3``. See `Compressed Tag Sets`_, below." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:66 +msgid "ABI Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:68 +msgid "" +"The ABI tag indicates which Python ABI is required by any included extension " +"modules. For implementation-specific ABIs, the implementation is " +"abbreviated in the same way as the Python Tag, e.g. ``cp33d`` would be the " +"CPython 3.3 ABI with debugging." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:73 +msgid "The CPython stable ABI is ``abi3`` as in the shared library suffix." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:75 +msgid "" +"Implementations with a very unstable ABI may use the first 6 bytes (as 8 " +"base64-encoded characters) of the SHA-256 hash of their source code revision " +"and compiler flags, etc, but will probably not have a great need to " +"distribute binary distributions. Each implementation's community may decide " +"how to best use the ABI tag." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:83 +msgid "Platform Tag" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:86 +msgid "" +"Platform tags are dependent on the versioning of the operating system or " +"platform they represent and may change over time as the underlying platform " +"changes its versioning." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:91 +msgid "Basic platform tags" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:93 +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:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:98 +msgid "win32" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:99 +msgid "linux_i386" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:100 +msgid "linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:106 +msgid "``manylinux``" +msgstr "``manylinux``" + +#: ../source/specifications/platform-compatibility-tags.rst:108 +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 "" + +#: ../source/specifications/platform-compatibility-tags.rst:112 +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." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:117 +msgid "" +"The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. " +"It defines tags of the form :file:`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/platform-compatibility-tags.rst:123 +msgid "" +"The following older tags are still supported for backward compatibility:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:125 +msgid "" +"``manylinux1`` supports glibc 2.5 on ``x86_64`` and ``i686`` architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:126 +msgid "``manylinux2010`` supports glibc 2.12 on ``x86_64`` and ``i686``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:127 +msgid "" +"``manylinux2014`` supports glibc 2.17 on ``x86_64``, ``i686``, ``aarch64``, " +"``armv7l``, ``ppc64``, ``ppc64le``, and ``s390x``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:130 +msgid "" +"In general, distributions built for older versions of the specification are " +"forwards-compatible (meaning that ``manylinux1`` distributions should " +"continue to work on modern systems) but not backwards-compatible (meaning " +"that ``manylinux2010`` distributions are not expected to work on platforms " +"that existed before 2010)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:136 +msgid "" +"Package maintainers should attempt to target the most compatible " +"specification possible, with the caveat that the provided build environment " +"for ``manylinux1`` and ``manylinux2010`` have reached end-of-life meaning " +"that these images will no longer receive security updates." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:141 +msgid "" +"The following table shows the minimum versions of relevant projects to " +"support the various ``manylinux`` standards:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "Tool" +msgstr "工具" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux1``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2010``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux2014``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:145 +msgid "``manylinux_x_y``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=8.1.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=19.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:147 +msgid "``>=20.3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "auditwheel" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=1.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=2.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.0.0``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:148 +msgid "``>=3.3.0`` [#]_" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:151 +msgid "Only support for ``manylinux_2_24`` has been added in auditwheel 3.3.0" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:155 +#, fuzzy +msgid "``musllinux``" +msgstr "維護者" + +#: ../source/specifications/platform-compatibility-tags.rst:157 +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 :file:`musllinux_{x}_{y}_{arch}`, supporting " +"musl ``x.y`` and higher on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:162 +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:193 +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:202 +msgid "" +"macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical " +"artefact of Apple's official macOS naming scheme). The schema for " +"compatibility tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the " +"wheel is compatible with macOS ``x.y`` or later on the architecture ``arch``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:207 +msgid "" +"For macOS 10, the tag is :file:`macosx_10_{y}_{arch}`, where ``y`` " +"corresponds to the minor version number of the macOS release. For macOS 11 " +"and higher, the tag is :file:`macosx_{x}_0_{arch}`, where ``x`` corresponds " +"to the major version number of the macOS release. Following the published " +"macOS major versions, the ``x`` value is either ``10 <= x <= 15``, or " +"``>=26`` and corresponding to the year of the macOS release. For example, " +"``macosx_11_0_arm64`` indicates compatibility with macOS 11 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:215 +msgid "" +"macOS binaries can be compiled for a single architecture, or can include " +"support for multiple architectures in the same binary (sometimes called " +"\"fat\" binaries). To indicate support for a single architecture, the value " +"of ``arch`` must match the value of :py:func:`platform.machine()` on the " +"system. To indicate support multiple architectures, the ``arch`` tag should " +"be an identifier from the following list that describes the set of supported " +"architectures:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "``arch``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:223 +msgid "Architectures supported" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``universal2``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:225 +msgid "``arm64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``universal``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:226 +msgid "``i386``, ``ppc``, ``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``intel``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:227 +msgid "``i386``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``fat``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:228 +msgid "``i386``, ``ppc``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``fat3``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:229 +msgid "``i386``, ``ppc``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``fat64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:230 +msgid "``ppc64``, ``x86_64``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:233 +msgid "" +"The minimum supported macOS version may also be constrained by architecture. " +"For example, macOS 11 (Big Sur) was the first release to support arm64. " +"These additional constraints are enforced transparently by the macOS " +"compilation toolchain when building binaries that support multiple " +"architectures." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:241 +msgid "Android" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:243 +msgid "" +"Android uses the schema :file:`android_{apilevel}_{abi}`, indicating " +"compatibility with the given Android API level or later, on the given ABI. " +"For example, ``android_27_arm64_v8a`` indicates support for API level 27 or " +"later, on ``arm64_v8a`` devices. Android makes no distinction between " +"physical devices and emulated devices." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:249 +msgid "" +"The API level should be a positive integer. This is *not* the same thing as " +"the user-facing Android version. For example, the release known as Android " +"12 (code named \"Snow Cone\") uses API level 31 or 32, depending on the " +"specific Android version in use. Android's release documentation contains " +"the `full list of Android versions and their corresponding API levels " +"`__." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:256 +msgid "" +"There are 4 `supported ABIs `__. Normalized according to the rules above, they are:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:259 +msgid "``armeabi_v7a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:260 +msgid "``arm64_v8a``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:261 +msgid "``x86``" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:264 +msgid "" +"Virtually all current physical devices use one of the ARM architectures. " +"``x86`` and ``x86_64`` are supported for use in the emulator. ``x86`` has " +"not been supported as a development platform since 2020, and no new emulator " +"images have been released since then." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:272 +msgid "iOS" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:274 +msgid "" +"iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating " +"compatibility with iOS ``x.y`` or later, on the ``arch`` architecture, using " +"the ``sdk`` SDK." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:277 +msgid "" +"The value of ``x`` and ``y`` correspond to the major and minor version " +"number of the iOS release, respectively. They must both be positive " +"integers. The version number always includes a major *and* minor version, " +"even if Apple's official version numbering only refers to the major value. " +"For example, a ``ios_13_0_arm64_iphonesimulator`` indicates compatibility " +"with iOS 13 or later." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:283 +msgid "" +"The value of ``arch`` must match the value of :py:func:`platform.machine()` " +"on the system." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:286 +msgid "" +"The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or " +"``iphonesimulator`` (for device simulators). These SDKs have the same API " +"surface, but are incompatible at the binary level, even if they are running " +"on the same CPU architecture. Code compiled for an arm64 simulator will not " +"run on an arm64 device." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:292 +msgid "" +"The combination of :file:`{arch}_{sdk}` is referred to as the \"multiarch\". " +"There are three possible values for multiarch:" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:295 +msgid "" +"``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every " +"iOS device manufactured since ~2015;" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:297 +msgid "" +"``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS " +"hardware; and" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:299 +msgid "``x86_64_iphonesimulator``, for simulators running on x86_64 hardware." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:302 +msgid "Use" +msgstr "使用" + +#: ../source/specifications/platform-compatibility-tags.rst:304 +msgid "" +"The tags are used by installers to decide which built distribution (if any) " +"to download from a list of potential built distributions. The installer " +"maintains a list of (pyver, abi, arch) tuples that it will support. If the " +"built distribution's tag is ``in`` the list, then it can be installed." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:310 +msgid "" +"It is recommended that installers try to choose the most feature complete " +"built distribution available (the one most specific to the installation " +"environment) by default before falling back to pure Python versions " +"published for older Python releases. Installers are also recommended to " +"provide a way to configure and re-order the list of allowed compatibility " +"tags; for example, a user might accept only the ``*-none-any`` tags to only " +"download built packages that advertise themselves as being pure Python." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:318 +msgid "" +"Another desirable installer feature might be to include \"re-compile from " +"source if possible\" as more preferable than some of the compatible but " +"legacy pre-built options." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:322 +msgid "" +"This example list is for an installer running under CPython 3.3 on a " +"linux_x86_64 system. It is in order from most-preferred (a distribution with " +"a compiled extension module, built for the current version of Python) to " +"least-preferred (a pure-Python distribution built with an older version of " +"Python):" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:328 +msgid "cp33-cp33m-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:329 +msgid "cp33-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:330 +msgid "cp3-abi3-linux_x86_64" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:331 +msgid "cp33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:332 +msgid "cp3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:333 +msgid "py33-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:334 +msgid "py3-none-linux_x86_64*" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:335 +msgid "cp33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:336 +msgid "cp3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:337 +msgid "py33-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:338 +msgid "py3-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:339 +msgid "py32-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:340 +msgid "py31-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:341 +msgid "py30-none-any" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:343 +msgid "" +"Built distributions may be platform specific for reasons other than C " +"extensions, such as by including a native executable invoked as a subprocess." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:347 +msgid "" +"Sometimes there will be more than one supported built distribution for a " +"particular version of a package. For example, a packager could release a " +"package tagged ``cp33-abi3-linux_x86_64`` that contains an optional C " +"extension and the same distribution tagged ``py3-none-any`` that does not. " +"The index of the tag in the supported tags list breaks the tie, and the " +"package with the C extension is installed in preference to the package " +"without because that tag appears first in the list." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:356 +msgid "Compressed Tag Sets" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:358 +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, collection of tags. For example, pip, a pure-Python " +"package that is written to run under Python 2 and 3 with the same source " +"code, could distribute a bdist with the tag ``py2.py3-none-any``. The full " +"list of simple tags is::" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:370 +msgid "" +"A bdist format that implements this scheme should include the expanded tags " +"in bdist-specific metadata. This compression scheme can generate large " +"numbers of unsupported tags and \"impossible\" tags that are supported by no " +"Python implementation e.g. \"cp33-cp31u-win64\", so use it sparingly." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:383 +msgid "What tags are used by default?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:379 +msgid "" +"Tools should use the most-preferred architecture dependent tag e.g. ``cp33-" +"cp33m-win32`` or the most-preferred pure python tag e.g. ``py33-none-any`` " +"by default. If the packager overrides the default it indicates that they " +"intended to provide cross-Python compatibility." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:393 +msgid "" +"What tag do I use if my distribution uses a feature exclusive to the newest " +"version of Python?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:386 +msgid "" +"Compatibility tags aid installers in selecting the *most compatible* build " +"of a *single version* of a distribution. For example, when there is no " +"Python 3.3 compatible build of ``beaglevote-1.2.0`` (it uses a Python 3.4 " +"exclusive feature) it may still use the ``py3-none-any`` tag instead of the " +"``py34-none-any`` tag. A Python 3.3 user must combine other qualifiers, such " +"as a requirement for the older release ``beaglevote-1.1.0`` that does not " +"use the new feature, to get a compatible build." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:398 +msgid "Why isn't there a ``.`` in the Python version number?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:396 +msgid "" +"CPython has lasted 20+ years without a 3-digit major release. This should " +"continue for some time. Other implementations may use _ as a delimiter, " +"since both - and . delimit the surrounding filename." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:404 +msgid "" +"Why normalise hyphens and other non-alphanumeric characters to underscores?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:401 +msgid "" +"To avoid conflicting with the ``.`` and ``-`` characters that separate " +"components of the filename, and for better compatibility with the widest " +"range of filesystem limitations for filenames (including being usable in URL " +"paths without quoting)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:413 +msgid "Why not use special character rather than ``.`` or ``-``?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:407 +msgid "" +"Either because that character is inconvenient or potentially confusing in " +"some contexts (for example, ``+`` must be quoted in URLs, ``~`` is used to " +"denote the user's home directory in POSIX), or because the advantages " +"weren't sufficiently compelling to justify changing the existing reference " +"implementation for the wheel format defined in :pep:`427` (for example, " +"using ``,`` rather than ``.`` to separate components in a compressed tag)." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:418 +msgid "Who will maintain the registry of abbreviated implementations?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:416 +msgid "" +"New two-letter abbreviations can be requested on the python-dev mailing " +"list. As a rule of thumb, abbreviations are reserved for the current 4 most " +"prominent implementations." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:423 +msgid "Does the compatibility tag go into METADATA or PKG-INFO?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:421 +msgid "" +"No. The compatibility tag is part of the built distribution's metadata. " +"METADATA / PKG-INFO should be valid for an entire distribution, not a single " +"build of that distribution." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:429 +msgid "Why didn't you mention my favorite Python implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:426 +msgid "" +"The abbreviated tags facilitate sharing compiled Python code in a public " +"index. Your Python implementation can use this specification too, but with " +"longer tags. Recall that all \"pure Python\" built distributions just use " +"``py``." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:437 +msgid "" +"Why is the ABI tag (the second tag) sometimes \"none\" in the reference " +"implementation?" +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:432 +msgid "" +"Since Python 2 does not have an easy way to get to the SOABI (the concept " +"comes from newer versions of Python 3) the reference implementation at the " +"time of writing guesses \"none\". Ideally it would detect \"py27(d|m|u)\" " +"analogous to newer versions of Python, but in the meantime \"none\" is a " +"good enough way to say \"don't know\"." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:442 +msgid "" +"February 2013: The original version of this specification was approved " +"through :pep:`425`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:444 +msgid "January 2016: The ``manylinux1`` tag was approved through :pep:`513`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:445 +msgid "April 2018: The ``manylinux2010`` tag was approved through :pep:`571`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:446 +msgid "July 2019: The ``manylinux2014`` tag was approved through :pep:`599`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:447 +msgid "" +"November 2019: The ``manylinux_x_y`` perennial tag was approved " +"through :pep:`600`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:449 +msgid "April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:450 +msgid "December 2023: The tags for iOS were approved through :pep:`730`." +msgstr "" + +#: ../source/specifications/platform-compatibility-tags.rst:451 +msgid "March 2024: The tags for Android were approved through :pep:`738`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:5 +#, fuzzy +#| msgid "Project name" +msgid "Project Status Markers" +msgstr "專案名稱" + +#: ../source/specifications/project-status-markers.rst:9 +msgid "This specification was originally defined in :pep:`792`." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:14 +msgid "" +":pep:`792` includes changes to the HTML and JSON index APIs. These changes " +"are documented in the :ref:`simple-repository-api` under :ref:`HTML - " +"Project Detail ` and :ref:`JSON - " +"Project Detail `." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:22 +msgid "" +"A project always has exactly one status. If no status is explicitly noted, " +"then the project is considered to be in the ``active`` state." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:25 +msgid "" +"Indices **MAY** implement any subset of the status markers specified, as " +"applicable to their needs." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:28 +msgid "" +"This standard does not prescribe *which* principals (i.e. project " +"maintainers, index administrators, etc.) are allowed to set and unset which " +"statuses." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:32 +msgid "``active``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:34 +msgid "" +"Description: The project is active. This is the default status for a project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:36 +#: ../source/specifications/project-status-markers.rst:49 +#: ../source/specifications/project-status-markers.rst:65 +#: ../source/specifications/project-status-markers.rst:83 +msgid "Index semantics:" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:38 +msgid "" +"The index hosting the project **MUST** allow uploads of new distributions to " +"the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:40 +#: ../source/specifications/project-status-markers.rst:53 +msgid "" +"The index **MUST** offer existing distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:42 +#, fuzzy +#| msgid "Translations" +msgid "Installer semantics: none." +msgstr "翻譯" + +#: ../source/specifications/project-status-markers.rst:45 +msgid "``archived``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:47 +msgid "Description: The project does not expect to be updated in the future." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:51 +#: ../source/specifications/project-status-markers.rst:67 +msgid "" +"The index hosting the project **MUST NOT** allow uploads of new " +"distributions to the project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:55 +#: ../source/specifications/project-status-markers.rst:71 +#: ../source/specifications/project-status-markers.rst:87 +#, fuzzy +msgid "Installer semantics:" +msgstr "安裝軟體套件" + +#: ../source/specifications/project-status-markers.rst:57 +msgid "Installers **MAY** produce warnings about a project's archival." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:60 +msgid "``quarantined``" +msgstr "" + +#: ../source/specifications/project-status-markers.rst:62 +msgid "" +"Description: The project is considered generally unsafe for use, e.g. due to " +"malware." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:69 +msgid "" +"The index **MUST NOT** offer any distributions of the project for download." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:73 +msgid "" +"Installers **MAY** produce warnings about a project's quarantine, although " +"doing so is effectively moot (as the index will not offer any distributions " +"for installation)." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:78 +#, fuzzy +#| msgid "Deprecated" +msgid "``deprecated``" +msgstr "已棄用" + +#: ../source/specifications/project-status-markers.rst:80 +msgid "" +"Description: The project is considered obsolete, and may have been " +"superseded by another project." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:85 +msgid "This status shares the same semantics as ``active``." +msgstr "" + +#: ../source/specifications/project-status-markers.rst:89 +msgid "Installers **MAY** produce warnings about a project's deprecation." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:6 +#, fuzzy +#| msgid "Specification" +msgid "``pylock.toml`` Specification" +msgstr "規格" + +#: ../source/specifications/pylock-toml.rst:8 +msgid "" +"The ``pylock.toml`` file format is for specifying dependencies to enable " +"reproducible installation in a Python environment." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:11 +msgid "This specification was originally defined in :pep:`751`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:16 +msgid "File Name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:18 +msgid "" +"A lock file MUST be named :file:`pylock.toml` or match the regular " +"expression ``r\"^pylock\\.([^.]+)\\.toml$\"`` if a name for the lock file is " +"desired or if multiple lock files exist (i.e. the regular expression " +"``r\"^pylock\\.([^.]+\\.)?toml$\"`` for any file name). The prefix and " +"suffix of a named file MUST be lowercase when possible, for easy detection " +"and removal, e.g.:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:30 +msgid "" +"The expectation is that services that automatically install from lock files " +"will search for:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:33 +msgid "The lock file with the service's name and doing the default install" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:34 +msgid "" +"A multi-use :file:`pylock.toml` with a dependency group with the name of the " +"service" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:35 +msgid "The default install of :file:`pylock.toml`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:37 +msgid "" +"E.g. a cloud host service named \"spam\" would first look " +"for :file:`pylock.spam.toml` to install from, and if that file didn't exist " +"then install from :file:`pylock.toml` and look for a dependency group named " +"\"spam\" to use if present." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:42 +msgid "" +"The lock file(s) SHOULD be located in the directory as appropriate for the " +"scope of the lock file. Locking against a single :file:`pyproject.toml`, for " +"instance, would place the :file:`pylock.toml` in the same directory. If the " +"lock file covered multiple projects in a monorepo, then the expectation is " +"the :file:`pylock.toml` file would be in the directory that held all the " +"projects being locked." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:53 +msgid "The format of the file is TOML_." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:55 +msgid "" +"Tools SHOULD write their lock files in a consistent way to minimize noise in " +"diff output. Keys in tables -- including the top-level table -- SHOULD be " +"recorded in a consistent order (if inspiration is desired, this " +"specification has tried to write down keys in a logical order). As well, " +"tools SHOULD sort arrays in consistent order. Usage of inline tables SHOULD " +"also be kept consistent." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:65 +#, fuzzy +#| msgid "``python_version``" +msgid "``lock-version``" +msgstr "``python_version``" + +#: ../source/specifications/pylock-toml.rst:67 +msgid "**Type**: string; value of ``\"1.0\"``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:68 +#: ../source/specifications/pylock-toml.rst:174 +#: ../source/specifications/pylock-toml.rst:189 +#: ../source/specifications/pylock-toml.rst:202 +#: ../source/specifications/pylock-toml.rst:298 +#: ../source/specifications/pylock-toml.rst:348 +#: ../source/specifications/pylock-toml.rst:397 +#: ../source/specifications/pylock-toml.rst:494 +#: ../source/specifications/pylock-toml.rst:689 +#, fuzzy +#| msgid "Requires" +msgid "**Required?**: yes" +msgstr "需要" + +#: ../source/specifications/pylock-toml.rst:69 +msgid "**Inspiration**: :ref:`core-metadata-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:70 +msgid "Record the file format version that the file adheres to." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:71 +msgid "" +"This PEP specifies the initial version -- and only valid value until future " +"updates to the standard change it -- as ``\"1.0\"``." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:73 +msgid "" +"If a tool supports the major version but not the minor version, a tool " +"SHOULD warn when an unknown key is seen." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:75 +msgid "If a tool doesn't support a major version, it MUST raise an error." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:81 +msgid "``environments``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:83 +#: ../source/specifications/pylock-toml.rst:110 +#: ../source/specifications/pylock-toml.rst:132 +#: ../source/specifications/pylock-toml.rst:154 +msgid "**Type**: Array of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:84 +#: ../source/specifications/pylock-toml.rst:98 +#: ../source/specifications/pylock-toml.rst:213 +#: ../source/specifications/pylock-toml.rst:230 +#: ../source/specifications/pylock-toml.rst:243 +#: ../source/specifications/pylock-toml.rst:255 +#: ../source/specifications/pylock-toml.rst:334 +#: ../source/specifications/pylock-toml.rst:362 +#: ../source/specifications/pylock-toml.rst:435 +#: ../source/specifications/pylock-toml.rst:469 +#: ../source/specifications/pylock-toml.rst:482 +#: ../source/specifications/pylock-toml.rst:519 +#: ../source/specifications/pylock-toml.rst:674 +#: ../source/specifications/pylock-toml.rst:700 +#: ../source/specifications/pylock-toml.rst:715 +msgid "**Required?**: no" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:85 +#: ../source/specifications/pylock-toml.rst:520 +#: ../source/specifications/pylock-toml.rst:538 +msgid "**Inspiration**: uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:86 +msgid "" +"A list of :ref:`dependency-specifiers-environment-markers` for which the " +"lock file is considered compatible with." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:88 +msgid "" +"Tools SHOULD write exclusive/non-overlapping environment markers to ease in " +"understanding." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:97 +#: ../source/specifications/pylock-toml.rst:173 +#: ../source/specifications/pylock-toml.rst:201 +#: ../source/specifications/pylock-toml.rst:212 +#: ../source/specifications/pylock-toml.rst:229 +#: ../source/specifications/pylock-toml.rst:242 +#: ../source/specifications/pylock-toml.rst:308 +#: ../source/specifications/pylock-toml.rst:319 +#: ../source/specifications/pylock-toml.rst:333 +#: ../source/specifications/pylock-toml.rst:347 +#: ../source/specifications/pylock-toml.rst:361 +#: ../source/specifications/pylock-toml.rst:396 +#: ../source/specifications/pylock-toml.rst:518 +#: ../source/specifications/pylock-toml.rst:551 +#: ../source/specifications/pylock-toml.rst:620 +#: ../source/specifications/pylock-toml.rst:688 +msgid "**Type**: string" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:99 +#: ../source/specifications/pylock-toml.rst:190 +#: ../source/specifications/pylock-toml.rst:256 +#: ../source/specifications/pylock-toml.rst:555 +#: ../source/specifications/pylock-toml.rst:608 +#: ../source/specifications/pylock-toml.rst:624 +msgid "**Inspiration**: PDM_, Poetry_, uv_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:100 +msgid "" +"Specifies the :ref:`core-metadata-requires-python` for the minimum Python " +"version compatible for any environment supported by the lock file (i.e. the " +"minimum viable Python version for the lock file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:111 +#: ../source/specifications/pylock-toml.rst:133 +#: ../source/specifications/pylock-toml.rst:155 +msgid "**Required?**: no; defaults to ``[]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:112 +msgid "**Inspiration**: :ref:`core-metadata-provides-extra`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:113 +msgid "" +"The list of :ref:`extras ` supported by this " +"lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:115 +#: ../source/specifications/pylock-toml.rst:138 +msgid "" +"Lockers MAY choose to not support writing lock files that support extras and " +"dependency groups (i.e. tools may only support exporting a single-use lock " +"file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:118 +msgid "Tools supporting extras MUST also support dependency groups." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:119 +msgid "" +"Tools should explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no extras (e.g. " +"a :ref:`pyproject.toml ` file had " +"no :ref:`[project.optional-dependencies] ` table), signalling that the lock file is, in effect, multi-" +"use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:130 +msgid "``dependency-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:134 +#: ../source/specifications/pylock-toml.rst:701 +#: ../source/specifications/pylock-toml.rst:716 +#, fuzzy +#| msgid "Project name" +msgid "**Inspiration**: :ref:`pyproject-tool-table`" +msgstr "專案名稱" + +#: ../source/specifications/pylock-toml.rst:135 +msgid "" +"The list of :ref:`dependency-groups` publicly supported by this lock file " +"(i.e. dependency groups users are expected to be able to specify via a " +"tool's UI)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:141 +msgid "Tools supporting dependency groups MUST also support extras." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:142 +msgid "" +"Tools SHOULD explicitly set this key to an empty array to signal that the " +"inputs used to generate the lock file had no dependency groups (e.g. " +"a :ref:`pyproject.toml ` file had no :ref:`[dependency-" +"groups] ` table), signalling that the lock file is, in " +"effect, multi-use even if it only looks to be single-use." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:152 +msgid "``default-groups``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:156 +msgid "**Inspiration**: Poetry_, PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:157 +msgid "" +"The name of synthetic dependency groups to represent what should be " +"installed by default (e.g. what :ref:`[project.dependencies] ` implicitly represents)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:161 +msgid "" +"Meant to be used in situations where :ref:`pylock-packages-marker` " +"necessitates such a group to exist." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:163 +msgid "" +"The groups listed by this key SHOULD NOT be listed in :ref:`pylock-" +"dependency-groups` as the groups are not meant to be directly exposed to " +"users by name but instead via an installer's UI." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:171 +msgid "``created-by``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:175 +msgid "**Inspiration**: Tools with their name in their lock file name" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:176 +msgid "Records the name of the tool used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:177 +msgid "" +"Tools MAY use the :ref:`pylock-tool` table to record enough details that it " +"can be inferred what inputs were used to create the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:179 +msgid "" +"Tools SHOULD record the normalized name of the tool if it is available as a " +"Python package to facilitate finding the tool." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:186 +#, fuzzy +#| msgid "Package Index" +msgid "``[[packages]]``" +msgstr "套件索引" + +#: ../source/specifications/pylock-toml.rst:188 +#: ../source/specifications/pylock-toml.rst:254 +#: ../source/specifications/pylock-toml.rst:605 +#: ../source/specifications/pylock-toml.rst:673 +msgid "**Type**: array of tables" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:191 +msgid "An array containing all packages that *may* be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:192 +msgid "" +"Packages MAY be listed multiple times with varying data, but all packages to " +"be installed MUST narrow down to a single entry at install time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:199 +msgid "``packages.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:203 +msgid "**Inspiration**: :ref:`core-metadata-name`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:204 +msgid "The name of the package :ref:`normalized `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:210 +#, fuzzy +#| msgid "``python_version``" +msgid "``packages.version``" +msgstr "``python_version``" + +#: ../source/specifications/pylock-toml.rst:214 +msgid "**Inspiration**: :ref:`core-metadata-version`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:215 +#, fuzzy +#| msgid "and import the package:" +msgid "The version of the package." +msgstr "然後載入那個套件:" + +#: ../source/specifications/pylock-toml.rst:216 +msgid "" +"The version SHOULD be specified when the version is known to be stable (i.e. " +"when an :ref:`sdist ` or :ref:`wheels ` are specified)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:219 +msgid "" +"The version MUST NOT be included when it cannot be guaranteed to be " +"consistent with the code used (i.e. when a :ref:`source tree ` is used)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:227 +msgid "``packages.marker``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:231 +msgid "**Inspiration**: PDM_" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:232 +msgid "" +"The :ref:`environment marker ` " +"which specify when the package should be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:240 +msgid "``packages.requires-python``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:244 +msgid "**Inspiration**: :ref:`core-metadata-requires-python`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:245 +msgid "" +"Holds the :ref:`version-specifiers` for Python version compatibility for the " +"package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:252 +msgid "``[[packages.dependencies]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:257 +msgid "" +"Records the other entries in :ref:`pylock-packages` which are direct " +"dependencies of this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:259 +msgid "" +"Each entry is a table which contains the minimum information required to " +"tell which other package entry it corresponds to where doing a key-by-key " +"comparison would find the appropriate package with no ambiguity (e.g. if " +"there are two entries for the ``spam`` package, then you can include the " +"version number like ``{name = \"spam\", version = \"1.0.0\"}``, or by source " +"like ``{name = \"spam\", vcs = { url = \"...\"}``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:265 +msgid "" +"Tools MUST NOT use this information when doing installation; it is purely " +"informational for auditing purposes." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:272 +msgid "``[packages.vcs]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:274 +#: ../source/specifications/pylock-toml.rst:376 +#: ../source/specifications/pylock-toml.rst:434 +#: ../source/specifications/pylock-toml.rst:535 +#: ../source/specifications/pylock-toml.rst:699 +#: ../source/specifications/pylock-toml.rst:714 +msgid "**Type**: table" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:275 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"directory`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:278 +msgid "**Inspiration**: :ref:`direct-url-data-structure`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:279 +msgid "" +"Record the version control system details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:282 +msgid "" +"Tools MAY choose to not support version control systems, both from a locking " +"and/or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:284 +msgid "Tools MAY choose to only support a subset of the available VCS types." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:285 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using version control " +"systems." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:287 +msgid "" +"Installation from a version control system is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:294 +msgid "``packages.vcs.type``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:296 +msgid "" +"**Type**: string; supported values specified in :ref:`direct-url-data-" +"structure-registered-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:299 +#: ../source/specifications/pylock-toml.rst:310 +#: ../source/specifications/pylock-toml.rst:321 +#: ../source/specifications/pylock-toml.rst:335 +#: ../source/specifications/pylock-toml.rst:349 +msgid "**Inspiration**: :ref:`direct-url-data-structure-vcs`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:300 +msgid "The type of version control system used." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:306 +msgid "``packages.vcs.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:309 +msgid "**Required?**: if :ref:`pylock-packages-vcs-path` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:311 +msgid "The URL_ to the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:317 +msgid "``packages.vcs.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:320 +msgid "**Required?**: if :ref:`pylock-packages-vcs-url` is not specified" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:322 +msgid "The path to the local directory of the source tree." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:323 +msgid "" +"If a relative path is used it MUST be relative to the location of this file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:324 +msgid "" +"If the path is relative it MAY use POSIX-style path separators explicitly " +"for portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:331 +msgid "``packages.vcs.requested-revision``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:336 +msgid "The branch/tag/ref/commit/revision/etc. that the user requested." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:337 +msgid "" +"This is purely informational and to facilitate writing the :ref:`direct-url-" +"data-structure`; it MUST NOT be used to checkout the repository." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:345 +msgid "``packages.vcs.commit-id``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:350 +msgid "The exact commit/revision number that is to be installed." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:351 +msgid "" +"If the VCS supports commit-hash based revision identifiers, such a commit-" +"hash, it MUST be used as the commit ID in order to reference an immutable " +"version of the source code." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:359 +msgid "``packages.vcs.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:363 +msgid "**Inspiration**: :ref:`direct-url-data-structure-subdirectories`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:364 +msgid "" +"The subdirectory within the :ref:`source tree ` where the project root of the project is (e.g. the location of " +"the :ref:`pyproject.toml ` file)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:368 +msgid "The path MUST be relative to the root of the source tree structure." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:374 +msgid "``[packages.directory]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:377 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, " +"and :ref:`pylock-packages-wheels`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:380 +#: ../source/specifications/pylock-toml.rst:398 +#: ../source/specifications/pylock-toml.rst:412 +msgid "**Inspiration**: :ref:`direct-url-data-structure-local-directory`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:381 +msgid "" +"Record the local directory details for the :ref:`source tree ` it contains." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:384 +msgid "" +"Tools MAY choose to not support local directories, both from a locking and/" +"or installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:386 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using local " +"directories." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:387 +msgid "" +"Installation from a directory is considered originating from a :ref:`direct " +"URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:394 +msgid "``packages.directory.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:399 +msgid "The local directory where the source tree is." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:400 +msgid "" +"If the path is relative it MUST be relative to the location of the lock file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:401 +msgid "" +"If the path is relative it MAY use POSIX-style path separators for " +"portability." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:408 +msgid "``packages.directory.editable``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:410 +msgid "**Type**: boolean" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:411 +msgid "**Required?**: no; defaults to ``false``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:413 +msgid "" +"A flag representing whether the source tree was an editable install at lock " +"time." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:415 +msgid "" +"An installer MAY choose to ignore this flag if user actions or context would " +"make an editable install unnecessary or undesirable (e.g. a container image " +"that will not be mounted for development purposes but instead deployed to " +"production where it would be treated at read-only)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:424 +msgid "``packages.directory.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:426 +#: ../source/specifications/pylock-toml.rst:510 +msgid "See :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:432 +msgid "``[packages.archive]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:436 +msgid "**Inspiration**: :ref:`direct-url-data-structure-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:437 +msgid "" +"A direct reference to an archive file to install from (this can include " +"wheels and sdists, as well as other archive formats containing a source " +"tree)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:440 +msgid "" +"Tools MAY choose to not support archive files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:442 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using archive files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:443 +msgid "" +"Installation from an archive file is considered originating from " +"a :ref:`direct URL reference `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:450 +msgid "``packages.archive.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:452 +msgid "See :ref:`pylock-packages-vcs-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:458 +msgid "``packages.archive.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:460 +msgid "See :ref:`pylock-packages-vcs-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:466 +msgid "``packages.archive.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:468 +msgid "**Type**: integer" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:470 +msgid "**Inspiration**: uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:471 +msgid "The size of the archive file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:472 +msgid "" +"Tools SHOULD provide the file size when reasonably possible (e.g. the file " +"size is available via the Content-Length_ header from a HEAD_ HTTP request)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:479 +msgid "``packages.archive.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:481 +msgid "**Type**: datetime" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:483 +msgid "**Inspiration**: :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:484 +msgid "The time the file was uploaded." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:485 +msgid "The date and time MUST be recorded in UTC." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:491 +msgid "``[packages.archive.hashes]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:493 +msgid "**Type**: Table of strings" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:495 +msgid "**Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:496 +msgid "" +"A table listing known hash values of the file where the key is the hash " +"algorithm and the value is the hash value." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:498 +msgid "The table MUST contain at least one entry." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:499 +msgid "Hash algorithm keys SHOULD be lowercase." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:500 +msgid "" +"At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed` " +"SHOULD always be included (at time of writing, sha256 specifically is " +"recommended." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:508 +msgid "``packages.archive.subdirectory``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:516 +#, fuzzy +#| msgid "Package Index" +msgid "``packages.index``" +msgstr "套件索引" + +#: ../source/specifications/pylock-toml.rst:521 +msgid "" +"The base URL for the package index from :ref:`simple-repository-api` where " +"the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:523 +msgid "" +"When possible, this SHOULD be specified to assist with generating `software " +"bill of materials`_ -- aka SBOMs -- and to assist in finding a file if a URL " +"ceases to be valid." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:526 +msgid "" +"Tools MAY support installing from an index if the URL recorded for a " +"specific file is no longer valid (e.g. returns a 404 HTTP error code)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:533 +msgid "``[packages.sdist]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:536 +#: ../source/specifications/pylock-toml.rst:606 +msgid "" +"**Required?**: no; mutually-exclusive with :ref:`pylock-packages-" +"vcs`, :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:539 +msgid "Details of a :ref:`source-distribution-format-sdist` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:541 +msgid "" +"Tools MAY choose to not support sdist files, both from a locking and/or " +"installation perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:543 +msgid "" +"Tools SHOULD provide a way for users to opt in/out of using sdist files." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:549 +msgid "``packages.sdist.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:552 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"sdist-path`/ :ref:`pylock-packages-sdist-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:556 +msgid "The file name of the :ref:`source-distribution-format-sdist` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:562 +msgid "``packages.sdist.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:564 +#: ../source/specifications/pylock-toml.rst:633 +msgid "See :ref:`pylock-packages-archive-upload-time`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:570 +msgid "``packages.sdist.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:572 +#: ../source/specifications/pylock-toml.rst:641 +msgid "See :ref:`pylock-packages-archive-url`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:578 +msgid "``packages.sdist.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:580 +#: ../source/specifications/pylock-toml.rst:649 +msgid "See :ref:`pylock-packages-archive-path`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:586 +msgid "``packages.sdist.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:588 +#: ../source/specifications/pylock-toml.rst:657 +msgid "See :ref:`pylock-packages-archive-size`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:594 +msgid "``packages.sdist.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:596 +#: ../source/specifications/pylock-toml.rst:665 +msgid "See :ref:`pylock-packages-archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:603 +msgid "``[[packages.wheels]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:609 +msgid "" +"For recording the wheel files as specified by :ref:`binary-distribution-" +"format` for the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:611 +msgid "" +"Tools MUST support wheel files, both from a locking and installation " +"perspective." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:618 +msgid "``packages.wheels.name``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:621 +msgid "" +"**Required?**: no, not when the last component of :ref:`pylock-packages-" +"wheels-path`/ :ref:`pylock-packages-wheels-url` would be the same value" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:625 +msgid "The file name of the :ref:`binary-distribution-format` file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:631 +msgid "``packages.wheels.upload-time``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:639 +msgid "``packages.wheels.url``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:647 +msgid "``packages.wheels.path``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:655 +msgid "``packages.wheels.size``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:663 +msgid "``packages.wheels.hashes``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:671 +msgid "``[[packages.attestation-identities]]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:675 +#: ../source/specifications/pylock-toml.rst:690 +#, fuzzy +#| msgid "Project name" +msgid "**Inspiration**: :ref:`provenance-object`" +msgstr "專案名稱" + +#: ../source/specifications/pylock-toml.rst:676 +msgid "" +"A recording of the attestations for **any** file recorded for this package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:677 +msgid "If available, tools SHOULD include the attestation identities found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:678 +msgid "" +"Publisher-specific keys are to be included in the table as-is (i.e. top-" +"level), following the spec at :ref:`index-hosted-attestations`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:686 +msgid "``packages.attestation-identities.kind``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:691 +msgid "The unique identity of the Trusted Publisher." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:697 +msgid "``[packages.tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:702 +msgid "" +"Similar usage as that of the :ref:`pylock-tool` table from " +"the :ref:`pyproject-toml-spec`, but at the package version level instead of " +"at the lock file level (which is also available via :ref:`pylock-tool`)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:705 +msgid "" +"Data recorded in the table MUST be disposable (i.e. it MUST NOT affect " +"installation)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:712 +msgid "``[tool]``" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:717 +msgid "See :ref:`pylock-packages-tool`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:731 +msgid "" +"The following outlines the steps to be taken to install from a lock file " +"(while the requirements are prescriptive, the general steps and order are a " +"suggestion):" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:735 +msgid "" +"Gather the extras and dependency groups to install and set ``extras`` and " +"``dependency_groups`` for marker evaluation, respectively." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:738 +msgid "``extras`` SHOULD be set to the empty set by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:739 +msgid "" +"``dependency_groups`` SHOULD be the set created from :ref:`pylock-default-" +"groups` by default." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:742 +msgid "" +"Check if the metadata version specified by :ref:`pylock-lock-version` is " +"supported; an error or warning MUST be raised as appropriate." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:744 +msgid "" +"If :ref:`pylock-requires-python` is specified, check that the environment " +"being installed for meets the requirement; an error MUST be raised if it is " +"not met." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:747 +msgid "" +"If :ref:`pylock-environments` is specified, check that at least one of the " +"environment marker expressions is satisfied; an error MUST be raised if no " +"expression is satisfied." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:750 +msgid "For each package listed in :ref:`pylock-packages`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:752 +msgid "" +"If :ref:`pylock-packages-marker` is specified, check if it is satisfied; if " +"it isn't, skip to the next package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:754 +msgid "" +"If :ref:`pylock-packages-requires-python` is specified, check if it is " +"satisfied; an error MUST be raised if it isn't." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:756 +msgid "" +"Check that no other conflicting instance of the package has been slated to " +"be installed; an error about the ambiguity MUST be raised otherwise." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:758 +msgid "" +"Check that the source of the package is specified appropriately (i.e. there " +"are no conflicting sources in the package entry); an error MUST be raised if " +"any issues are found." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:761 +msgid "Add the package to the set of packages to install." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:763 +msgid "For each package to be installed:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:765 +msgid "If :ref:`pylock-packages-vcs` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:767 +msgid "" +"Clone the repository to the commit ID specified in :ref:`pylock-packages-vcs-" +"commit-id`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:769 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-vcs-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:771 +#: ../source/specifications/pylock-toml.rst:777 +#: ../source/specifications/pylock-toml.rst:786 +#: ../source/specifications/pylock-toml.rst:806 +#: ../source/specifications/pylock-toml.rst:821 +msgid ":ref:`Install `." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:773 +msgid "Else if :ref:`pylock-packages-directory` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:775 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-directory-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:779 +msgid "Else if :ref:`pylock-packages-archive` is set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:781 +#: ../source/specifications/pylock-toml.rst:811 +msgid "Get the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:782 +msgid "" +"Validate using :ref:`pylock-packages-archive-size` and :ref:`pylock-packages-" +"archive-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:784 +msgid "" +":ref:`Build ` the package, " +"respecting :ref:`pylock-packages-archive-subdirectory`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:788 +msgid "Else if there are entries for :ref:`pylock-packages-wheels`:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:790 +msgid "" +"Look for the appropriate wheel file based on :ref:`pylock-packages-wheels-" +"name`; if one is not found then move on to :ref:`pylock-packages-sdist` or " +"an error MUST be raised about a lack of source for the project." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:794 +msgid "Get the file:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:796 +msgid "If :ref:`pylock-packages-wheels-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:797 +msgid "" +"Else if :ref:`pylock-packages-wheels-url` is set, try to use it; optionally " +"tools MAY use :ref:`pylock-packages-index` or some tool-specific mechanism " +"to download the selected wheel file (tools MUST NOT try to change what wheel " +"file to download based on what's available; what file to install should be " +"determined in an offline fashion for reproducibility)." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:804 +msgid "" +"Validate using :ref:`pylock-packages-wheels-size` and :ref:`pylock-packages-" +"wheels-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:808 +msgid "" +"Else if no :ref:`pylock-packages-wheels` file is found or :ref:`pylock-" +"packages-sdist` is solely set:" +msgstr "" + +#: ../source/specifications/pylock-toml.rst:813 +msgid "If :ref:`pylock-packages-sdist-path` is set, use it." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:814 +msgid "" +"Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools MAY " +"use :ref:`pylock-packages-index` or some tool-specific mechanism to download " +"the file." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:818 +msgid "" +"Validate using :ref:`pylock-packages-sdist-size` and :ref:`pylock-packages-" +"sdist-hashes`." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:820 +msgid ":ref:`Build ` the package." +msgstr "" + +#: ../source/specifications/pylock-toml.rst:828 +msgid "April 2025: Initial version, approved via :pep:`751`." +msgstr "" + +#: ../source/specifications/pypirc.rst:6 +msgid "The :file:`.pypirc` file" +msgstr "" + +#: ../source/specifications/pypirc.rst:8 +msgid "" +"A :file:`.pypirc` file allows you to define the configuration " +"for :term:`package indexes ` (referred to here as " +"\"repositories\"), so that you don't have to enter the URL, username, or " +"password whenever you upload a package with :ref:`twine` or :ref:`flit`." +msgstr "" + +#: ../source/specifications/pypirc.rst:13 +msgid "The :file:`.pypirc` file **SHOULD** be UTF-8 encoded." +msgstr "" + +#: ../source/specifications/pypirc.rst:15 +msgid "" +"Tools that read or write :file:`.pypirc` files may not function correctly if " +"another character encoding is used." +msgstr "" + +#: ../source/specifications/pypirc.rst:18 +msgid "The format (originally defined by the :ref:`distutils` package) is:" +msgstr "" + +#: ../source/specifications/pypirc.rst:37 +msgid "" +"The ``distutils`` section defines an ``index-servers`` field that lists the " +"name of all sections describing a repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:40 +msgid "Each section describing a repository defines three fields:" +msgstr "" + +#: ../source/specifications/pypirc.rst:42 +msgid "``repository``: The URL of the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:43 +msgid "``username``: The registered username on the repository." +msgstr "" + +#: ../source/specifications/pypirc.rst:44 +msgid "``password``: The password that will used to authenticate the username." +msgstr "" + +#: ../source/specifications/pypirc.rst:48 +msgid "" +"Be aware that this stores your password in plain text. For better security, " +"consider an alternative like `keyring`_, setting environment variables, or " +"providing the password on the command line." +msgstr "" + +#: ../source/specifications/pypirc.rst:52 +msgid "" +"Otherwise, set the permissions on :file:`.pypirc` so that only you can view " +"or modify it. For example, on Linux or macOS, run:" +msgstr "" + +#: ../source/specifications/pypirc.rst:62 +msgid "Common configurations" +msgstr "" + +#: ../source/specifications/pypirc.rst:66 +msgid "" +"These examples apply to :ref:`twine`. Other projects (e.g. :ref:`flit`) also " +"use :file:`.pypirc`, but with different defaults. Please refer to each " +"project's documentation for more details and usage instructions." +msgstr "" + +#: ../source/specifications/pypirc.rst:70 +msgid "" +"Twine's default configuration mimics a :file:`.pypirc` with repository " +"sections for PyPI and TestPyPI:" +msgstr "" + +#: ../source/specifications/pypirc.rst:86 +msgid "" +"Twine will add additional configuration from :file:`$HOME/.pypirc`, the " +"command line, and environment variables to this default configuration." +msgstr "" + +#: ../source/specifications/pypirc.rst:90 +msgid "Using a PyPI token" +msgstr "" + +#: ../source/specifications/pypirc.rst:92 +msgid "" +"To set your `API token`_ for PyPI, you can create a :file:`$HOME/.pypirc` " +"similar to:" +msgstr "" + +#: ../source/specifications/pypirc.rst:101 +msgid "" +"For :ref:`TestPyPI `, add a ``[testpypi]`` section, using " +"the API token from your TestPyPI account." +msgstr "" + +#: ../source/specifications/pypirc.rst:107 +msgid "Using another package index" +msgstr "" + +#: ../source/specifications/pypirc.rst:109 +msgid "" +"To configure an additional repository, you'll need to redefine the ``index-" +"servers`` field to include the repository name. Here is a complete example " +"of a :file:`$HOME/.pypirc` for PyPI, TestPyPI, and a private repository:" +msgstr "" + +#: ../source/specifications/pypirc.rst:136 +msgid "" +"Instead of using the ``password`` field, consider saving your API tokens and " +"passwords securely using `keyring`_ (which is installed by Twine):" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:6 +msgid "``pyproject.toml`` specification" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:10 +msgid "" +"This is a **technical, formal specification**. For a gentle, user-friendly " +"guide to ``pyproject.toml``, see :ref:`writing-pyproject-toml`." +msgstr "" + +#: ../source/specifications/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/pyproject-toml.rst:17 +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/pyproject-toml.rst:27 +msgid "Declaring build system dependencies: the ``[build-system]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:29 +msgid "" +"The ``[build-system]`` table declares any Python level dependencies that " +"must be installed in order to run the project's build system successfully." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:35 +msgid "" +"The ``[build-system]`` table is used to store build-related data. Initially, " +"only one key of the table is valid and is mandatory for the table: " +"``requires``. This key must have a value of a list of strings representing " +"dependencies required to execute the build system. The strings in this list " +"follow the :ref:`version specifier specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:42 +msgid "" +"An example ``[build-system]`` table for a project built with ``setuptools`` " +"is:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:51 +msgid "" +"Build tools are expected to use the example configuration file above as " +"their default semantics when a ``pyproject.toml`` file is not present." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:54 +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:62 +msgid "" +"Tools may choose to present an error to the user if the file exists, " +"``[build-system]`` table is missing, and there is no clear indication that " +"the project should be built (e.g., no setup.py/setup.cfg or other build " +"configuration files, and no ``[project]`` table)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:67 +msgid "" +"To provide a type-specific representation of the resulting data from the " +"TOML file for illustrative purposes only, the following `JSON Schema " +"`_ would match the data format:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:105 +msgid "Declaring project metadata: the ``[project]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:107 +msgid "" +"The ``[project]`` table specifies the project's :ref:`core metadata `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:109 +msgid "" +"There are two kinds of metadata: *static* and *dynamic*. Static metadata is " +"specified in the ``pyproject.toml`` file directly and cannot be specified or " +"changed by a tool (this includes data *referred* to by the metadata, e.g. " +"the contents of files referenced by the metadata). Dynamic metadata is " +"listed via the ``dynamic`` key (defined later in this specification) and " +"represents metadata that a tool will later provide." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:117 +msgid "" +"The lack of a ``[project]`` table implicitly means the :term:`build backend " +"` will dynamically provide all keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:120 +msgid "The only keys required to be statically defined are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:124 +msgid "" +"The keys which are required but may be specified *either* statically or " +"listed as dynamic are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:129 +msgid "" +"All other keys are considered optional and may be specified statically, " +"listed as dynamic, or left unspecified." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:132 +msgid "The complete list of keys allowed in the ``[project]`` table are:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:134 +msgid "``authors``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:136 +msgid "``dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:138 +#: ../source/specifications/pyproject-toml.rst:574 +msgid "``dynamic``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:139 +msgid "``entry-points``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:140 +msgid "``gui-scripts``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:141 +#: ../source/specifications/pyproject-toml.rst:482 +msgid "``import-names``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:142 +#: ../source/specifications/pyproject-toml.rst:533 +msgid "``import-namespaces``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:146 +#, fuzzy +msgid "``maintainers``" +msgstr "維護者" + +#: ../source/specifications/pyproject-toml.rst:148 +msgid "``optional-dependencies``" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:161 +#: ../source/specifications/pyproject-toml.rst:176 +#: ../source/specifications/pyproject-toml.rst:191 +#: ../source/specifications/pyproject-toml.rst:245 +#: ../source/specifications/pyproject-toml.rst:257 +msgid "TOML_ type: string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:162 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Name `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:165 +msgid "The name of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:167 +msgid "" +"Tools SHOULD :ref:`normalize ` this name, as soon as it " +"is read for internal consistency." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:177 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Version " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:180 +msgid "" +"The version of the project, as defined in the :ref:`Version specifier " +"specification `." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:183 +msgid "Users SHOULD prefer to specify already-normalized versions." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:192 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Summary " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:195 +msgid "" +"The summary description of the project in one line. Tools MAY error if this " +"includes multiple lines." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:204 +msgid "TOML_ type: string or table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:205 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Description " +"` and :ref:`Description-Content-Type `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:209 +msgid "The full description of the project (i.e. the README)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:211 +msgid "" +"The key accepts either a string or a table. If it is a string then it is a " +"path relative to ``pyproject.toml`` to a text file containing the full " +"description. Tools MUST assume the file's encoding is UTF-8. If the file " +"path ends in a case-insensitive ``.md`` suffix, then tools MUST assume the " +"content-type is ``text/markdown``. If the file path ends in a case-" +"insensitive ``.rst``, then tools MUST assume the content-type is ``text/x-" +"rst``. If a tool recognizes more extensions than this PEP, they MAY infer " +"the content-type for the user without specifying this key as ``dynamic``. " +"For all unrecognized suffixes when a content-type is not provided, tools " +"MUST raise an error." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:222 +msgid "" +"The ``readme`` key may also take a table. The ``file`` key has a string " +"value representing a path relative to ``pyproject.toml`` to a file " +"containing the full description. The ``text`` key has a string value which " +"is the full description. These keys are mutually-exclusive, thus tools MUST " +"raise an error if the metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:229 +msgid "" +"A table specified in the ``readme`` key also has a ``content-type`` key " +"which takes a string specifying the content-type of the full description. A " +"tool MUST raise an error if the metadata does not specify this key in the " +"table. If the metadata does not specify the ``charset`` parameter, then it " +"is assumed to be UTF-8. Tools MAY support other encodings if they choose to. " +"Tools MAY support alternative content-types which they can transform to a " +"content-type as supported by the :ref:`core metadata `. " +"Otherwise tools MUST raise an error for unsupported content-types." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:246 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Python `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:249 +msgid "The Python version requirements of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:258 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-" +"Expression `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:261 +msgid "" +"Text string that is a valid SPDX :term:`license expression `, as specified in :doc:`/specifications/license-expression`. " +"Tools SHOULD validate and perform case normalization of the expression." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:266 +msgid "" +"This key should **only** be specified if the license expression for any and " +"all distribution files created by a build backend using " +"the :file:`pyproject.toml` is the same as the one specified. If the license " +"expression will differ then it should either be specified as dynamic or not " +"set at all." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:273 +#, fuzzy +#| msgid "Specification" +msgid "Legacy specification" +msgstr "規格" + +#: ../source/specifications/pyproject-toml.rst:275 +msgid "TOML_ type: table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:276 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:279 +msgid "" +"The table may have one of two keys. The ``file`` key has a string value that " +"is a file path relative to :file:`pyproject.toml` to the file which contains " +"the license for the project. Tools MUST assume the file's encoding is UTF-8. " +"The ``text`` key has a string value which is the license of the project. " +"These keys are mutually exclusive, so a tool MUST raise an error if the " +"metadata specifies both keys." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:286 +msgid "" +"The table subkeys were deprecated by :pep:`639` in favor of the string value." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:293 +#: ../source/specifications/pyproject-toml.rst:376 +#: ../source/specifications/pyproject-toml.rst:388 +#: ../source/specifications/pyproject-toml.rst:484 +#: ../source/specifications/pyproject-toml.rst:535 +msgid "TOML_ type: array of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:294 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`License-File " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:297 +msgid "" +"An array specifying paths in the project source tree relative to the project " +"root directory (i.e. directory containing :file:`pyproject.toml` or legacy " +"project configuration files, e.g. :file:`setup.py`, :file:`setup.cfg`, etc.) " +"to file(s) containing licenses and other legal notices to be distributed " +"with the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:303 +msgid "" +"The strings MUST contain valid glob patterns, as specified in :doc:`/" +"specifications/glob-patterns`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:306 +msgid "" +"Patterns are relative to the directory containing :file:`pyproject.toml`," +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:308 +msgid "" +"Tools MUST assume that license file content is valid UTF-8 encoded text, and " +"SHOULD validate this and raise an error if it is not." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:311 +msgid "Build tools:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:313 +msgid "" +"MUST include all files matched by a listed pattern in all distribution " +"archives." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:315 +msgid "" +"MUST list each matched file path under a License-File field in the Core " +"Metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:318 +msgid "" +"If the ``license-files`` key is present and is set to a value of an empty " +"array, then tools MUST NOT include any license files and MUST NOT raise an " +"error. If the ``license-files`` key is not defined, tools can decide how to " +"handle license files. For example they can choose not to include any files " +"or use their own logic to discover the appropriate files in the distribution." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:332 +msgid "TOML_ type: Array of inline tables with string keys and values" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:333 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Author `, :ref:`Author-email `, :ref:`Maintainer `, and :ref:`Maintainer-" +"email `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:339 +msgid "" +"The people or organizations considered to be the \"authors\" of the project. " +"The exact meaning is open to interpretation — it may list the original or " +"primary authors, current maintainers, or owners of the package." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:344 +msgid "" +"The \"maintainers\" key is similar to \"authors\" in that its exact meaning " +"is open to interpretation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:347 +msgid "" +"These keys accept an array of tables with 2 keys: ``name`` and ``email``. " +"Both values must be strings. The ``name`` value MUST be a valid email name " +"(i.e. whatever can be put as a name, before an email, in :rfc:`822`) and not " +"contain commas. The ``email`` value MUST be a valid email address. Both keys " +"are optional, but at least one of the keys must be specified in the table." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:354 +msgid "" +"Using the data to fill in :ref:`core metadata ` is as follows:" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:357 +msgid "" +"If only ``name`` is provided, the value goes in :ref:`Author ` or :ref:`Maintainer ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:360 +msgid "" +"If only ``email`` is provided, the value goes in :ref:`Author-email ` or :ref:`Maintainer-email ` as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:364 +msgid "" +"If both ``email`` and ``name`` are provided, the value goes in :ref:`Author-" +"email ` or :ref:`Maintainer-email ` as appropriate, with the format ``{name} <{email}>``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:368 +msgid "Multiple values should be separated by commas." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:377 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Keywords " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:380 +msgid "The keywords for the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:389 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Classifier " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:392 +msgid "Trove classifiers which apply to the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:394 +msgid "" +"The use of ``License ::`` classifiers is deprecated and tools MAY issue a " +"warning informing users about that. Build tools MAY raise an error if both " +"the ``license`` string value (translating to ``License-Expression`` metadata " +"field) and the ``License ::`` classifiers are used." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:406 +msgid "TOML_ type: table with keys and values of strings" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:407 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Project-URL " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:410 +msgid "" +"A table of URLs where the key is the URL label and the value is the URL " +"itself. See :ref:`well-known-project-urls` for normalization rules and well-" +"known rules when processing metadata for presentation." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:420 +msgid "Entry points" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:422 +msgid "" +"TOML_ type: table (``[project.scripts]``, ``[project.gui-scripts]``, and " +"``[project.entry-points]``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:424 +msgid ":ref:`Entry points specification `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:426 +msgid "" +"There are three tables related to entry points. The ``[project.scripts]`` " +"table corresponds to the ``console_scripts`` group in the :ref:`entry points " +"specification `. The key of the table is the name of the entry " +"point and the value is the object reference." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:432 +msgid "" +"The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts`` group " +"in the :ref:`entry points specification `. Its format is the " +"same as ``[project.scripts]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:436 +msgid "" +"The ``[project.entry-points]`` table is a collection of tables. Each sub-" +"table's name is an entry point group. The key and value semantics are the " +"same as ``[project.scripts]``. Users MUST NOT create nested sub-tables but " +"instead keep the entry point groups to only one level deep." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:442 +msgid "" +"Build back-ends MUST raise an error if the metadata defines a " +"``[project.entry-points.console_scripts]`` or ``[project.entry-" +"points.gui_scripts]`` table, as they would be ambiguous in the face of " +"``[project.scripts]`` and ``[project.gui-scripts]``, respectively." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:455 +msgid "" +"TOML_ type: Array of :pep:`508` strings (``dependencies``), and a table with " +"values of arrays of :pep:`508` strings (``optional-dependencies``)" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:458 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Requires-" +"Dist ` and :ref:`Provides-Extra `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:462 +msgid "The (optional) dependencies of the project." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:464 +msgid "" +"For ``dependencies``, it is a key whose value is an array of strings. Each " +"string represents a dependency of the project and MUST be formatted as a " +"valid :pep:`508` string. Each string maps directly to a :ref:`Requires-Dist " +"` entry." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:469 +msgid "" +"For ``optional-dependencies``, it is a table where each key specifies an " +"extra and whose value is an array of strings. The strings of the arrays must " +"be valid :pep:`508` strings. The keys MUST be valid values " +"for :ref:`Provides-Extra `. Each value in the " +"array thus becomes a corresponding :ref:`Requires-Dist ` entry for the matching :ref:`Provides-Extra ` metadata." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:485 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-Name " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:488 +msgid "" +"An array of strings specifying the import names that the project exclusively " +"provides when installed. Each string MUST be a valid Python identifier or " +"can be empty. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:493 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``. For " +"instance, a project which is a single package named spam with multiple " +"submodules would only list ``project.import-names = [\"spam\"]``. A project " +"that lists ``spam.bacon.eggs`` would also need to account for ``spam`` and " +"``spam.bacon`` appropriately in ``import-names`` and ``import-namespaces``. " +"Listing all names acts as a check that the intent of the import names is as " +"expected. As well, projects SHOULD list all import names, public or private, " +"using the ``; private`` modifier as appropriate." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:505 +#: ../source/specifications/pyproject-toml.rst:554 +msgid "" +"If a project lists the same name in both ``import-names`` and ``import-" +"namespaces``, then tools MUST raise an error due to ambiguity." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:508 +msgid "" +"Projects MAY set ``import-names`` to an empty array to represent a project " +"with no import names (i.e. there are no Python modules of any kind in the " +"distribution file)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:512 +#: ../source/specifications/pyproject-toml.rst:557 +msgid "" +"Build back-ends MAY support dynamically calculating the value if the user " +"declares the key in ``project.dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:515 +#, fuzzy +#| msgid "Examples::" +msgid "Examples:" +msgstr "例子::" + +#: ../source/specifications/pyproject-toml.rst:536 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Import-" +"Namespace `" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:539 +msgid "" +"An array of strings specifying the import names that the project provides " +"when installed, but not exclusively. Each string MUST be a valid Python " +"identifier. An import name MAY be followed by a semicolon and the term " +"\"private\" (e.g. ``\"; private\"``) with any amount of whitespace " +"surrounding the semicolon. Note that unlike ``import-names``, ``import-" +"namespaces`` CANNOT be an empty array." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:545 +msgid "" +"Projects SHOULD list all the shortest import names that are exclusively " +"provided by the project. If any of the shortest names are dotted names, all " +"intervening names from that name to the top-level name should also be listed " +"appropriately in ``import-names`` and/or ``import-namespaces``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:550 +msgid "" +"This field is used for namespace packages where multiple projects can " +"contribute to the same import namespace. Projects all listing the same " +"import name in ``import-namespaces`` can be installed together without " +"shadowing each other." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:560 +#, fuzzy +#| msgid "Example::" +msgid "Example:" +msgstr "例子::" + +#: ../source/specifications/pyproject-toml.rst:576 +msgid "TOML_ type: array of string" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:577 +msgid "" +"Corresponding :ref:`core metadata ` field: :ref:`Dynamic " +"`" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:580 +msgid "" +"Specifies which keys listed by this PEP were intentionally unspecified so " +"another tool can/will provide such metadata dynamically. This clearly " +"delineates which metadata is purposefully unspecified and expected to stay " +"unspecified compared to being provided via tooling later on." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:586 +msgid "" +"A build back-end MUST honour statically-specified metadata (which means the " +"metadata did not list the key in ``dynamic``)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:588 +msgid "" +"A build back-end MUST raise an error if the metadata specifies ``name`` in " +"``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:590 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:595 +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 "" + +#: ../source/specifications/pyproject-toml.rst:599 +msgid "" +"Build back-ends MUST raise an error if the metadata specifies a key " +"statically as well as being listed in ``dynamic``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:601 +msgid "" +"If the metadata does not list a key in ``dynamic``, then a build back-end " +"CANNOT fill in the requisite metadata on behalf of the user (i.e. " +"``dynamic`` is the only way to allow a tool to fill in metadata and the user " +"must opt into the filling in)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:605 +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)." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:615 +msgid "Arbitrary tool configuration: the ``[tool]`` table" +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:617 +msgid "" +"The ``[tool]`` table is where any tool related to your Python project, not " +"just build tools, can have users specify configuration data as long as they " +"use a sub-table within ``[tool]``, e.g. the `flit `_ tool would store its configuration in ``[tool.flit]``." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:623 +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." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:634 +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`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:638 +msgid "" +"November 2020: The specification of the ``[project]`` table was approved " +"through :pep:`621`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:641 +msgid "" +"December 2024: The ``license`` key was redefined, the ``license-files`` key " +"was added and ``License::`` classifiers were deprecated through :pep:`639`." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:644 +msgid "" +"September 2025: Clarity that the ``license`` key applies to all distribution " +"files generated from the :file:`pyproject.toml` file." +msgstr "" + +#: ../source/specifications/pyproject-toml.rst:647 +msgid "" +"October 2025: The ``import-names`` and ``import-namespaces`` keys were added " +"through :pep:`794`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:7 +msgid "Recording installed projects" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:9 +msgid "" +"This document specifies a common format of recording information about " +"Python :term:`projects ` installed in an environment. A common " +"metadata format allows tools to query, manage or uninstall projects, " +"regardless of how they were installed." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:14 +msgid "" +"Almost all information is optional. This allows tools outside the Python " +"ecosystem, such as Linux package managers, to integrate with Python tooling " +"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 "" + +#: ../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 "" + +#: ../source/specifications/recording-installed-packages.rst:29 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:37 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:47 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:56 +msgid "" +"This ``.dist-info`` directory may contain the following files, described in " +"detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:59 +msgid "``METADATA``: contains project metadata" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:60 +msgid "``RECORD``: records the list of installed files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:61 +msgid "" +"``INSTALLER``: records the name of the tool used to install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:62 +msgid "``entry_points.txt``: see :ref:`entry-points` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:63 +msgid "``direct_url.json``: see :ref:`direct-url` for details" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:65 +msgid "" +"The ``METADATA`` file is mandatory. All other files may be omitted at the " +"installing tool's discretion. Additional installer-specific files may be " +"present." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:69 +msgid "" +"This :file:`.dist-info/` directory may contain the following directories, " +"described in detail below:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:72 +msgid ":file:`licenses/`: contains license files." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:73 +msgid ":file:`sboms/`: contains Software Bill-of-Materials files (SBOMs)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:77 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:82 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:89 +msgid "The METADATA file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:91 +msgid "" +"The ``METADATA`` file contains metadata as described in the :ref:`core-" +"metadata` specification, version 1.1 or greater." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:94 +msgid "" +"The ``METADATA`` file is mandatory. If it cannot be created, or if required " +"core metadata is not available, installers must report an error and fail to " +"install the project." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:100 +msgid "The RECORD file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:102 +msgid "" +"The ``RECORD`` file holds the list of installed files. It is a CSV file " +"containing one record (line) per installed file." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:105 +msgid "" +"The CSV dialect must be readable with the default ``reader`` of Python's " +"``csv`` module:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:108 +msgid "field delimiter: ``,`` (comma)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:109 +msgid "quoting char: ``\"`` (straight double quote)," +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:110 +msgid "line terminator: either ``\\r\\n`` or ``\\n``." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:112 +msgid "" +"Each record is composed of three elements: the file's **path**, the **hash** " +"of the contents, and its **size**." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:115 +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 ``\\``)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:120 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:125 +msgid "" +"The *size* is either the empty string, or file's size in bytes, as a base 10 " +"integer." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:128 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:134 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:141 +msgid "" +"To completely uninstall a package, a tool needs to remove all files listed " +"in ``RECORD``, all ``.pyc`` files (of all optimization levels) corresponding " +"to removed ``.py`` files, and any directories emptied by the uninstallation." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:146 +msgid "Here is an example snippet of a possible ``RECORD`` file::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:165 +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.)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:172 +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/recording-installed-packages.rst:181 +msgid "The INSTALLER file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:183 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:189 +msgid "The file can be terminated by zero or more ASCII whitespace characters." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:191 +msgid "Here are examples of two possible ``INSTALLER`` files::" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:199 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:206 +msgid "The entry_points.txt file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:208 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:213 +msgid "Its detailed specification is at :ref:`entry-points`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:217 +msgid "The direct_url.json file" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:219 +msgid "" +"This file MUST be created by installers when installing a distribution from " +"a requirement specifying a direct URL reference (including a VCS URL)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:225 +msgid "Its detailed specification is at :ref:`direct-url`." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:229 +msgid "The :file:`licenses/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:231 +msgid "" +"If the metadata version is 2.4 or greater and one or more ``License-File`` " +"fields is specified, the :file:`.dist-info/` directory MUST contain " +"a :file:`licenses/` subdirectory which MUST contain the files listed in the " +"``License-File`` fields in the :file:`METADATA` file at their respective " +"paths relative to the :file:`licenses/` directory. Any files in this " +"directory MUST be copied from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:240 +msgid "The :file:`sboms/` subdirectory" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:242 +msgid "" +"All files contained within the :file:`.dist-info/sboms/` directory MUST be " +"Software Bill-of-Materials (SBOM) files that describe software contained " +"within the installed package. Any files in this directory MUST be copied " +"from wheels by the install tools." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:249 +msgid "Intentionally preventing changes to installed packages" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:251 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:257 +msgid "To achieve this, affected tools should take the following steps:" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:259 +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)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:263 +msgid "" +"Write an ``INSTALLER`` file indicating the name of the tool that should be " +"used to manage the package (this allows ``RECORD``-aware tools to provide " +"better error notices when asked to modify affected packages)" +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:267 +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)." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:272 +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 "" + +#: ../source/specifications/recording-installed-packages.rst:280 +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*." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:283 +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." +msgstr "" + +#: ../source/specifications/recording-installed-packages.rst:286 +msgid "" +"September 2020: Various amendments and clarifications were approved " +"through :pep:`627`." +msgstr "" + +#: ../source/specifications/schemas/index.rst:4 +msgid "PyPA schemas" +msgstr "" + +#: ../source/specifications/schemas/index.rst:6 +msgid "`direct_url.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:7 +msgid "`build-details.json `_" +msgstr "" + +#: ../source/specifications/schemas/index.rst:8 +msgid "`pylock.toml `_" +msgstr "" + +#: ../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 +msgid "Package Installation Metadata" +msgstr "" + +#: ../source/specifications/section-package-indices.rst:3 +msgid "Package Index Interfaces" +msgstr "" + +#: ../source/specifications/section-python-description-formats.rst:3 +#, fuzzy +#| msgid "Python version" +msgid "Python Description Formats" +msgstr "Python 版本" + +#: ../source/specifications/section-reproducible-environments.rst:3 +msgid "Reproducible Environments" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:6 +msgid "Simple repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:8 +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:`2119`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:13 +msgid "" +"The interface for querying available package versions and retrieving " +"packages from an index server comes in two forms: :ref:`HTML ` and :ref:`JSON `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:21 +msgid "Base API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:23 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:28 +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/" +"``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:33 +#, fuzzy +msgid "Normalized Names" +msgstr "翻譯" + +#: ../source/specifications/simple-repository-api.rst:35 +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::" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:50 +msgid "Versioning PyPI's Simple API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:52 +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 " +"`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:60 +msgid "This would end up looking like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:66 +msgid "When interpreting the repository version:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:68 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:71 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:75 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:81 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:89 +msgid "API Version History" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:91 +msgid "" +"This section contains only an abbreviated history of changes, as marked by " +"the API version number. For a full history of changes including changes made " +"before API versioning, see :ref:`History `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:95 +msgid "API version 1.0: Initial version of the API, declared with :pep:`629`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:96 +msgid "" +"API version 1.1: Added ``versions``, ``files[].size``, and ``files[].upload-" +"time`` metadata to the JSON serialization, declared with :pep:`700`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:98 +msgid "" +"API version 1.2: Added repository \"tracks\" metadata, declared " +"with :pep:`708`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:99 +msgid "API version 1.3: Added provenance metadata, declared with :pep:`740`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:100 +msgid "API version 1.4: Added status markers, declared with :pep:`792`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:103 +#, fuzzy +#| msgid "Contents" +msgid "Clients" +msgstr "内容" + +#: ../source/specifications/simple-repository-api.rst:105 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:109 +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:112 +msgid "" +"When encountering a minor version greater than expected, clients **SHOULD** " +"warn users with an appropriate message." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:115 +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:121 +#, fuzzy +msgid "HTML Serialization" +msgstr "翻譯" + +#: ../source/specifications/simple-repository-api.rst:125 +msgid "" +"The following constraints apply to all HTML serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:128 +msgid "All HTML responses **MUST** be a valid HTML5 document." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:129 +msgid "" +"HTML responses **MAY** contain one or more ``meta`` tags in the ```` " +"section. The semantics of these tags are defined below." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:133 +#: ../source/specifications/simple-repository-api.rst:428 +#, fuzzy +#| msgid "Project name" +msgid "Project List" +msgstr "專案名稱" + +#: ../source/specifications/simple-repository-api.rst:135 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:139 +msgid "" +"The text of each 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:156 +#: ../source/specifications/simple-repository-api.rst:473 +#, fuzzy +#| msgid "Project name" +msgid "Project Detail" +msgstr "專案名稱" + +#: ../source/specifications/simple-repository-api.rst:158 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:164 +msgid "" +"For example, a project named \"HolyGrail\" would have a URL like ``/" +"holygrail/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:167 +msgid "" +"The project detail 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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:172 +msgid "" +"Each file 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:177 +msgid "" +"In addition to the above, the following constraints are placed on the API:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:179 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:183 +msgid "" +"URLs may be either absolute or relative as long as they point to the correct " +"location." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:186 +msgid "" +"There are no constraints on where the files must be hosted relative to the " +"repository." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:189 +msgid "" +"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:192 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:197 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:202 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:208 +msgid "" +"A repository **MAY** include a ``data-core-metadata`` attribute on a file " +"link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:211 +msgid "" +"The repository **SHOULD** provide the hash of the Core Metadata file as the " +"``data-core-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:217 +msgid "" +"A repository **MAY** include a ``data-dist-info-metadata`` attribute on a " +"file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:220 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``data-core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:225 +msgid "" +"``data-dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``data-core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:228 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:232 +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:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:242 +msgid "" +"In the attribute value, < and > have to be HTML encoded as ``<`` and " +"``>``, respectively." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:245 +msgid "" +"A repository **MAY** include a ``data-yanked`` attribute on a file link." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:247 +msgid "" +"The ``data-yanked`` attribute 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:253 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:258 +#: ../source/specifications/simple-repository-api.rst:603 +msgid "" +"The semantics of how tools should handle yanked files is described " +"in :ref:`file-yanking`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:261 +msgid "" +"A repository **MAY** include a ``data-provenance`` attribute on a file link. " +"The value of this attribute **MUST** be a fully qualified URL, signaling " +"that the file's provenance can be found at that URL. This URL **MUST** " +"represent a `secure origin `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:268 +msgid "The ``data-provenance`` attribute was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:272 +msgid "" +"The format of the linked provenance is defined in :ref:`index-hosted-" +"attestations`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:274 +msgid "" +"A repository **MAY** include ``pypi:project-status`` and ``pypi:project-" +"status-reason`` meta tags on the response itself." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:277 +msgid "" +"The value of ``pypi:project-status`` **MUST** be a valid project status " +"marker, while the value of ``pypi:project-status-reason`` **MUST** be an " +"arbitrary string if present." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:283 +#: ../source/specifications/simple-repository-api.rst:489 +msgid "" +"The set of valid project status markers and their semantics is described " +"in :ref:`project-status-markers`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:288 +msgid "" +"The ``pypi:project-status`` and ``pypi:project-status-reason`` meta tags " +"were added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:294 +msgid "Serve Distribution Metadata in the Simple Repository API" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:296 +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:302 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:311 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:319 +msgid "Backwards Compatibility" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:321 +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/simple-repository-api.rst:325 +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:334 +msgid "JSON-based Simple API for Python Package Indexes" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:336 +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 `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:341 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:351 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:358 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:364 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:368 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:372 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:376 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:382 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:390 +#, fuzzy +msgid "JSON Serialization" +msgstr "翻譯" + +#: ../source/specifications/simple-repository-api.rst:392 +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:396 +msgid "" +"The following constraints apply to all JSON serialized responses described " +"in this spec:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:399 +msgid "" +"All JSON responses will *always* be a JSON object rather than an array or " +"other type." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:402 +msgid "" +"While JSON doesn't natively support a 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:407 +msgid "" +"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:410 +msgid "" +"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:413 +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:419 +msgid "" +"All requirements of :ref:`the base HTML API specification ` that are not HTML specific still apply." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:422 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:430 +msgid "" +"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:433 +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:434 +#: ../source/specifications/simple-repository-api.rst:508 +msgid "" +"``meta``: The general response metadata as `described earlier `__." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:436 +#: ../source/specifications/simple-repository-api.rst:634 +msgid "As an example:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:453 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:463 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:475 +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/``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:480 +msgid "" +"This URL must respond with a JSON encoded dictionary that has five keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:482 +msgid "``name``: The normalized name of the project." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:483 +msgid "``project-status``: An optional dictionary, containing the following:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:485 +msgid "``status``: If present, this **MUST** be a valid project status marker." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:494 +msgid "The ``status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:496 +msgid "" +"``reason``: If present, this **MUST** be an arbitrary string description of " +"the project status." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:501 +msgid "The ``reason`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:505 +msgid "The ``project-status`` key was added with API version 1.4." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:507 +msgid "" +"``files``: A list of dictionaries, each one representing an individual file." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:509 +msgid "" +"``versions``: A list of version strings specifying all of the project " +"versions uploaded for this project. The value of ``versions`` is logically a " +"set, and as such may not contain duplicates, and the order of the versions " +"is not significant." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:516 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:523 +msgid "" +"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 normalized VSS versions where possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:531 +msgid "The ``versions`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:533 +msgid "Each individual file dictionary has the following keys:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:535 +msgid "``filename``: The filename that is being represented." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:536 +msgid "``url``: The URL that the file can be fetched from." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:537 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:542 +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:546 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:551 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:557 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:560 +msgid "" +"``core-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:568 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:572 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:576 +msgid "" +"It is recommended that servers make the hashes of the metadata file " +"available if possible." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:579 +msgid "" +"``dist-info-metadata``: An **optional**, deprecated alias for ``core-" +"metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:581 +msgid "" +"Index clients **MAY** consume this key if present, as a legacy fallback for " +"``core-metadata``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:586 +msgid "" +"``dist-info-metadata`` was standardized with :pep:`658` and renamed to " +"``core-metadata`` with :pep:`714`." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:589 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:595 +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\"." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:606 +msgid "" +"``size``: A **mandatory** key. It **MUST** contain an integer which is the " +"file size in bytes." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:610 +msgid "The ``size`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:612 +msgid "" +"``upload-time``: An **optional** key that, if present, **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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:616 +msgid "" +"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/simple-repository-api.rst:623 +msgid "The ``upload-time`` key was added with API version 1.1." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:625 +msgid "" +"``provenance``: An **optional** key which, if present **MUST** be either a " +"JSON string or ``null``. If not ``null``, it **MUST** be a URL to the file's " +"associated provenance, with the same rules as ``data-provenance`` in " +"the :ref:`base HTML API specification `." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:632 +msgid "The ``provenance`` field was added with API version 1.3." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:670 +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:679 +#, fuzzy +#| msgid "Contents" +msgid "Content-Types" +msgstr "内容" + +#: ../source/specifications/simple-repository-api.rst:681 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:685 +msgid "The structure of this content type will be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:691 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:696 +msgid "Which means that for the existing 1.0 API, the content types would be:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:698 +msgid "**JSON:** ``application/vnd.pypi.simple.v1+json``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:699 +msgid "**HTML:** ``application/vnd.pypi.simple.v1+html``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:701 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:706 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:713 +#, fuzzy +msgid "Version + Format Selection" +msgstr "翻譯" + +#: ../source/specifications/simple-repository-api.rst:715 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:720 +msgid "" +"To enable this, this spec standardizes on the use of HTTP's `Server-Driven " +"Content Negotiation `_." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:723 +msgid "" +"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:726 +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:728 +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: */*``)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:731 +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:735 +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:737 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:740 +msgid "" +"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:742 +msgid "" +"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:745 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:750 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:757 +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. an ``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:764 +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:768 +msgid "``$type/$subtype``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:769 +msgid "``$type/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:770 +msgid "``*/*``" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:772 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:776 +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:783 +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``." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:789 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:793 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:800 +msgid "An example of how a client can operate would look like:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:851 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:857 +msgid "Alternative Negotiation Mechanisms" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:859 +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:867 +msgid "URL Parameter" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:869 +msgid "" +"Servers that implement the Simple API may choose to support a URL parameter " +"named ``format`` to allow the clients to request a specific version of the " +"URL." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:872 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:876 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:881 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:884 +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)." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:893 +msgid "Endpoint Configuration" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:895 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:899 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:903 +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/simple-repository-api.rst:910 +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/simple-repository-api.rst:918 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:922 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:927 +msgid "It is recommended that servers:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:929 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:933 +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/simple-repository-api.rst:938 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:941 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:947 +msgid "It is recommended that clients:" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:949 +msgid "" +"Support all 3 content types described in this spec, using server-driven " +"content negotiation, for as long as they reasonably can." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:952 +msgid "" +"When constructing an ``Accept`` header, include all of the content types " +"that you support." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:955 +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/simple-repository-api.rst:961 +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." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:965 +msgid "" +"Explicitly select what versions they are looking for, rather than using the " +"``latest`` meta version during normal operation." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:968 +msgid "" +"Check the ``Content-Type`` of the response and ensure it matches something " +"that you were expecting." +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:976 +msgid "September 2015: initial form of the HTML format, in :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:977 +msgid "July 2016: Requires-Python metadata, in an update to :pep:`503`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:978 +msgid "May 2019: \"yank\" support, in :pep:`592`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:979 +msgid "" +"July 2020: API versioning convention and metadata, and declaring the HTML " +"format as API v1, in :pep:`629`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:981 +msgid "" +"May 2021: providing package metadata independently from a package, " +"in :pep:`658`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:983 +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`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:985 +msgid "" +"October 2022: project versions and file size and upload-time in the JSON " +"format, in :pep:`700`" +msgstr "" + +#: ../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/simple-repository-api.rst:989 +msgid "" +"November 2024: provenance metadata in the HTML and JSON formats, " +"in :pep:`740`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:990 +msgid "" +"July 2025: project status markers in the HTML and JSON formats, in :pep:`792`" +msgstr "" + +#: ../source/specifications/simple-repository-api.rst:991 +msgid "" +"July 2025: layout changes (dedicated page for file yanking, introduce " +"concepts before API details)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:6 +msgid "Source distribution format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:8 +msgid "" +"The current standard 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 "" + +#: ../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 "" + +#: ../source/specifications/source-distribution-format.rst:21 +msgid "Source distributions are also known as *sdists* for short." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:26 +msgid "Source trees" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:28 +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 used 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 "" + +#: ../source/specifications/source-distribution-format.rst:38 +msgid "Source distribution file name" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:40 +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`)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:46 +msgid "" +"The name and version components of the filename MUST match the values stored " +"in the metadata contained in the file." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:49 +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 `." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:53 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:59 +msgid "Source distribution file format" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:61 +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 :file:`PKG-INFO` file containing metadata in the format " +"described in the :ref:`core-metadata` specification. The metadata MUST " +"conform to at least version 2.2 of the metadata specification." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:69 +msgid "" +"If the metadata version is 2.4 or greater, the source distribution MUST " +"contain any license files specified by the ``License-File`` field in " +"the :file:`PKG-INFO` at their respective paths relative to the root " +"directory of the sdist (containing the :file:`pyproject.toml` and " +"the :file:`PKG-INFO` metadata)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:74 +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." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:77 +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'." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:85 +msgid "Source distribution archive features" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:87 +msgid "" +"Because extracting tar files as-is is dangerous, and the results are " +"platform-specific, archive features of source distributions are limited." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:91 +msgid "Unpacking with the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:93 +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 "" + +#: ../source/specifications/source-distribution-format.rst:97 +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 "" + +#: ../source/specifications/source-distribution-format.rst:105 +msgid "Unpacking without the data filter" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:107 +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.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:113 +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:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:117 +msgid "Files that would be placed outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:118 +msgid "Links (symbolic or hard) pointing outside the destination directory." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:119 +msgid "Device files (including pipes)." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:121 +msgid "" +"The following are also invalid. Tools MAY treat them as above, but are NOT " +"REQUIRED to do so:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:124 +msgid "Files with a ``..`` component in the filename or link target." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:125 +msgid "Links pointing to a file that is not part of the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:127 +msgid "" +"Tools MAY unpack links (symbolic or hard) as regular files, using content " +"from the archive." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:130 +msgid "When extracting *sdist* archives:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:132 +msgid "" +"Leading slashes in file names MUST be dropped. (This is nowadays standard " +"behaviour for ``tar`` unpacking.)" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:134 +msgid "For each ``mode`` (Unix permission) bit, tools MUST either:" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:136 +msgid "use the platform's default for a new file/directory (respectively)," +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:137 +msgid "set the bit according to the archive, or" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:138 +msgid "" +"use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or " +"``rwxr-xr-x`` (``0o755``) for executable files and directories." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:141 +msgid "High ``mode`` bits (setuid, setgid, sticky) MUST be cleared." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:142 +msgid "It is RECOMMENDED to preserve the user *executable* bit." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:146 +msgid "Further hints" +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:148 +msgid "" +"Tool authors are encouraged to consider how *hints for further verification* " +"in ``tarfile`` documentation apply to their tool." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:155 +msgid "" +"November 2020: The original version of this specification was approved " +"through :pep:`643`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:157 +msgid "July 2021: Defined what a source tree is." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:158 +msgid "" +"September 2022: The filename of a source distribution was standardized " +"through :pep:`625`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:160 +msgid "" +"August 2023: Source distribution archive features were standardized " +"through :pep:`721`." +msgstr "" + +#: ../source/specifications/source-distribution-format.rst:162 +msgid "" +"December 2024: License files inclusion into source distribution was " +"standardized through :pep:`639`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:7 +#: ../source/specifications/version-specifiers.rst:800 +msgid "Version specifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:10 +msgid "" +"This specification describes a scheme for identifying versions of Python " +"software distributions, and declaring dependencies on particular versions." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:15 +msgid "Definitions" +msgstr "定義" + +#: ../source/specifications/version-specifiers.rst:17 +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`." +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:26 +msgid "" +"\"Index servers\" are active distribution registries which publish version " +"and dependency metadata and place constraints on the permitted metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:29 +msgid "" +"\"Publication tools\" are automated tools intended to run on development " +"systems and upload source and binary distribution archives to index servers." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:32 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:37 +msgid "" +"\"Automated tools\" is a collective term covering build tools, index " +"servers, publication tools, integration tools and any other software that " +"produces or consumes distribution version and dependency metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:43 +#, fuzzy +msgid "Version scheme" +msgstr "翻譯" + +#: ../source/specifications/version-specifiers.rst:45 +msgid "" +"Distributions are identified by a public version identifier which supports " +"all defined version comparison operations" +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:57 +msgid "Public version identifiers" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:59 +msgid "" +"The canonical public version identifiers MUST comply with the following " +"scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:64 +msgid "" +"Public version identifiers MUST NOT include leading or trailing whitespace." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:66 +msgid "Public version identifiers MUST be unique within a given distribution." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:68 +msgid "" +"Installation tools SHOULD ignore any public versions which do not comply " +"with this scheme but MUST also include the normalizations specified below. " +"Installation tools MAY warn the user when non-compliant or ambiguous " +"versions are detected." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:73 +msgid "" +"See also :ref:`version-specifiers-regex` which provides a regular expression " +"to check strict conformance with the canonical format, as well as a more " +"permissive regular expression accepting inputs that may require subsequent " +"normalization." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:78 +msgid "Public version identifiers are separated into up to five segments:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:80 +msgid "Epoch segment: ``N!``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:81 +msgid "Release segment: ``N(.N)*``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:82 +msgid "Pre-release segment: ``{a|b|rc}N``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:83 +msgid "Post-release segment: ``.postN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:84 +msgid "Development release segment: ``.devN``" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:86 +msgid "" +"Any given release will be a \"final release\", \"pre-release\", \"post-" +"release\" or \"developmental release\" as defined in the following sections." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:89 +msgid "" +"All numeric components MUST be non-negative integers represented as " +"sequences of ASCII digits." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:92 +msgid "" +"All numeric components MUST be interpreted and ordered according to their " +"numeric value, not as text strings." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:95 +msgid "" +"All numeric components MAY be zero. Except as described below for the " +"release segment, a numeric component of zero has no special significance " +"aside from always being the lowest possible value in the version ordering." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:101 +msgid "" +"Some hard to read version identifiers are permitted by this scheme in order " +"to better accommodate the wide range of versioning practices across existing " +"public and private Python projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:105 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:116 +msgid "Local version identifiers MUST comply with the following scheme::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:120 +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." +msgstr "" + +#: ../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:132 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:138 +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:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:143 +msgid "ASCII letters (``[a-zA-Z]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:144 +msgid "ASCII digits (``[0-9]``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:145 +msgid "periods (``.``)" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:147 +msgid "Local version labels MUST start and end with an ASCII letter or digit." +msgstr "" + +#: ../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:160 +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." +msgstr "" + +#: ../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:175 +msgid "" +"Source distributions using a local version identifier SHOULD provide the " +"``python.integrator`` extension metadata (as defined in :pep:`459`)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:180 +msgid "Final releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:182 +msgid "" +"A version identifier that consists solely of a release segment and " +"optionally an epoch identifier is termed a \"final release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:185 +msgid "" +"The release segment consists of one or more non-negative integer values, " +"separated by dots::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:190 +msgid "" +"Final releases within a project MUST be numbered in a consistently " +"increasing fashion, otherwise automated tools will not be able to upgrade " +"them correctly." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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: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\")." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:203 +msgid "For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:218 +msgid "" +"A release series is any set of final release numbers that start with a " +"common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all " +"part of the ``3.3`` release series." +msgstr "" + +#: ../source/specifications/version-specifiers.rst: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." +msgstr "" + +#: ../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:243 +msgid "Pre-releases" +msgstr "預發行" + +#: ../source/specifications/version-specifiers.rst:245 +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:248 +msgid "" +"If used as part of a project's development cycle, these pre-releases are " +"indicated by including a pre-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:256 +msgid "" +"A version identifier that consists solely of a release segment and a pre-" +"release segment is termed a \"pre-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:259 +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 "" + +#: ../source/specifications/version-specifiers.rst:264 +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:267 +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:270 +msgid "" +"Build tools, publication tools and index servers SHOULD disallow the " +"creation of both ``rc`` and ``c`` releases for a common release segment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:275 +msgid "Post-releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:277 +msgid "" +"Some projects use post-releases to address minor errors in a final release " +"that do not affect the distributed software (for example, correcting an " +"error in the release notes)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:281 +msgid "" +"If used as part of a project's development cycle, these post-releases are " +"indicated by including a post-release segment in the version identifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:286 +msgid "" +"A version identifier that includes a post-release segment without a " +"developmental release segment is termed a \"post-release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:289 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:296 +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:301 +msgid "Post-releases are also permitted for pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:309 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:316 +msgid "Developmental releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:318 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:323 +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:329 +msgid "" +"A version identifier that includes a developmental release segment is termed " +"a \"developmental release\"." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:332 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:338 +msgid "" +"Developmental releases are also permitted for pre-releases and post-" +"releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:346 +msgid "" +"Do note that development releases are considered a type of pre-release when " +"handling them." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:351 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:358 +msgid "" +"Developmental releases of post-releases are also strongly discouraged, but " +"they may be appropriate for projects which use the post-release notation for " +"full maintenance releases which may include code changes." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:364 +#, fuzzy +msgid "Version epochs" +msgstr "翻譯" + +#: ../source/specifications/version-specifiers.rst:366 +msgid "" +"If included in a version identifier, the epoch appears before all other " +"components, separated from the release segment by an exclamation mark::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:371 +msgid "If no explicit epoch is given, the implicit epoch is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:373 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:387 +msgid "" +"However, by specifying an explicit epoch, the sort order can be changed " +"appropriately, as all versions from a later epoch are sorted after versions " +"from an earlier epoch::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:399 +msgid "" +"Use of nonzero epochs is discouraged. They are often not supported or " +"discouraged by downstream packaging where Python packages may need to be " +"consumed, and due to their scarce use they may also not be well supported by " +"Python packaging tools." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:404 +msgid "" +"When version scheme needs to be changed, it is preferable to continue with " +"monotonically increasing numbers in epoch zero. For example, the version " +"2026.x could be unambiguously followed by 3000.x." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:408 +msgid "" +"See `Discouraging use of epoch segments in versions `__ for the relevant discussion." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:416 +msgid "Normalization" +msgstr "正規化" + +#: ../source/specifications/version-specifiers.rst:418 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:425 +msgid "Case sensitivity" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:427 +msgid "" +"All ascii letters should be interpreted case insensitively within a version " +"and the normal form is lowercase. This allows versions such as ``1.1RC1`` " +"which would be normalized to ``1.1rc1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:433 +#, fuzzy +msgid "Integer Normalization" +msgstr "翻譯" + +#: ../source/specifications/version-specifiers.rst:435 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:443 +msgid "Pre-release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:445 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:454 +msgid "Pre-release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:456 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:465 +msgid "Implicit pre-release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:467 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:473 +msgid "Post release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:475 +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:484 +msgid "Post release spelling" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:486 +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:493 +msgid "Implicit post release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:495 +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:501 +msgid "Implicit post releases" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:503 +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:512 +msgid "Development release separators" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:514 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:521 +msgid "Implicit development release number" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:523 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:530 +msgid "Local version segments" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:532 +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:539 +msgid "Preceding v character" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:541 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:548 +msgid "Leading and Trailing Whitespace" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:550 +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``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:557 +msgid "Examples of compliant version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:559 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:566 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:571 +msgid "Simple \"major.minor\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:580 +msgid "Simple \"major.minor.micro\" versioning::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:588 +msgid "" +"\"major.minor\" versioning with alpha, beta and candidate pre-releases::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:600 +msgid "" +"\"major.minor\" versioning with developmental releases, release candidates " +"and post-releases for minor corrections::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:615 +msgid "" +"Date based releases, using an incrementing serial within each year, skipping " +"zero::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:629 +msgid "Summary of permitted suffixes and relative ordering" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:633 +msgid "" +"This section is intended primarily for authors of tools that automatically " +"process distribution metadata, rather than developers of Python " +"distributions deciding on a versioning scheme." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:637 +msgid "" +"The epoch segment of version identifiers MUST be sorted according to the " +"numeric value of the given epoch. If no epoch segment is present, the " +"implicit numeric value is ``0``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:641 +msgid "" +"The release segment of version identifiers MUST be sorted in the same order " +"as Python's tuple sorting when the normalized release segment is parsed as " +"follows::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:647 +msgid "" +"All release segments involved in the comparison MUST be converted to a " +"consistent length by padding shorter segments with zeros as needed." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:650 +msgid "" +"Within a numeric release (``1.0``, ``2.7.3``), the following suffixes are " +"permitted and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:655 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:660 +msgid "" +"Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate " +"(``1.0rc1``, ``1.0c1``), the following suffixes are permitted and MUST be " +"ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:666 +msgid "" +"Within a post-release (``1.0.post1``), the following suffixes are permitted " +"and MUST be ordered as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:671 +msgid "" +"Note that ``devN`` and ``postN`` MUST always be preceded by a dot, even when " +"used immediately following a numeric version (e.g. ``1.0.dev456``, " +"``1.0.post1``)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:675 +msgid "" +"Within a pre-release, post-release or development release segment with a " +"shared prefix, ordering MUST be by the value of the numeric component." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:678 +msgid "The following example covers many of the possible combinations::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:703 +msgid "Version ordering across different metadata versions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:705 +msgid "" +"Metadata v1.0 (:pep:`241`) and metadata v1.1 (:pep:`314`) do not specify a " +"standard version identification or ordering scheme. However metadata v1.2 " +"(:pep:`345`) does specify a scheme which is defined in :pep:`386`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:709 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:717 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:723 +msgid "" +"Distribution users may wish to explicitly remove non-compliant versions from " +"any private package indexes they control." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:728 +msgid "Compatibility with other version schemes" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:730 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:735 +msgid "" +"This allows automated distribution tools to provide consistently correct " +"ordering of published releases, while still allowing developers to use the " +"internal versioning scheme they prefer for their projects." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:743 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:750 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:755 +msgid "" +"Semantic versions containing a hyphen (pre-releases - clause 10) or a plus " +"sign (builds - clause 11) are *not* compatible with this specification and " +"are not permitted in the public version field." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:759 +msgid "" +"One possible mechanism to translate such semantic versioning based source " +"labels to compatible public versions is to use the ``.devN`` suffix to " +"specify the appropriate version order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:763 +msgid "" +"Specific build information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:769 +msgid "DVCS based version labels" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:771 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:776 +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:780 +msgid "" +"Identifying hash information may also be included in local version labels." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:784 +msgid "Olson database versioning" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:786 +msgid "" +"The ``pytz`` project inherits its versioning scheme from the corresponding " +"Olson timezone database versioning scheme: the year followed by a lowercase " +"character indicating the version of the database within that year." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:790 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:795 +msgid "" +"As with other translated version identifiers, the corresponding Olson " +"database version could be recorded in the project metadata." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:802 +msgid "" +"A version specifier consists of a series of version clauses, separated by " +"commas. For example::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:807 +msgid "The comparison operator determines the kind of version clause:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:809 +msgid "``~=``: `Compatible release`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:810 +msgid "``==``: `Version matching`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:811 +msgid "``!=``: `Version exclusion`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:812 +msgid "``<=``, ``>=``: `Inclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:813 +msgid "``<``, ``>``: `Exclusive ordered comparison`_ clause" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:814 +msgid "``===``: `Arbitrary equality`_ clause." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:816 +msgid "" +"The comma (\",\") is equivalent to a logical **and** operator: a candidate " +"version must match all given version clauses in order to match the specifier " +"as a whole." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:820 +msgid "" +"Whitespace between a conditional operator and the following version " +"identifier is optional, as is the whitespace around the commas." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:823 +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:829 +msgid "" +"Except where specifically noted below, local version identifiers MUST NOT be " +"permitted in version specifiers, and local version labels MUST be ignored " +"entirely when checking if candidate versions match a given version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:838 +msgid "Compatible release" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:840 +msgid "" +"A compatible release clause consists of the compatible release operator " +"``~=`` and a version identifier. It matches any candidate version that is " +"expected to be compatible with the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:844 +msgid "" +"The specified version identifier must be in the standard format described in " +"`Version scheme`_. Local version identifiers are NOT permitted in this " +"version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:848 +msgid "" +"For a given release identifier ``V.N``, the compatible release clause is " +"approximately equivalent to the pair of comparison clauses::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:853 +msgid "" +"This operator MUST NOT be used with a single segment version number such as " +"``~=1``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:856 +msgid "For example, the following groups of version clauses are equivalent::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:864 +msgid "" +"If a pre-release, post-release or developmental release is named in a " +"compatible release clause as ``V.N.suffix``, then the suffix is ignored when " +"determining the required prefix match::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:874 +msgid "" +"The padding rules for release segment comparisons means that the assumed " +"degree of forward compatibility in a compatible release clause can be " +"controlled by appending additional zeros to the version specifier::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:886 +msgid "Version matching" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:888 +msgid "" +"A version matching clause includes the version matching operator ``==`` and " +"a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:891 +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:895 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:901 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:906 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:913 +#: ../source/specifications/version-specifiers.rst:974 +msgid "" +"For example, given the version ``1.1.post1``, the following clauses would " +"match or not as shown::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:920 +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:928 +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::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:940 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:946 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:953 +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:957 +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:965 +#, fuzzy +msgid "Version exclusion" +msgstr "翻譯" + +#: ../source/specifications/version-specifiers.rst:967 +msgid "" +"A version exclusion clause includes the version exclusion operator ``!=`` " +"and a version identifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:970 +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:983 +msgid "Inclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:985 +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:991 +msgid "The inclusive ordered comparison operators are ``<=`` and ``>=``." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:993 +#: ../source/specifications/version-specifiers.rst:1023 +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:996 +#: ../source/specifications/version-specifiers.rst:1026 +msgid "Local version identifiers are NOT permitted in this version specifier." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1000 +msgid "Exclusive ordered comparison" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1002 +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:1008 +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:1015 +msgid "" +"The exclusive ordered comparison ``>V`` **MUST NOT** match a local version " +"of the specified version." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1018 +msgid "" +"The exclusive ordered comparison ``=`` entry as part " +"of the URL fragment." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1148 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1154 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1161 +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)." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1169 +msgid "Remote URL examples::" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1177 +msgid "File URLs" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1179 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1184 +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/specifications/version-specifiers.rst:1189 +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/specifications/version-specifiers.rst:1200 +msgid "Summary of differences from pkg_resources.parse_version" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1202 +msgid "" +"Note: this comparison is to ``pkg_resources.parse_version`` as it existed at " +"the time :pep:`440` was written. After the PEP was accepted, setuptools 6.0 " +"and later versions adopted the behaviour described here." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1206 +msgid "" +"Local versions sort differently, this specification requires that they sort " +"as greater than the same version without a local version, whereas " +"``pkg_resources.parse_version`` considers it a pre-release marker." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1210 +msgid "" +"This specification purposely restricts the syntax which constitutes a valid " +"version while ``pkg_resources.parse_version`` attempts to provide some " +"meaning from *any* arbitrary string." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1214 +msgid "" +"``pkg_resources.parse_version`` allows arbitrarily deeply nested version " +"signifiers like ``1.0.dev1.post1.dev5``. This specification however allows " +"only a single use of each type and they must exist in a certain order." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1223 +msgid "Appendix: Parsing version strings with regular expressions" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1225 +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." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1231 +msgid "" +"To test whether a version identifier is in the canonical format, you can use " +"the following function:" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1240 +msgid "" +"To extract the components of a version identifier, use the following regular " +"expression (as defined by the `packaging `_ project):" +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1287 +msgid "August 2014: This specification was approved through :pep:`440`." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1288 +msgid "" +"May 2025: Clarify that development releases are a form of pre-release when " +"they are handled." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1290 +msgid "Nov 2025: Make arbitrary equality case insensitivity explicit." +msgstr "" + +#: ../source/specifications/version-specifiers.rst:1291 +msgid "Jan 2026: The use of epochs was discouraged." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:6 +msgid "Python Virtual Environments" +msgstr "" + +#: ../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 "" + +#: ../source/specifications/virtual-environments.rst:18 +msgid "Runtime detection of virtual environments" +msgstr "" + +#: ../source/specifications/virtual-environments.rst:20 +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)." +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)." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:33 +msgid "Declaring installation environments as Python virtual environments" +msgstr "" + +#: ../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." +msgstr "" + +#: ../source/specifications/virtual-environments.rst:40 +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." +msgstr "" + +#: ../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/specifications/virtual-environments.rst:56 +msgid "May 2012: This specification was approved through :pep:`405`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:5 +#, fuzzy +#| msgid "Project name" +msgid "Well-known Project URLs in Metadata" +msgstr "專案名稱" + +#: ../source/specifications/well-known-project-urls.rst:9 +msgid "" +"This document is primarily of interest to metadata *consumers*, who should " +"use the normalization rules and well-known list below to make their " +"presentation of project URLs consistent across the Python ecosystem." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:14 +msgid "" +"Metadata *producers* (such as build tools and individual package " +"maintainers) may continue to use any labels they please, within the overall " +"``Project-URL`` length restrictions. However, when possible, users are " +"*encouraged* to pick meaningful labels that normalize to well-known labels." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:22 +msgid "" +"See :ref:`Writing your pyproject.toml - urls ` " +"for user-oriented guidance on choosing project URL labels in your package's " +"metadata." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:26 +msgid "This specification was originally defined in :pep:`753`." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:28 +msgid "" +":pep:`753` deprecates the :ref:`core-metadata-home-page` and :ref:`core-" +"metadata-download-url` metadata fields in favor of :ref:`core-metadata-" +"project-url`, and defines a normalization and lookup procedure for " +"determining whether a ``Project-URL`` is \"well-known,\" i.e. has the " +"semantics assigned to ``Home-page``, ``Download-URL``, or other common " +"project URLs." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:35 +msgid "" +"This allows indices (such as the Python Package Index) and other downstream " +"metadata consumers to present project URLs in a consistent manner." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:42 +#, fuzzy +msgid "Label normalization" +msgstr "翻譯" + +#: ../source/specifications/well-known-project-urls.rst:46 +msgid "" +"Label normalization is performed by metadata *consumers*, not metadata " +"producers." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:49 +msgid "" +"To determine whether a ``Project-URL`` label is \"well-known,\" metadata " +"consumers should normalize the label before comparing it to the :ref:`list " +"of well-known labels `." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:53 +msgid "" +"The normalization procedure for ``Project-URL`` labels is defined by the " +"following Python function:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:65 +msgid "" +"In plain language: a label is *normalized* by deleting all ASCII punctuation " +"and whitespace, and then converting the result to lowercase." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:68 +msgid "" +"The following table shows examples of labels before (raw) and after " +"normalization:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:74 +msgid "Raw" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:75 +#, fuzzy +msgid "Normalized" +msgstr "翻譯" + +#: ../source/specifications/well-known-project-urls.rst:76 +msgid "``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:77 +#: ../source/specifications/well-known-project-urls.rst:79 +#: ../source/specifications/well-known-project-urls.rst:81 +msgid "``homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:78 +msgid "``Home-page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:80 +msgid "``Home page``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:82 +msgid "``Change_Log``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:83 +msgid "``changelog``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:84 +msgid "``What's New?``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:85 +msgid "``whatsnew``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:86 +#: ../source/specifications/well-known-project-urls.rst:87 +msgid "``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:92 +msgid "Well-known labels" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:96 +msgid "" +"The list of well-known labels is a living standard, maintained as part of " +"this document." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:99 +msgid "" +"The following table lists labels that are well-known for the purpose of " +"specializing the presentation of ``Project-URL`` metadata:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:105 +msgid "Label (Human-readable equivalent)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:107 +msgid "Aliases" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:108 +msgid "``homepage`` (Homepage)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:109 +msgid "The project's home page" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:110 +#: ../source/specifications/well-known-project-urls.rst:116 +#: ../source/specifications/well-known-project-urls.rst:122 +msgid "*(none)*" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:111 +msgid "``source`` (Source Code)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:112 +msgid "The project's hosted source code or repository" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:113 +msgid "``repository``, ``sourcecode``, ``github``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:114 +msgid "``download`` (Download)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:115 +msgid "" +"A download URL for the current distribution, equivalent to ``Download-URL``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:117 +msgid "``changelog`` (Changelog)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:118 +msgid "The project's comprehensive changelog" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:119 +msgid "``changes``, ``whatsnew``, ``history``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:120 +msgid "``releasenotes`` (Release Notes)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:121 +msgid "The project's curated release notes" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:123 +msgid "``documentation`` (Documentation)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:124 +msgid "The project's online documentation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:125 +msgid "``docs``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:126 +msgid "``issues`` (Issue Tracker)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:127 +msgid "The project's bug tracker" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:128 +msgid "``bugs``, ``issue``, ``tracker``, ``issuetracker``, ``bugtracker``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:129 +msgid "``funding`` (Funding)" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:130 +msgid "Funding Information" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:131 +msgid "``sponsor``, ``donate``, ``donation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:133 +msgid "" +"Package metadata consumers may choose to render aliased labels the same as " +"their \"parent\" well known label, or further specialize them." +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:137 +msgid "Example behavior" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:139 +msgid "" +"The following shows the flow of project URL metadata from ``pyproject.toml`` " +"to core metadata to a potential index presentation:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:142 +msgid "Example project URLs in standard configuration" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:151 +msgid "Core metadata representation" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:159 +msgid "Potential rendering" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:167 +msgid "" +"Observe that the core metadata appears in the form provided by the user " +"(since metadata *producers* do not perform normalization), but the metadata " +"*consumer* normalizes and identifies appropriate human-readable equivalents " +"based on the normalized form:" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:172 +msgid "``Home page`` becomes ``homepage``, which is rendered as ``Homepage``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:173 +msgid "" +"``DOCUMENTATION`` becomes ``documentation``, which is rendered as " +"``Documentation``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:174 +msgid "" +"``Repository`` becomes ``repository``, which is rendered as ``Source Code``" +msgstr "" + +#: ../source/specifications/well-known-project-urls.rst:175 +msgid "" +"``GitHub`` becomes ``github``, which is rendered as ``Source Code (GitHub)`` " +"(as a specialization of ``Source Code``)" +msgstr "" + +#: ../source/support.rst:3 +msgid "How to Get Support" +msgstr "" + +#: ../source/support.rst:5 +msgid "" +"For support related to a specific project, see the links on " +"the :doc:`Projects ` page." +msgstr "" + +#: ../source/support.rst:8 +msgid "" +"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/creating-documentation.rst:4 +msgid "Creating documentation" +msgstr "" + +#: ../source/tutorials/creating-documentation.rst:6 +msgid "" +"This tutorial has been removed since it is not related to packaging and was " +"unmaintained. Please see the `Sphinx tutorial `_ instead." +msgstr "" + +#: ../source/tutorials/index.rst:4 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:5 +msgid "Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:7 +msgid "" +"This section covers the basics of how to install Python :term:`packages " +"`." +msgstr "" + +#: ../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:24 +msgid "Requirements for Installing Packages" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:26 +msgid "" +"This section describes the steps to follow before installing other Python " +"packages." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:31 +msgid "Ensure you can run Python from the command line" +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:" +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 "" + +#: ../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:62 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:68 +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:" +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 "" + +#: ../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:95 +msgid "Ensure you can run pip from the command line" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:97 +msgid "" +"Additionally, you'll need to make sure you have :ref:`pip` available. You " +"can check this by running:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:112 +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`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:119 +msgid "" +"If ``pip`` isn't already installed, then first try to bootstrap it from the " +"standard library:" +msgstr "" + +#: ../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:136 +msgid "" +"Securely Download `get-pip.py `_ [1]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:139 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:145 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:154 +msgid "Ensure pip, setuptools, and wheel are up to date" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:156 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:173 +msgid "Optionally, create a virtual environment" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:175 +msgid "" +"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: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:199 +msgid "Creating Virtual Environments" +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/tutorials/installing-packages.rst:207 +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." +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/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: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/installing-packages.rst:224 +msgid "" +"Currently, there are two common tools for creating Python virtual " +"environments:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:226 +msgid "" +":doc:`venv ` is available by default in Python 3.3 and " +"later, and installs :ref:`pip` into created virtual environments in Python " +"3.4 and later (Python versions prior to 3.12 also " +"installed :ref:`setuptools`)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:229 +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 " +"installed into created virtual environments by default. Note that " +"``setuptools`` is no longer included by default starting with Python 3.12 " +"(and ``virtualenv`` follows this behavior)." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:234 +msgid "The basic usage is like so:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:236 +msgid "Using :doc:`venv `:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:252 +msgid "Using :ref:`virtualenv`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:268 +msgid "" +"For more information, see the :doc:`venv ` docs or " +"the :doc:`virtualenv ` docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:271 +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)." +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/installing-packages.rst:286 +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" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:295 +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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:301 +msgid "Installing from PyPI" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:303 +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:354 +msgid "" +"To install a version that's :ref:`compatible ` with a certain version: [4]_" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:369 +msgid "" +"In this case, this means to install any version \"==1.4.*\" version that's " +"also \">=1.4.2\"." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:374 +msgid "Source Distributions vs Wheels" +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/installing-packages.rst:382 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:387 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:395 +msgid "Upgrade an already installed ``SomeProject`` to the latest from PyPI." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:412 +msgid "Installing to the User Site" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:414 +msgid "" +"To install :term:`packages ` that are isolated to the " +"current user, use the ``--user`` flag:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:429 +msgid "" +"For more information see the `User Installs `_ section from the pip docs." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:433 +msgid "" +"Note that the ``--user`` flag has no effect when inside a virtual " +"environment - all installation commands will affect the virtual environment." +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`:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:444 +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`_." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:450 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:466 +msgid "" +"Install a list of requirements specified in a :ref:`Requirements File " +"`." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:482 +msgid "Installing from VCS" +msgstr "" + +#: ../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 `." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:506 +msgid "Installing from other Indexes" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:508 +msgid "Install from an alternate index" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:522 +msgid "" +"Search an additional index during install, in addition to :term:`PyPI " +"`" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:538 +msgid "Installing from a local src tree" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:541 +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." +msgstr "" + +#: ../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 "" +"Install from a local directory containing archives (and don't " +"check :term:`PyPI `)" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:609 +msgid "Installing from other sources" +msgstr "" + +#: ../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/installing-packages.rst:623 +msgid "Installing Prereleases" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:625 +msgid "" +"Find pre-release and development versions, in addition to stable versions. " +"By default, pip only finds stable versions." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:641 +#, fuzzy +msgid "Installing \"Extras\"" +msgstr "安裝軟體套件" + +#: ../source/tutorials/installing-packages.rst:643 +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:" +msgstr "" + +#: ../source/tutorials/installing-packages.rst:666 +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." +msgstr "" + +#: ../source/tutorials/installing-packages.rst:675 +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`." +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" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:4 +msgid "Managing Application Dependencies" +msgstr "" + +#: ../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." +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." +msgstr "" + +#: ../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 "" + +#: ../source/tutorials/managing-dependencies.rst:17 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:24 +msgid "" +"For alternatives, see `Other Tools for Application Dependency Management`_." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:27 +msgid "Installing Pipenv" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:29 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:35 +msgid "Use ``pip`` to install Pipenv:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:51 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:62 +msgid "Installing packages for your project" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:64 +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:" +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):" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:109 +msgid "Using installed packages" +msgstr "" + +#: ../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/managing-dependencies.rst:122 +msgid "Then you can run this script using ``pipenv run``:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:128 +msgid "You should get output similar to this:" +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:134 +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``." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:140 +#: ../source/tutorials/packaging-projects.rst:484 +msgid "Next steps" +msgstr "" + +#: ../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/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 "" + +#: ../source/tutorials/managing-dependencies.rst:148 +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``)." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:157 +msgid "Other Tools for Application Dependency Management" +msgstr "" + +#: ../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/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 "" + +#: ../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/managing-dependencies.rst:170 +msgid "" +"`PDM `_ for a modern Python package " +"management relying on standards such as :pep:`517` and :pep:`621`." +msgstr "" + +#: ../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/managing-dependencies.rst:175 +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." +msgstr "" + +#: ../source/tutorials/managing-dependencies.rst:180 +msgid "" +"`uv `__ for a single tool that covers the entire " +"project management workflow, including dependency management, packaging, and " +"publishing." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:2 +msgid "Packaging Python Projects" +msgstr "" + +#: ../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 "" + +#: ../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 "" + +#: ../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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:35 +msgid "A simple project" +msgstr "" + +#: ../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:44 +msgid "Create the following file structure locally:" +msgstr "" + +#: ../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:57 +msgid "" +"Creating the file :file:`__init__.py` is recommended because the existence " +"of an :file:`__init__.py` file allows users to import the directory as a " +"regular package, even if (as is the case in this " +"tutorial) :file:`__init__.py` is empty. [#namespace-packages]_" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:62 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:71 +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 "" + +#: ../source/tutorials/packaging-projects.rst:75 +msgid "" +"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:83 +msgid "Creating the package files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:85 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:103 +msgid "Creating a test directory" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:105 +msgid ":file:`tests/` is a placeholder for test files. Leave it empty for now." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:111 +msgid "Choosing a build backend" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:113 +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:122 +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/packaging-projects.rst:129 +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:134 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:141 +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. The minimum version specified in the above " +"code block is the one that introduced support for :ref:`the new license " +"metadata `." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:150 +msgid "" +"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:153 +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:157 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:167 +msgid "Configuring metadata" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:169 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:196 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:201 +msgid "" +"``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:203 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:206 +msgid "``description`` is a short, one-sentence summary of the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:207 +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 "" + +#: ../source/tutorials/packaging-projects.rst:212 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:215 +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 and is OS-independent. You should always include at least which version(s) " +"of Python your package works on 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:222 +msgid "" +"``license`` is the :term:`SPDX license expression ` of " +"your :term:`Distribution Archive` files." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:224 +msgid "" +"``license-files`` is the list of glob paths to the license files, relative " +"to the directory where :file:`pyproject.toml` is located." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:226 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:229 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:236 +msgid "Creating README.md" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:238 +msgid "" +"Open :file:`README.md` and enter the following content. You can customize " +"this if you'd like." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:251 +msgid "Creating a LICENSE" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:253 +msgid "" +"It's important for every :term:`Distribution Archive` uploaded to the Python " +"Package Index to include a license. This tells users who install " +"your :term:`Distribution Archive` the terms under which they can use it. 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/tutorials/packaging-projects.rst:282 +msgid "" +"Most build backends automatically include license files in packages. See " +"your backend's documentation for more details. If you include the path to " +"license in the ``license-files`` key of :file:`pyproject.toml`, and your " +"build backend supports :pep:`639`, the file will be automatically included " +"in the package." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:290 +msgid "Including other files" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:292 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:299 +msgid "Generating distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:301 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:305 +msgid "Make sure you have the latest version of PyPA's :ref:`build` installed:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:319 +msgid "" +"If you have trouble installing these, see the :doc:`installing-packages` " +"tutorial." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:322 +msgid "" +"Now run this command from the same directory where :file:`pyproject.toml` is " +"located:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:336 +msgid "" +"This command should output a lot of text and once completed should generate " +"two files in the :file:`dist` directory:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:346 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:355 +msgid "Uploading the distribution archives" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:357 +msgid "Finally, it's time to upload your package to the Python Package Index!" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:359 +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`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:367 +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.**" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:374 +msgid "" +"Now that you are registered, you can use :ref:`twine` to upload the " +"distribution packages. You'll need to install Twine:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:389 +msgid "" +"Once installed, run Twine to upload all of the archives under :file:`dist`:" +msgstr "一旦安裝完畢，執行Twine以上載所有於file:" + +#: ../source/tutorials/packaging-projects.rst:403 +msgid "" +"You will be prompted for an API token. Use the token value, including the " +"``pypi-`` prefix. Note that the input will be hidden, so be sure to paste " +"correctly." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:406 +msgid "After the command completes, you should see output similar to this:" +msgstr "當指令完成，你應該可以見到類似以下的輸出內容:" + +#: ../source/tutorials/packaging-projects.rst:417 +msgid "" +"Once uploaded, your package should be viewable on TestPyPI; for example: " +"``https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE``." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:422 +msgid "Installing your newly uploaded package" +msgstr "安裝你那最新上載套件中" + +#: ../source/tutorials/packaging-projects.rst:424 +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/tutorials/packaging-projects.rst:440 +msgid "Make sure to specify your username in the package name!" +msgstr "碓保指明你的帳戶名稱於那個套件名稱裏!" + +#: ../source/tutorials/packaging-projects.rst:442 +msgid "" +"pip should install the package from TestPyPI and the output should look " +"something like this:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:452 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:459 +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:" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:474 +msgid "and import the package:" +msgstr "然後載入那個套件:" + +#: ../source/tutorials/packaging-projects.rst:486 +msgid "" +"**Congratulations, you've packaged and distributed a Python project!** ✨ 🍰 " +"✨" +msgstr "**恭喜，你已經做好套件而且發佈為一個Python頂目出去!**✨ 🍰 ✨" + +#: ../source/tutorials/packaging-projects.rst:489 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:494 +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:" +msgstr "當你真正準備上載一個套件到Python套件索引，你往後可以重複幾次這動作" + +#: ../source/tutorials/packaging-projects.rst:498 +#, fuzzy +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 "" +"為你的套件選擇一個稔熟且獨特的名字。由於你已經在教學中做了一次，所以你不用在" +"此再加上你的用戶名稱。" + +#: ../source/tutorials/packaging-projects.rst:500 +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." +msgstr "於https://pypi.org網址內登記一個帳戶-謹記這是兩個截然不同的伺服器和" + +#: ../source/tutorials/packaging-projects.rst:503 +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." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:507 +msgid "" +"Install your package from the real PyPI using ``python3 -m pip install [your-" +"package]``." +msgstr "" +"使用 ``python3 -m pip install [your-package]`` 以從真正的PyPI安裝您的套件。" + +#: ../source/tutorials/packaging-projects.rst:509 +msgid "" +"At this point if you want to read more on packaging Python libraries here " +"are some things you can do:" +msgstr "此時，如果您想閱讀有關打包 Python 庫的更多信息，您可以執行以下操作：" + +#: ../source/tutorials/packaging-projects.rst:512 +msgid "" +"Read about advanced configuration for your chosen build backend: `Hatchling " +"`_, :doc:`setuptools `, :doc:`Flit `, `PDM `_." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:516 +msgid "" +"Look at the :doc:`guides ` on this site for more advanced " +"practical information, or the :doc:`discussions ` for " +"explanations and background on specific topics." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:519 +msgid "" +"Consider packaging tools that provide a single command-line interface for " +"project management and packaging, such " +"as :ref:`hatch`, :ref:`flit`, :ref:`pdm`, and :ref:`poetry`." +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:527 +msgid "Notes" +msgstr "" + +#: ../source/tutorials/packaging-projects.rst:529 +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)." +msgstr "" + +#, fuzzy +#~ msgid "" +#~ "https://datatracker.ietf.org/doc/html/draft-jones-json-web-signature-json-" +#~ "serialization-01" +#~ msgstr "http://self-issued.info/docs/draft-jones-jose-json-private-key.html" + +#, fuzzy +#~ msgid "" +#~ "https://datatracker.ietf.org/doc/html/draft-jones-jose-json-private-key-01" +#~ msgstr "http://self-issued.info/docs/draft-jones-jose-json-private-key.html" + +#, fuzzy +#~| msgid "Project name" +#~ msgid "**Inspiration**: :ref:` pyproject-tool-table`" +#~ msgstr "專案名稱" + +#~ msgid "List keywords that describe your project." +#~ msgstr "列出描述您的項目的關鍵字。" + +#, fuzzy +#~ msgid "``project_urls``" +#~ msgstr "project_urls" + +#~ msgid "Comparison to .egg" +#~ msgstr "與 .egg 的比較" + +#~ msgid "Read about :doc:`/guides/packaging-binary-extensions`." +#~ msgstr "閱讀 :doc:`/guides/packaging-binary-extensions`。" + +#, fuzzy +#~ msgid "" +#~ "https://self-issued.info/docs/draft-ietf-jose-json-web-signature.html" +#~ msgstr "http://self-issued.info/docs/draft-ietf-jose-json-web-key.html" + +#, fuzzy +#~ msgid "https://self-issued.info/docs/draft-ietf-jose-json-web-key.html" +#~ msgstr "http://self-issued.info/docs/draft-ietf-jose-json-web-key.html" + +#~ msgid "2014-11-11" +#~ msgstr "2014-11-11" + +#~ msgid "keywords" +#~ msgstr "keywords"